A2A Agent Card の設計

エージェントのアイデンティティ、スキル、認証要件、および他のエージェントによる発見を可能にする機能を宣言する、標準準拠の A2A Agent Card を作成します。

適用場面

• 他の A2A 準拠エージェントから発見可能にする必要があるエージェントを構築する場合
• マルチエージェント オーケストレーション用にエージェントの機能を公開する場合
• 既存のエージェントを A2A (Agent-to-Agent) プロトコルに移行する場合
• 実装前にエージェントの公開契約を定義する場合
• Agent Card を利用するエージェント レジストリまたはディレクトリと統合する場合

入力

• 必須: エージェントの名前と説明
• 必須: エージェントが実行できるスキルのリスト (名前、説明、入出力スキーマ)
• 必須: エージェントをホストするベース URL
• オプション: 認証方法 (none、oauth2、oidc、api-key)
• オプション: text/plain 以外のサポート対象コンテンツタイプ (例: image/png、application/json)
• オプション: 機能フラグ (ストリーミング、プッシュ通知、状態遷移履歴)
• オプション: プロバイダー組織の名前と URL

手順

ステップ 1: エージェントのアイデンティティと説明を定義する

1.1. エージェント アイデンティティ フィールドを選択します:

{
  "name": "data-analysis-agent",
  "description": "Performs statistical analysis, data visualization, and report generation on tabular datasets.",
  "url": "https://agent.example.com",
  "provider": {
    "organization": "Example Corp",
    "url": "https://example.com"
  },
  "version": "1.0.0"
}

1.2. 以下の内容に答える明確で実行可能な説明を記述します:

• このエージェントはどのドメインをカバーしていますか?
• どのような種類のタスクを処理できますか?
• その制限は何ですか?

1.3. Agent Card を /.well-known/agent.json で提供する標準的な URL を設定します。

予想される結果: 名前、説明、URL、プロバイダー、バージョンを含む完全なアイデンティティ ブロック。

失敗処理: エージェントが複数のドメインにサービスを提供する場合、1 つのエージェントで複数のスキルを持つか、複数のエージェントで焦点を絞ったスコープを持つかを検討します。A2A は明確な境界を持つ焦点を絞ったエージェントを推奨します。

ステップ 2: 入出力スキーマを含むスキルを列挙する

2.1. エージェントが実行できる各スキルを定義します:

{
  "skills": [
    {
      "id": "analyze-dataset",
      "name": "Analyze Dataset",
      "description": "Run descriptive statistics, correlation analysis, or hypothesis tests on a CSV dataset.",
      "tags": ["statistics", "data-analysis", "csv"],
      "examples": [
        "Analyze the correlation between columns A and B in my dataset",
        "Run a t-test comparing group 1 and group 2"
      ],
      "inputModes": ["text/plain", "application/json"],
      "outputModes": ["text/plain", "application/json", "image/png"]
    },
    {
      "id": "generate-chart",
      "name": "Generate Chart",
      "description": "Create bar, line, scatter, or histogram charts from tabular data.",
      "tags": ["visualization", "charts"],
      "examples": [
        "Create a scatter plot of height vs weight",
        "Generate a histogram of the age column"
      ],
      "inputModes": ["text/plain", "application/json"],
      "outputModes": ["image/png", "image/svg+xml"]
    }
  ]
}

2.2. 各スキルについて、以下を提供します:

• id: 一意の識別子 (ケバブケース)
• name: 人間が読みやすい表示名
• description: スキルが何を実行するかの説明 (1 〜 2 文)
• tags: 発見用の検索可能なキーワード
• examples: このスキルをトリガーする自然言語タスクの例
• inputModes: スキルが受け入れる MIME タイプ
• outputModes: スキルが生成できる MIME タイプ

2.3. スキルの境界が明確で重複していないことを確認します。各タスクは正確に 1 つのスキルにマップする必要があります。

予想される結果: id、name、description、tags、examples、I/O モードを持つ各エントリを含むスキル配列。

失敗処理: スキルが大幅に重複している場合は、より多くの例を含む 1 つのより広いスキルにマージします。スキルが広すぎる場合は、焦点を絞ったサブスキルに分割します。

ステップ 3: 認証を構成する

3.1. デプロイメント コンテキストに基づいて認証スキームを定義します:

認証なし (ローカル/信頼されたネットワーク):

{
  "authentication": {
    "schemes": []
  }
}

OAuth 2.0 (本番環境では推奨):

{
  "authentication": {
    "schemes": ["oauth2"],
    "credentials": {
      "oauth2": {
        "authorizationUrl": "https://auth.example.com/authorize",
        "tokenUrl": "https://auth.example.com/token",
        "scopes": {
          "agent:invoke": "Invoke agent skills",
          "agent:read": "Read task status"
        }
      }
    }
  }
}

API キー (シンプルな共有秘密):

{
  "authentication": {
    "schemes": ["apiKey"],
    "credentials": {
      "apiKey": {
        "headerName": "X-API-Key"
      }
    }
  }
}

3.2. デプロイメント環境に最小限の実行可能な認証を選択します:

• ローカル開発: none
• 内部サービス: apiKey
• 公開されているエージェント: oauth2 または oidc

3.3. Agent Card のプロバイダー セクションまたは外部ドキュメントでトークン/キーのプロビジョニング プロセスを文書化します。

予想される結果: デプロイメント セキュリティ要件に一致する認証ブロック。

失敗処理: OAuth 2.0 インフラストラクチャが利用できない場合は、API キー認証で開始して移行を計画します。none 認証で公開エージェントをデプロイしないでください。

ステップ 4: 機能を指定する

4.1. エージェントがサポートするプロトコル機能を宣言します:

{
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": true
  }
}

4.2. 実装準備状況に基づいて各機能フラグを設定します:

• streaming: エージェントが tasks/sendSubscribe を介した SSE ストリーミングをサポートしている場合は true。長時間実行タスクのリアルタイム進捗更新を有効にします。
• pushNotifications: タスク状態の変更時にエージェントが Webhook コールバックを送信できる場合は true。エージェントが Webhook URL を保存してコールバックする必要があります。
• stateTransitionHistory: エージェントがタスク状態遷移 (送信済み、実行中、完了など) の完全な履歴を保持している場合は true。監査証跡に役立ちます。

4.3. 実装が完全にサポートしている場合のみ、機能を true に設定します。サポートされていない機能を宣言すると相互運用性が破損します。

予想される結果: 実装と一致するブール値フラグを含む機能オブジェクト。

失敗処理: 機能が実装されるかどうか不確定な場合は、false に設定します。機能は将来のバージョンで追加できます。機能を削除することは重大な変更です。

ステップ 5: Agent Card の検証と公開

5.1. 完全な Agent Card を組み立てます:

{
  "name": "data-analysis-agent",
  "description": "Performs statistical analysis and visualization on tabular datasets.",
  "url": "https://agent.example.com",
  "version": "1.0.0",
  "provider": {
    "organization": "Example Corp",
    "url": "https://example.com"
  },
  "authentication": {
    "schemes": ["oauth2"],
    "credentials": { ... }
  },
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": true
  },
  "skills": [ ... ],
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"]
}

5.2. Agent Card を検証します:

• JSON として解析し、構文エラーがないことを確認します
• すべての必須フィールド (name、description、url、skills) が存在することを確認します
• 各スキルに id、name、description、および少なくとも 1 つの入出力モードがあることを確認します
• URL に到達可能で、/.well-known/agent.json で card を提供していることを確認します

5.3. Agent Card を公開します:

• https://<agent-url>/.well-known/agent.json で提供します
• Content-Type: application/json を設定します
• クロスオリジン発見が必要な場合は CORS ヘッダーを有効にします
• 関連するエージェント ディレクトリまたはレジストリに登録します

5.4. カードをフェッチして発見をテストします:

curl -s https://agent.example.com/.well-known/agent.json | python3 -m json.tool

予想される結果: 既知の URL で提供される有効な JSON Agent Card。すべての A2A クライアントで解析可能です。

失敗処理: JSON 検証に失敗した場合は、JSON リンターを使用して構文エラーを特定します。URL に到達不可の場合は、DNS、SSL 証明書、および Web サーバーの構成を確認します。CORS が必要な場合は、Access-Control-Allow-Origin ヘッダーを追加します。

検証チェックリスト

• Agent Card は構文エラーのない有効な JSON です
• すべての必須フィールドが存在します: name、description、url、skills
• 各スキルに id、name、description、inputModes、outputModes があります
• 認証スキームはデプロイメント セキュリティ要件と一致します
• 機能フラグは実装の状態を正確に反映します
• Agent Card は /.well-known/agent.json で正しい Content-Type を使用して提供されます
• A2A クライアントが正常に card をフェッチして解析できます
• スキルの例は現実的で正しいスキルをトリガーします

よくある質問

• 機能の過度な約束: 実装なしで streaming: true または pushNotifications: true を設定すると、それらの機能が使用されるときにクライアント障害が発生します。慎重に設定してください。
• 不明確なスキルの説明: 「データ処理を実行」のような説明は正確なスキル マッチングを妨げます。入力、出力、ドメインについて具体的にしてください。
• CORS ヘッダーがない: ブラウザベースの A2A クライアントは、適切な CORS 設定なしに Agent Card をフェッチできません。
• スキルの重複: 2 つのスキルが同じタスクを処理できる場合、クライアント エージェントはどれを呼び出すかを判断できません。明確な境界を確保してください。
• デフォルト モードの忘却: defaultInputModes と defaultOutputModes を省略すると、クライアントは何のコンテンツ タイプを送信するかわかりません。
• バージョンの停滞: スキルまたは機能が変わるときは Agent Card バージョンを更新します。クライアントが古いバージョンをキャッシュする可能性があります。
• 実装前の公開: Agent Card は契約です。実装されていないスキルを公開するとランタイム障害につながります。

関連スキル

• implement-a2a-server - Agent Card の背後にあるサーバーを実装する
• test-a2a-interop - Agent Card 準拠性と相互運用性を検証する
• build-custom-mcp-server - A2A の代替/補完としての MCP サーバー
• configure-mcp-server - A2A セットアップに適用可能な MCP 設定パターン