coordinating-multi-space-devops-agent

複数の AgentSpaces へのクエリ

事前確認

aws_devops_agent__list_agent_spaces が利用可能なツールにない場合、リモート MCP サーバーに接続されていません。「AWS DevOps Agent のセットアップを手伝って」と依頼するようユーザーに伝えてください。そうすると、setup-devops-agent スキルが自動的に読み込まれます。

前提条件：SigV4 認証が必要です

複数スペースへのルーティングにはSigV4 認証が必要です。Bearer トークンは単一の AgentSpace にスコープされており、他のスペースにはルーティングできません。

実際には、多くのチームが複数の AgentSpaceを運用しています。通常は、本番スペース、ステージングスペース、そしてアカウント間で共有するランブックを保管する専用の「ナレッジ」スペースです。各スペースには、それぞれ関連付けられた AWS アカウント、ランブック、履歴があります。

このスキルはルーティングの中核です。ユーザーが複数のスペースを設定している場合や、質問が実際に複数のアカウントにまたがる場合に使用します。

スペースの検出

aws_devops_agent__list_agent_spaces()
→ {"agentSpaces": [{"agentSpaceId": "as-abc123", "name": "prod"}, ...]}

スペースが 1 つだけ返された場合、このスキルは適用されません。chatting-with-aws-devops-agent または investigating-incidents-with-aws-devops-agent を直接使用してください（agent_space_id は不要です）。

複数のスペースが返された場合、ユーザーの質問が次のどれに当たるかを判断します。

質問の種類	戦略
1 つの環境に限定される（「本番環境で問題が起きている」）	単一スペース — 該当するスペースを選択
複数の環境にまたがる（「本番環境とステージング環境を比較して」）	並列 — 各スペースにクエリし、結果を統合
一般的なナレッジ（「ECS のランブックはありますか？」）	「ナレッジ」という名前のスペースがあれば、そこにルーティング
曖昧（「サービスが遅い」）	ユーザーに確認 — 推測で判断しない

セッションごとのルーティングメモリ

ユーザーがローカルにルーティングガイド（例：.claude/aws-agents-for-devsecops.md、AGENTS.md、プロジェクトごとのメモ）を保存している場合は、セッションの開始時に一度読み込み、その後の会話ではルーティング表として使用します。想定される形式：

| Space | AWS Profile | Agent Space ID | Purpose |
|-------|-------------|----------------|---------|
| prod  | acme-prod   | as-abc123      | Production incidents, customer-facing services |
| stage | acme-stage  | as-def456      | Pre-prod validation, integration testing |
| kb    | acme-shared | as-ghi789      | Shared runbooks, cross-account knowledge |

ガイドがない場合は、次の手順で検出します。

1. aws_devops_agent__list_agent_spaces() → すべてのスペースを取得します。
2. 各スペースについて：aws_devops_agent__chat(message="Summarize the AWS accounts, services, and runbooks you have access to.", agent_space_id="<SPACE_ID>") → 1 段落の概要を取得します。
3. 今後のセッションで検出を省略できるよう、ルーティングガイドをプロジェクト（例：.claude/aws-agents-for-devsecops.md、AGENTS.md、プロジェクトごとのメモ）に書き込むことを提案します。

パターン A — 並列クエリと回答の統合

ユーザーが比較を求めている場合に使用します。「本番環境とステージング環境のエラー率を比較して」「この問題は両方のアカウントで発生していますか？」「すべての環境のコストを監査して」などが該当します。

# 1. Query each space in parallel with environment-specific context
aws_devops_agent__chat(message="<question> | env=prod | <prod IaC context>", agent_space_id="PROD_ID")
→ {"executionId": "...", "answer": "..."}

aws_devops_agent__chat(message="<question> | env=stage | <stage IaC context>", agent_space_id="STAGE_ID")
→ {"executionId": "...", "answer": "..."}

# 2. Synthesize locally — present a side-by-side summary, not two separate dumps

両方の回答をそのまま貼り付けるだけではいけません。 両方を読み、共通点と相違点を見極めて、ユーザーに差分を伝えてください。そこに価値があります。

パターン B — ナレッジを参照してから、スペースごとに対応

あるスペースにあるランブックやナレッジが、別のスペースでの作業に役立つ場合に使用します。

# 1. Ask the knowledge space first
aws_devops_agent__chat(
    message="What's our standard runbook for ECS 503 errors?",
    agent_space_id="KB_ID"
)
→ {"answer": "<runbook text>"}

# 2. Apply that runbook in the target environment
aws_devops_agent__investigate(
    title="ECS 503 errors on checkout-service. [Runbook from knowledge space] <runbook text> [Local context] ...",
    agent_space_id="PROD_ID",
    priority="HIGH"
)

DevOps Agent はスペース間で状態を共有しません。ナレッジスペースの回答を調査の title に引用して、スペース間の橋渡しをします。

パターン C — 対象を絞った単一スペースへのクエリ

ユーザーがスペースまたは環境を明示している場合に使用します。

# Pick the matching agentSpaceId from your routing memory, pass it on the call
aws_devops_agent__chat(message="<question>", agent_space_id="<matched_space_id>")

ルーティング先が曖昧でユーザーが明示していない場合は、一度だけ確認してください。誤ったアカウントにクエリを送るよりも適切です。

パターン D — 調査間で状態は共有されません

調査はスペースごとに行われます。問題が複数のアカウントにまたがる場合は、2 つの調査が必要になることがあります。

aws_devops_agent__investigate(title="Latency spike — prod side", agent_space_id="PROD_ID", priority="HIGH")
aws_devops_agent__investigate(title="Latency spike — stage side", agent_space_id="STAGE_ID", priority="HIGH")

両方の taskId を追跡してください。両方をポーリングし、調査結果をまとめて提示してください。

これはまれなケースです。通常は、1 つのスペースが問題を担当します。デフォルトで対象を広げないでください。

してはいけないこと

• あらゆる質問を、すべてのスペースに一斉に投げないでください。 時間とコストがかかり、ユーザーは3倍の量の出力を読むことになります。
• 対象範囲を確認せず、複数のスペースに問い合わせないでください。 スペースの description や記録された対応範囲に関連するサービスが記載されていない場合は、そのスペースをスキップしてください。対象範囲が合わないスペースに質問を送ると、「わかりません」と返すのではなく、通常は応答が停止します。
• 原則として、調査を並行して開始しないでください。 それぞれに5～8分かかります。インシデントを担当するスペースを1つ選んでください。
• 会話の途中で、黙ってスペースを切り替えないでください。 フォローアップに別のスペースが必要な場合は、ユーザーに「ランブックを確認するため、ナレッジスペースに切り替えます」と伝えてください。

タイムアウトに関するガイダンス

chat ツールは、応答全体をサーバー側でバッファリングしてから返します。複数のアカウントをまたぐ複雑なクエリでは、スペースごとに30～90秒かかることがあります。90秒以内に応答しない場合は、対象範囲が合っていない可能性が高いため、「スペースXは90秒以内に応答しませんでした。スキップします（対象範囲が合っていない可能性があります）」のようなメッセージを表示し、応答を待ち続けずに先へ進んでください。

関連項目

• examples/multi-space-walkthrough.md には、ステージング環境との比較とナレッジスペースでのランブック検索を含む、本番インシデントの詳細なシナリオが記載されています。
• setup-devops-agent スキルでは、複数の AgentSpaces、AWS プロファイル、シェルラッパーを初めて設定する手順を説明しています。