polylane

Polylane Platform

Polylane はエージェントを活用した本番運用プラットフォームです。スタックのライブコンテキストグラフを構築し、テレメトリから問題を検出して、エージェントで調査し、取り消し可能な操作とレビュー済みのプルリクエストを通じて修正します。

このファイルではプロセスと規約を説明します。カタログ、スキーマ、制限は含まれていません。これらにはすべて最新の情報源があります。引用する前に取得してください。

Retrieval Sources

情報源	取得方法	用途
Polylane docs	https://docs.polylane.com — エージェント向けインデックスは /llms.txt、各ページの生 Markdown は /raw/<path>.md	概念、機能の動作、スキーマ
Docs MCP	https://docs.polylane.com/mcp — list-pages、get-page（認証不要）	同じ内容をツールとして取得
Platform MCP	https://mcp.polylane.com/mcp	ワークスペースのライブクエリ：グラフ、テレメトリ、コード
CLI help	polylane --help、polylane <resource> <verb> --help	インストール済みバージョンのコマンド一覧
API	https://api.polylane.com/v1/reference；polylane api list / api describe <op>	すべての REST 操作とそのスキーマ
Public catalogs	GET /v1/public/integrations/catalog、GET /v1/public/billing/plans（認証不要）；GET /v1/scopes（認証が必要）	インテグレーションの種類、プランと制限、スコープ

The Four-Step Loop

Context ──▶ Detection ──▶ Investigation ──▶ Remediation
(connect)   (find issues)  (root-cause)      (fix + prevent)

すべてのプリミティブは、いずれか1つのステップに属します。ドキュメントのセクションもこれに対応しています：/connect、/detect、/investigate（調査と修正）。

概念	一言で説明
Workspace	テナントの単位であり、以下のすべてがワークスペースのスコープに属します
Context graph	ノード（リソース）と型付きエッジ（deploys_to、connects_to、invokes、…）で構成され、クラウド同期とインテグレーションによってデータが取り込まれます
Issue	1件の検出記録（Polylane のチェックまたはプロバイダーのアラート）です。フィンガープリントによって重複排除されます。未解決のイシューに一致すると更新され、過去24時間以内に解決されたイシューに一致すると重複ではなく再オープンします。トリアージの判定は Incident / No incident です
Thread	エージェントの実行記録を永続的に保存したトランスクリプトです。調査とチャットはそれぞれ1つのスレッドになります
Investigation	確認済みのイシューに対する修正実行です。1つのエージェントスレッドが判定を下し、原因を追跡して、修正可能な場合は PR を作成します
Autofix	エージェントが作成する修正です。直接プッシュされることはなく、必ずプルリクエストとして作成されます
Memory	保存された確認済みの調査結果で、今後のエージェント実行で再表示されます

Connecting a Stack

次の順に接続します。各段階で次の機能が利用可能になります。

1. クラウド1つとオブザーバビリティツール1つ → グラフにデータが取り込まれ、検出が始まります。カタログ（polylane integration catalog または GET /v1/public/integrations/catalog）で接続可能なものを確認し、推奨する前にユーザーのリポジトリにプロバイダー設定ファイルがあるか調べます。
2. コードホスト（GitHub） → PR の変更に関するインテリジェンス、コードを考慮した調査、自動修正が利用可能になります。
3. チャット（Slack） → メッセージのトリガーと結果の送信先が利用可能になります。

接続方法（プロバイダーごとのフラグは polylane integration connect --help / cloud connect --help を参照）：

• AWS — 読み取り専用ロールを作成する CloudFormation スタックを使用します。キーは保存されません。
• GitHub、Sentry、Vercel、Slack — アプリのインストールにブラウザーを使用します。対話型ターミナルでは CLI がインストールを待機しますが、--output json、--non-interactive、または TTY がない場合は、インストールの完了時ではなく URL が出力された時点で終了コード 0 を返します。その後、インストールを確認してください。
• ほとんどのオブザーバビリティツールとクラウド — API トークンを使用します。
• 任意の MCP サーバー — インテグレーションとして接続でき、そのツールをエージェントが利用できるようになります。

推測せずに確認してください： integration list、cloud list、続けて service list を実行します。リソースが表示されれば、最初の同期が成功しています。何もない状態からエージェント主導でオンボーディングする場合（アカウント → ワークスペース → API キー → MCP → クラウド）は、https://polylane.com/for-agents に従ってください。

Polylane を使った調査

インターフェースにかかわらず、同じ方法で調査できます（ここでは CLI コマンドを示していますが、プラットフォーム MCP の runTool からも同じ機能を利用できます）。

1. 起点を確認する — すでにフラグが付いていますか？ issue show <id> と issue timeline <id> を確認します。症状しかわかりませんか？ service find "<query>" でリソースを探します。まだ何もありませんか？ issue list --active を実行します。
2. まず何が変わったかを確認する — インシデントの多くは変更の後に発生します。feed list --category change|release --since 24h を実行します。
3. 影響を受けたサービスの証拠を集める — service logs <id> --since 1h --grep error、service metrics <id> --since 1h、影響範囲を把握するには service graph <id> --direction both を実行します。
4. コードと関連付ける — repo grep <repo> "<pattern>"、repo read <repo> <path> を実行します。
5. 必要に応じて、固定された範囲を超えて調べる — tools search "<capability>" の後に tools run <name> を実行すると、接続されたスタックがサポートするプロバイダー固有のクエリ（CloudWatch、Datadog、Honeycomb など）を実行できます。
6. 調査しながら記録する — 実施した対応は issue note に、状態の変化（「Mitigated」など）は issue milestone に記録します。確認済みの事実のみ memory save に保存します。メモリーは以降のすべての実行で参照されます。
7. 役立つ場合は引き継ぐ — thread ask "<question>" --context <ids> を実行すると、蓄積したコンテキストを Polylane 自身のエージェントに渡せます（ID にはプレフィックスによる型指定があります。以下を参照）。

根本原因、または証拠に裏付けられた有力な仮説が見つかり、issue に記録されていれば調査完了です。

変更前に本番環境への影響を確認する

稼働中のシステムに関わるコードを編集またはリリースする前に、グラフを使って影響範囲を確認します。

1. 変更を本番環境に対応付ける — このコードが提供するリソースはどれですか？ service find "<name>"、またはリポジトリの deploys_to エッジ（repo show、tools run findNodes）を確認します。
2. 影響範囲を確認する — service graph <id> --direction inbound を実行し、変更対象に依存するすべてのリソースを確認します。
3. すでに劣化していませんか？ — サービスで絞り込んだ issue list --active を確認します。未解決のインシデントに変更を投入しないでください。
4. ほかに進行中の変更はありますか？ — feed list --category change|release --since 24h を実行します。まだ安定していないデプロイに変更を重ねるのは避けてください。
5. 監視しながらリリースする — Polylane は deploys_to エッジをたどり、PR に本番環境への影響を自動的にコメントします。
6. デプロイ後に確認する — デプロイ前のベースラインと比較しながら service logs／service metrics --since <deploy> を確認し、フィード内のデプロイの変更記録も確認します。

インターフェース

├─ Terminal / scripts / CI → polylane CLI (see polylane-cli skill)
├─ Coding agent → platform MCP or CLI; wire both with `polylane setup`
├─ Programmatic → REST API (api.polylane.com/v1)
├─ No account yet → `polylane auth signup`, or hand any coding agent
│  https://polylane.com/for-agents to onboard from scratch
└─ Humans → console.polylane.com (every API object carries a _html_url deep link)

The Platform MCP：6 つのツールで、すべてにアクセス

https://mcp.polylane.com/mcp（ストリーミング可能な HTTP。動的クライアント登録を使う OAuth、またはヘッドレス環境向けの x-api-key）。接続されているものの数にかかわらず、固定の 6 つのツールを提供します（以下の 5 つに加え、サーバーで発生した問題を報告する reportFeedback）。機能ごとに MCP ツールを 1 つずつ用意するのではなく、Polylane のバックエンドでコードを実行し、そこで全機能にアクセスできます。

ツール	機能
searchTools	ワークスペースのエージェントツールとそのスキーマを検出します。Polylane 独自のエージェントが使用するツールと同じものです（接続されているすべてのプロバイダーにわたるオブザーバビリティクエリ、グラフのトラバース、コード検索、デプロイ、監査ログ）。最初に呼び出してください。一覧は認証情報に合わせて絞り込まれます。
runTool	エージェントツールを正確な名前で 1 つ実行します。引数は、スキーマに一致するネストされた params オブジェクトとして指定します。
runCode	パラメーターを持たない非同期 TypeScript アロー関数をバックエンドで実行します。ここでは、各エージェントツールを await tools.<name>(args) として呼び出せます（tools.__describe(["name"]) で型を取得します）。複数のツール呼び出しが必要なタスクでは、常にこれを使用してください。
search	Polylane の OpenAPI 仕様（$ref は解決済み）を、サンドボックスのグローバル codemode.spec() を使うパラメーターなしの非同期アロー関数で検索します。
execute	任意の REST 操作を codemode.request({ method, path, query, body }) で呼び出します。エンドポイントは先に search で見つけてください。

コード実行が重要な理由： N 回のツール呼び出しの連鎖を 1 回のラウンドトリップで実行でき、中間データ（ログ行、ノード一覧、仕様全体）はバックエンドに保持されます。コードが返す内容だけがコンテキストに入り、大きな結果は切り詰められます。そのため、コード内でフィルタリング、結合、集計を行い、要約を返してください。

async () => {
  const types = await tools.__describe(["findNodes"]);  // exact input/output types
  const nodes = await tools.findNodes({ query: "checkout" });
  // ...chain further tools.<name>() calls on the results here...
  return nodes;  // return only what you need in context
}

書き込みの制御： 書き込みには agent_tools:write スコープと x-polylane-allow-writes: true ヘッダーの両方が必要です。いずれの場合も、すべての書き込みは安全性モデルによる審査を受けます。エリシテーションに対応するクライアントには承認プロンプトが表示されます。OAuth セッションは複数のワークスペースにまたがることができます。呼び出しごとに workspaceId（ID またはスラッグ）を渡してください。API キーは 1 つのワークスペースに紐付けられているため、省略してください。

参照情報からは分からない規約

REST。 list/get/patch/delete では workspaceId をパス（/v1/{resource}/{workspaceId}[/{id}]）に指定します。create は POST /v1/{resource} で、workspaceId はパスではなく本文に指定します。パスと本文で異なるワークスペースを指定する POST は 403 になります。レスポンスは success、result、error でラップされます。プラン上限による拒否は HTTP 402（application/problem+json）で、超過した項目が示されます。単一オブジェクトには _html_url（コンソールへのディープリンク）と _links（次の操作）が含まれます。パスを推測するのではなく、_links をたどってください。

ID にはプレフィックスで型が付けられています — プレフィックスからリソースの種類を判別します（CLI の --context は repo_、acc_、thrd_、mem_ を認識し、それ以外はリソースノードとして扱います）。ws_ はワークスペース、usr_ はユーザー、thrd_ はスレッド、iss_ は課題、acc_ はクラウドアカウント、int_ はインテグレーション、repo_ はリポジトリ、mem_ はメモリ、fix_ は自動修正、ask_ はエスカレーション、art_ はアーティファクト、sk_ は API キーです。

スコープは resource:action 形式の文字列です（issues:read、agent_tools:write）。GET /v1/scopes で一覧を取得できます。CLI の OAuth ログインは、デフォルトで agent_tools:read と agent_tools:write を要求します。書き込みツールに使う API キーには agent_tools:write が必要です。

安全性モデル（自律性の調整）

1. デフォルトは読み取り専用 — クラウドアカウントは読み取り専用で接続されます。ワークスペース管理者が読み取り専用をオフにするまでは、書き込みは拒否されます。
2. 取り消し可能な操作 — 有効にすると、再起動やデプロイのロールバックが可能になります。すべての書き込みは安全性審査を受けます。Polylane 内での書き込みは、人が参加しているターン（チャット）で、明示的な確認を得た場合にのみ行われます。無人のバックグラウンド実行は読み取り専用です。Platform MCP での書き込みには、上記のオプトインが必要です。
3. 審査で保護されたコード — エージェントがデフォルトブランチにプッシュすることはありません。修正は PR として作成され、CI と人による承認を経ます。