---
id: a2a
title: 外部エージェント連携（A2A 認可サーバー）
category: advanced
order: 230
keywords: [A2A, エージェント連携, OAuth2, 認可サーバー, 外部エージェント, クライアント登録, 委任, agent-to-agent]
---

# 外部エージェント連携（A2A 認可サーバー）

MAESTRO には、外部エージェントやサービスがあなたのワークスペースにアクセスするための OAuth2 認可サーバーが組み込まれています。Agent-to-Agent（A2A）連携の土台となる機能です。

> **既定は無効です。** 利用するには管理者が `config.yaml` で `a2a.enabled: true` を設定してください。

## A2A 認可サーバーとは

外部のエージェントや自動化ツールがあなたのワークスペースに代わって操作を行うには、あなたの同意を得た上でアクセストークンを取得する必要があります。この仕組みを管理するのが A2A 認可サーバーです。

OAuth2 の標準フロー（認可コード + PKCE）をベースにしており、信頼できるクライアントだけがアクセスできるよう設計されています。

## 管理者の作業：クライアントを登録する

外部エージェントを接続するには、まず管理者がそのクライアントを登録する必要があります。

**設定 → 管理 → A2A クライアント** から操作できます。

| 項目 | 内容 |
|------|------|
| クライアント名 | 分かりやすい表示名（例: 「集計ボット」） |
| リダイレクト URI | 外部エージェント側が受け取るコールバック URL |
| スコープ | 付与する操作範囲（`tasks:read` / `tasks:write` など） |

登録するとクライアント ID が発行されます。シークレットは登録直後にのみ表示されるので、すぐ控えてください。

## ユーザーの作業：委任に同意・取り消しをする

外部エージェントがアクセスを要求すると、あなたの画面に同意ページが表示されます。内容を確認して「許可」すると、そのエージェントはあなたに代わって指定のスコープ内で操作できるようになります。

### 設定 → A2A 委任 から一覧・取り消し

**設定 → A2A 委任** を開くと、自分が過去に承認した委任の一覧が表示されます。各行には次の情報が確認できます。

| 項目 | 内容 |
|------|------|
| クライアント名 | 委任を受けた外部エージェントの名前 |
| スペース | アクセスを許可したスペース |
| スキル | 実行を許可したスキル（ピース） |
| 付与日時 | 委任を承認した日付 |
| 有効期限 | トークンの有効期限（期限なしの場合はその旨表示） |
| ステータス | 有効（Active）または取り消し済み（Revoked） |

**取り消し手順：**

1. 取り消したい委任の行にある「取り消す」ボタンをクリックします。
2. 確認ボタン（「取り消しを確定」）が表示されるので、再度クリックします。
3. 取り消しは即座に反映されます。そのトークンは無効になり、その委任のもとで実行中だったタスクがあればキャンセルされます。

一度取り消した委任は元に戻せません。外部エージェントが再度アクセスするには、最初から認可フローをやり直す必要があります。

## Agent Card と公開スキル

外部エージェントが MAESTRO に接続する際、最初に **Agent Card**（`.well-known/agent.json`）を取得します。Agent Card はこのサーバーへの接続情報を記述した文書で、外部エージェントはここから認証フローを開始します。

カードには「公開版」と「委任スコープ付き版」の2種類があります。

| カード種別 | 内容 |
|-----------|------|
| 公開版（認証なし） | サーバーの接続情報のみ。ユーザー固有の情報は含まない |
| 委任版（認証あり） | 委任に同意したスペース・スキルだけが記載される |

### スペース単位の公開スキル設定

スペースのオーナーは、そのスペースで外部エージェントに公開するスキル（ピース）を選べます。**設定 → ワークスペース → A2A 公開スキル** で選択できます。

- 選択したスキルだけが委任版 Agent Card に含まれます
- 未選択のスペースはすべて非公開扱いです
- 外部エージェントが見えるのは、ユーザーが委任に同意し、かつオーナーが公開設定したスペース・スキルの範囲だけです

## 有効化の設定

`config.yaml` に以下を追加してください。

```yaml
a2a:
  enabled: true
```

その他のオプション（トークン有効期限・セッション鍵など）は AGENTS.md または管理者向け設定ドキュメントを参照してください。

## スキルの実行と結果の受け取り

同意を得た外部エージェントは、委任されたスコープ内のスキルを呼び出してタスクを実行できます。

外部エージェントがスキルをリクエストすると、MAESTRO はあなたの代わりに対象スペース内でマッチするピースを起動します。実行の進捗はリクエスト側に順次ストリーミングされ、完了後は実行結果とファイル（Artifact）を受け取れます。

| 段階 | 内容 |
|------|------|
| リクエスト | 外部エージェントが委任トークンを添えてスキルを指定する |
| 実行 | 委任スコープを再確認後、対象スペース内でピースを起動する |
| 進捗 | 実行状況をストリーミングで順次返す |
| 完了 | 実行結果と出力ファイル（Artifact）を返却する |

委任スコープ外のスキルはリクエストされても実行されません。

### 長いタスクを非ブロッキングで依頼する

時間のかかるタスクは、接続を張り続けずに依頼できます。`message/send` に `configuration.blocking: false` を付けると、MAESTRO はタスクを受け付けた時点（`submitted` / `working`）で**即座に応答を返します**。完了を待たないので、接続を保持し続ける必要はありません。

結果は後から `tasks/get`（`params.id` にタスク ID を指定）で取得します。タスクが完了していれば `completed` 状態と出力ファイル（Artifact）が返り、まだ実行中なら現在の状態が返ります。ブリッジ側は裏側でジョブの状態を追い続け、切断や再起動をまたいでもタスクを最終状態まで収束させます。

| 段階 | 内容 |
|------|------|
| 依頼 | `configuration.blocking: false` を付けて `message/send` |
| 即応 | 受付時点の非終了状態（`submitted` / `working`）がすぐ返る |
| 取得 | 後から `tasks/get` で最新状態・結果を取得する |

> `tasks/resubscribe` は現在、**その時点の最新状態を返すだけ**です。切断後に進捗ストリームを途中から再開することはできません（進捗を追う場合は `tasks/get` でポーリングしてください）。

## 委任ごとのリソース制限

A2A 経由で接続した外部エージェントには、委任ごとにリクエストレート・同時実行数・ペイロードサイズ・ストリーム時間・スキル実行予算の制限が適用されます。サーバーへの過負荷を防ぎ、複数の委任が公平にリソースを使えるようにするための仕組みです。デフォルト値でも問題なく動作しますが、環境に合わせて調整したい場合は管理者が `config.yaml` の `a2a.limits` セクションを編集してください。

## 注意事項

- 外部エージェントに付与するスコープは必要最小限にしてください。
- クライアントシークレットは安全に管理し、外部に漏らさないでください。
