2026-07-18 16:59 UTC

A2A の Agent Card: 完全な JSON 例とフィールド解説

Agent Card は、クライアントエージェントに「誰を呼び出すか」「どこにタスクを送るか」「どのスキルが使えるか」を伝える JSON ドキュメントです。A2A（Agent2Agent）プロトコルでは、通常 /.well-known/agent-card.json に公開します。カードがなければ発見しにくく、曖昧な説明では正しくルーティングしにくくなります。

Agent Card - エージェント能力の公開契約
Discovery - well-known URL または registry によるカード発見
skills - 「何でもできる」ではなく具体的な能力
capabilities - streaming、push、拡張カード
security - OpenAPI 風の認証スキーム

Agent Card が必要な理由

A2A は独立したエージェント同士をつなぎます。一方がクライアント、もう一方が実行者です。タスク送信前にクライアントはカードを読み、次に答えます。

このエージェントはユーザーの意図に合うか?
どの endpoint がタスクを受け取るか?
入出力でどの MIME タイプが使えるか?
認証は必要か、どの方式か?
イベントストリーミングや webhook 通知はあるか?

カードは宣伝文ではありません。オーケストレータや LLM ルーターが解析します。description、skills、examples が具体であるほど、実行者の選定は安定します。

完全な JSON 例

以下は、サイト上の商品検索、見積計算、ユーザー確認後のリード作成を行うエージェントの実用例です。フィールドは一般的な A2A JSON カードと同様に camelCase です。

{
  "name": "Site Commerce Agent",
  "description": "サイトのカタログを検索し、価格と納期を計算し、ユーザー確認後にリードを作成します。カタログ、下書きカート、注文ステータスを扱います。決済は行わず、価格変更もしません。",
  "version": "1.2.0",
  "protocolVersion": "0.3.0",
  "url": "https://api.example.com/a2a",
  "documentationUrl": "https://docs.example.com/a2a/commerce-agent",
  "iconUrl": "https://example.com/icons/commerce-agent.svg",
  "provider": {
    "organization": "Example Shop",
    "url": "https://example.com"
  },
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": true,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "search-products",
      "name": "商品検索",
      "description": "クエリ、カテゴリ、価格、在庫で商品を検索します。id、名称、価格、短い説明付きの候補を返します。",
      "tags": ["catalog", "search", "products"],
      "examples": [
        "今週配送可能な800ユーロ以下のノートPCを探して",
        "20人チーム向けの利用可能なプランを見せて"
      ],
      "inputModes": ["text/plain", "application/json"],
      "outputModes": ["application/json", "text/plain"]
    },
    {
      "id": "calculate-quote",
      "name": "見積計算",
      "description": "選択した品目と数量について価格、税、送料、納期を計算します。注文は作成しません。",
      "tags": ["pricing", "quote", "shipping"],
      "examples": [
        "product_id=sku-1042 を3個、ベルリン配送で計算して",
        "50ユーザー向けに Basic と Pro を比較して"
      ],
      "inputModes": ["application/json", "text/plain"],
      "outputModes": ["application/json"]
    },
    {
      "id": "create-lead",
      "name": "リード作成",
      "description": "ユーザーの明示的な確認後にリードまたは依頼の下書きを作成します。連絡先とデータ処理の同意が必要です。",
      "tags": ["lead", "order-draft", "crm"],
      "examples": [
        "ACME 向け Pro プランの依頼を作成、連絡先: ops@acme.example",
        "quote_id=q-7781 から注文下書きを作成して"
      ],
      "inputModes": ["application/json"],
      "outputModes": ["application/json", "text/plain"]
    },
    {
      "id": "get-order-status",
      "name": "注文ステータス",
      "description": "認証済みユーザーの order_id、または公開トラッキング番号で支払い・配送ステータスを返します。",
      "tags": ["orders", "status", "tracking"],
      "examples": [
        "注文 ORD-20441 のステータスは?",
        "追跡番号 TRK-998877 の荷物はどこ?"
      ]
    }
  ],
  "securitySchemes": {
    "bearer": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    },
    "oauth2": {
      "type": "oauth2",
      "flows": {
        "clientCredentials": {
          "tokenUrl": "https://auth.example.com/oauth/token",
          "scopes": {
            "catalog:read": "カタログと見積の読み取り",
            "leads:write": "リード作成",
            "orders:read": "注文ステータスの読み取り"
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": ["catalog:read"]
    },
    {
      "bearer": []
    }
  ]
}

A2A v1.0 では、単一のトップレベル url の代わりに supportedInterfaces 配列で endpoint を記述することが多いです。意味は同じで、タスク送信先と binding（JSONRPC、HTTP+JSON、GRPC など）を示します。

v1.0 の断片例:

{
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ]
}

トップレベルフィールドの解説

フィールド	必須	役割
`name`	はい	人が読めるエージェント名
`description`	はい	何をし、何をしないかの具体的な要約
`version`	はい	実装バージョン（semver 推奨）
`url` / `supportedInterfaces`	はい*	タスク用 endpoint。カード URL ではない
`skills`	はい	最低1つの skill
`capabilities`	推奨	正直な能力フラグ
`defaultInputModes` / `defaultOutputModes`	推奨	デフォルト MIME
`provider`	いいえ	提供組織
`documentationUrl` / `iconUrl`	いいえ	ドキュメントと UI アイコン
`protocolVersion`	スキーマによる	プロトコル版（v0.3 では上位に多い）
`securitySchemes` / `security`	いいえ	クライアントの認証方法

* v0.3 スキーマでは通常 url が必須です。v1.0 では supportedInterfaces が endpoint の役割を担います。

`name` と `description`

name は人とログ向け。description はルーターが読みます。悪い例: 「便利なサイトエージェント」。良い例: 操作、制限、結果の形を列挙する。

`version`

エージェント実装のバージョンであり、必ずしもプロトコル版ではありません。skills や応答契約の破壊的変更では major を上げます。クライアントはカードをキャッシュし、バージョン変更で再取得することがあります。

`url` - よくある誤り

url は message/send / タスクの送信先です。/.well-known/agent-card.json のパスでは ありません。

誤り:

"url": "https://example.com/.well-known/agent-card.json"

正しい例:

"url": "https://api.example.com/a2a"

`capabilities`

フラグ	意味
`streaming`	ストリーミング応答（SSE / stream）対応
`pushNotifications`	長時間タスク向け webhook
`stateTransitionHistory`	タスク状態遷移の履歴
`extendedAgentCard`	認証後に拡張/非公開カードが使える

実装済みの場合だけ true にしてください。streaming 非対応のエージェントに stream を開くとエラーになります。

`defaultInputModes` と `defaultOutputModes`

エージェント全体のデフォルト MIME です。skill で上書きできます。典型値: text/plain、application/json、application/pdf、image/png。

`skills` の解説

skill はルーティング単位です。1 skill = 1 つの明確な能力。

フィールド	必須	補足
`id`	はい	エージェント内で一意。kebab-case が扱いやすい
`name`	はい	UI 用の短い名前
`description`	はい	受け取るもの、返すもの、制限
`tags`	いいえ	検索・フィルタ用キーワード
`examples`	いいえだが強く推奨	オーケストレータ向けの実プロンプト 2-3 個
`inputModes` / `outputModes`	いいえ	この skill の MIME 上書き

examples は飾りではありません。無いとオーケストレータは説明だけで入力を推測し、失敗が増えます。

悪い skill:

{
  "id": "website",
  "name": "Website",
  "description": "サイトを扱う"
}

良い skill は完全例のように、具体的な id、境界、tags、examples を持ちます。

認証: `securitySchemes` と `security`

スキームは通常 OpenAPI 方式に従います。

apiKey
http（Basic / Bearer）
oauth2
openIdConnect
mutualTLS

securitySchemes は利用可能な方式を定義します。security はデフォルト要件です。

security 配列の複数オブジェクト = 代替（OR）
1 オブジェクト内の複数キー = すべて必要（AND）

公開するのは認証の方法であり、秘密情報ではありません。API キー、refresh トークン、内部ホスト名を JSON に入れないでください。

Discovery: カードの見つけ方

典型的な流れ:

クライアントがエージェントのベースドメインを知る
https://agent.example.com/.well-known/agent-card.json を取得する
必須フィールドを検証する
description、tags、examples で skill を選ぶ
security に従って認証する
url / supportedInterfaces にタスクを送る

カードは registry やエージェントディレクトリにも載せられます。その場合 discovery は検索経由になり、well-known は所有者の正の情報源として残ります。

ローカル確認:

curl -s https://api.example.com/.well-known/agent-card.json

Agent Card に載せていけないもの

API キー、パスワード、秘密鍵
保護されていない内部管理画面や staging URL
外部クライアントに使えない操作
実装のない capabilities の盛りすぎ（streaming: true）
「サイトですべてやる」ような曖昧な skills

公開カードは攻撃面でありルーティング面でもあります。正確で、必要最小限に保ってください。

よくある誤り

url とカード URL を混同する
空の skills 配列 - ほぼルーティング不能になる
境界のない説明 - やらないこと（決済、削除、価格変更）が書かれていない
examples がない - 有効入力の理解が弱くなる
本番カードに localhost - クライアントから届かない
製品全体を1 skill にまとめる - 権限や MIME が異なる狭い skills に分ける方がよい

公開前のミニチェックリスト

HTTPS で Content-Type: application/json を返す
name、description、version、endpoint、少なくとも1 skill がある
説明が具体的
主要 skills に examples と tags がある
capabilities が実サーバと一致する
JSON に秘密情報がない
カード上の endpoint がテストタスクに応答する
破壊的変更でバージョンを上げる

まとめ

Agent Card は A2A における主要な discovery 契約です。正確な skills、正直な capabilities、明示的な security を持つ完全な JSON があれば、クライアントエージェントは適切な実行者を見つけ、誤った呼び出しを避けられます。

Agent Card の設計、A2A サーバ、サイト API との接続で支援が必要なら - ご連絡ください。

よくある質問

Agent Card はどこに置くべきですか?

標準の公開パスはエージェントドメイン上の /.well-known/agent-card.json です。 カタログや registry への登録もできますが、well-known URL は別インデックスなしで使える便利な discovery 地点のままです。

`url` とカードアドレスの違いは?

カードアドレスは discovery 用、url（または supportedInterfaces）はタスク実行用です。 クライアントはまず JSON を読み、その後エージェントの作業 endpoint にメッセージ/タスクを送ります。

カードに skills はいくつ必要ですか?

入力や権限が本当に異なる能力の数だけです。 通常は「全部やる」1 つより、3-7 個の狭い skills の方がよいです。ルーティングには境界、tags、examples が重要です。

Agent Card に認証は必須ですか?

常にではありません。 公開の読み取り専用エージェントは security を省略できます。書き込み、個人データ、有料操作では securitySchemes と security を宣言し、秘密はカード外に置いてください。

デプロイのたびにカードを更新すべきですか?

skills、endpoint、capabilities、auth、エージェントの意味が変わったときに更新してください。 契約変更のない技術パッチは version に反映し、破壊的変更は major と明示的なドキュメントが望ましいです。