エージェントの人間が読める名前。
マーケットプレイスの一覧やクライアント UI に表示されます。短く具体的に保ちましょう——クライアントは候補エージェントを比較する際にこれを主要なラベルとして使用します。
よくある間違い： 「AI Assistant」のような汎用的な名前を使うと、ルーティングシステムが区別する手がかりを得られません。
"name": "地理空間ルート プランナー エージェント"
スキーマリファレンス · 14 fieldsA2A v1.0
A2A Agent Card スキーマ、フィールドごとの解説
Agent Card は、A2A クライアントにエージェントが誰なのか、どこに到達すればよいか、何ができるか、アクセスがどう保護されているかを伝える標準化された JSON ドキュメントです。このリファレンスは、すべての v1.0 フィールドについて、型、要件、例、そしてバリデーターが最もよく検出する間違いを網羅しています。
ディスカバリーの仕組み
1 つの well-known URL があらゆる A2A 統合の起点になります。
A2A クライアントは well-known URI から Agent Card を取得し、自分のタスクに照らしてスキル、能力、セキュリティ要件を評価した後、優先インターフェース——supportedInterfaces の最初のエントリ——を呼び出します。capabilities.extendedAgentCard が true の場合、認証済みクライアントは GetExtendedAgentCard 操作を通じてより豊富な Agent Card を要求できます。
仕様では /.well-known/agent-card.json を標準の場所として登録しています。古い v0.x のデプロイでは /.well-known/agent.json が使われていたため、私たちのバリデーターは両方をチェックします。
# Fetch a public Agent Card
GET /.well-known/agent-card.json HTTP/1.1
Host: agent.example.com
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"name": "GeoSpatial Route Planner Agent",
"supportedInterfaces": [
{ "url": "https://georoute-agent.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
],
...
}フィールドリファレンス
すべての AgentCard フィールドと、合否を分ける詳細情報。
必須フラグは公式仕様の v1.0 protobuf 定義に従います。アンカーリンクにより、各フィールドは Issue、レビュー、CI の出力から引用可能です。
エージェントが何をするか、他のエージェントがいつそれを呼び出すべきか。
これは、あなたのエージェントがタスクに適しているかどうかを判断する人間の統合担当者と LLM ベースのルーターの両方にとって、主要な自由テキストのシグナルです。タスクの領域、主要な能力、境界を明記してください。
よくある間違い： 20 文字未満の 1 行の説明。ルーターは説明されていないものをマッチさせることはできません。
"description": "高度なルート計画、交通分析、カスタム マップ生成サービスを提供します。"
エンドポイントとプロトコルバインディングの順序付きリスト。最初のエントリが優先されます。
v1.0 で新規追加：従来のトップレベルの url、preferredTransport、additionalInterfaces フィールドを置き換えます。各エントリは独自の url、protocolBinding（JSONRPC、GRPC、HTTP+JSON、またはカスタムバインディング URI）、protocolVersion、およびオプションのテナントルーティングキーを宣言します——これにより、1 つのエージェントが複数のプロトコルバージョンとトランスポートを同時に提供できます。
よくある間違い： サーバーがその URL で実際には提供していないバインディングを宣言すること——仕様では各エントリが正確であることを求めています。
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]誰がエージェントを運営しているか：組織とウェブサイト。
マーケットプレイスや企業監査のための信頼シグナルです。v1.0 では name フィールドが organization に改名されました。存在する場合、オブジェクト内の url は必須です。
よくある間違い： いまだに provider.name（v1.0 以前）を使用していること。v1.0 Agent Card を読むバリデーターはそれを認識しません。
"provider": {
"organization": "例 ジオサービス株式会社",
"url": "https://www.examplegeoservices.com"
}プロトコルではなく、エージェント自体のバージョン。
Agent Card が実質的に変更されたことをクライアントが検出し、互換性を再評価できるようにします。あなた自身のリリース方式（通常は semver）に従ってください。
よくある間違い： これを A2A プロトコルバージョンと混同すること——それは現在、各 supportedInterfaces エントリに存在します。
"version": "1.2.0"
エージェントの人間が読めるドキュメントへのリンク。
ディスカバリードキュメントには属さない、完全な API 契約、レート制限、利用規約を統合担当者が読める場所を提供します。
よくある間違い： 技術文書ではなく、マーケティング用のホームページを指していること。
"documentationUrl": "https://docs.example.com/agent"
プロトコル機能フラグ：streaming、pushNotifications、extensions、extendedAgentCard。
クライアントは宣言されていない機能を呼び出してはいけません——宣言されていないストリーミング呼び出しはエラーを返します。extendedAgentCard: true は、GetExtendedAgentCard 操作を通じてより豊富な認証済み Agent Card を提供することを示します。v1.0 では stateTransitionHistory が削除されました。
よくある間違い： サーバーにストリーミングエンドポイントがないのに streaming: true を宣言すること。クライアントはそれを呼び出して失敗します。
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}名前付き認証スキーム：API キー、HTTP 認証、OAuth 2.0、OpenID Connect、または相互 TLS。
各名前付きスキームは、1 つの具体的なスキームオブジェクト（apiKeySecurityScheme、httpAuthSecurityScheme、oauth2SecurityScheme、openIdConnectSecurityScheme、mtlsSecurityScheme）をラップします。クライアントはここから認証方法を発見します——認証情報自体は常に帯域外で取得されます。
よくある間違い： 実際の API キーやトークンを Agent Card に埋め込むこと。Agent Card は公開ドキュメントです。
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}エージェントを呼び出すために必要な、宣言されたスキーム（およびスコープ）。
各エントリは、securitySchemes のスキーム名を必要なスコープにマッピングし、OpenAPI のセキュリティ要件パターンを反映しています。意図的に公開されているエージェントの場合は、両方のフィールドを完全に省略してください。
よくある間違い： securitySchemes を宣言しているのに security 要件がなく、クライアントが認証が強制されているかどうかを推測せざるを得ないこと。
"security": [{ "google": ["openid", "profile", "email"] }]エージェントがすべてのスキルにわたって受け入れるメディアタイプ。
text/plain、application/json、image/png などの標準的な MIME タイプ。個々のスキルは独自の inputModes で上書きできます。
よくある間違い： フィールドを省略すること。v1.0 では必須です——クライアントはリクエストを組み立てるためにこれを必要とします。
"defaultInputModes": ["application/json", "text/plain"]
エージェントがすべてのスキルにわたって返すメディアタイプ。
呼び出し元に、文章、構造化された JSON、画像、ファイルのいずれを期待すべきかを伝えます。スキルはスキルごとに outputModes で上書きできます。
よくある間違い： エージェントが実際には構造化された成果物を返すのに、text/plain だけを記載すること。
"defaultOutputModes": ["application/json", "image/png"]
エージェントが成功する可能性の高い具体的な能力。
各スキルには id、name、description、tags が必要です。examples、スキルごとのモード、スキルごとのセキュリティはオプションです。スキルはディスカバリーの単位です——ルーターはタスクをそれらと照合するため、それぞれを単一のタスク境界に限定してください。
よくある間違い： タグのないスキル。タグは v1.0 で必須になり、スキルレベルのマッチングを駆動します。
"skills": [{
"id": "route-optimizer-traffic",
"name": "トラフィックを認識したルート オプティマイザー",
"description": "リアルタイムの交通状況を使用して最適な運転ルートを計算します...",
"tags": ["maps", "routing", "traffic"],
"examples": ["有料道路を避けて A から B までのルートを計画します。"]
}]Agent Card がプロバイダーによって発行されたことを証明する JSON Web Signature。
各署名は、RFC 8785（JCS）で正規化された Agent Card に対して計算された base64url 保護 JWS ヘッダーと署名値を持ちます。クライアントは、公開ウェブから取得した Agent Card を信頼する前に、少なくとも 1 つの署名を検証すべきです。
よくある間違い： カードに署名した後にフィールドを編集すること——空白の意味を持たない値の変更であっても JWS は無効になります。
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]エージェントを表すアイコンへの URL。
カタログやクライアント UI で使用されます。安定した場所から HTTPS 経由で提供してください。
よくある間違い： リスティングの裏で変更される可能性のある、別の信頼できないドメイン上のアイコンにリンクすること。
"iconUrl": "https://agent.example.com/icon.png"
バージョン移行
v0.x Agent Card を A2A v1.0 に移行する。
あなたの Agent Card にまだトップレベルの url や preferredTransport がある場合、それは v1.0 より前のものです。バリデーターはこれらのそれぞれを自動的にフラグします。
| v0.x フィールド | v1.0 の置き換え | 変更理由 |
|---|---|---|
| url | supportedInterfaces[0].url | 優先エンドポイントは、単純に最初のインターフェースエントリになりました。 |
| preferredTransport | supportedInterfaces[] ordering | 優先順位は、別のフィールドではなく配列の順序で表現されます。 |
| additionalInterfaces | supportedInterfaces[] | すべてのインターフェースが 1 つの順序付き配列に存在します。 |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | 各インターフェースが独自のプロトコルバージョンを宣言し、複数バージョンのサポートを可能にします。 |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | capabilities オブジェクトに移動しました。RPC は GetExtendedAgentCard に改名されました。 |
| provider.name | provider.organization | 明確化のために改名されました。 |
| capabilities.stateTransitionHistory | — removed | v1.0 の一部ではありません。必要に応じて、拡張として同等の動作をモデル化してください。 |
ボイラープレート
v1.0 Agent Card のための TypeScript 型。
これらのインターフェースをクライアント、サーバー、または CI チェックに組み込むことで、型安全に Agent Card を解析・生成できます。これらは、Agent Card が実際に公開される camelCase JSON 形式で、公式仕様リポジトリの protobuf 定義を反映しています。
代わりに手動で Agent Card を作成しますか？ジェネレーターはまさにこの正確な形式を生成します。
// A2A v1.0 Agent Card — TypeScript definitions
export interface AgentCard {
name: string
description: string
supportedInterfaces: AgentInterface[]
provider?: AgentProvider
version: string
documentationUrl?: string
capabilities: AgentCapabilities
securitySchemes?: Record<string, SecurityScheme>
security?: Record<string, string[]>[]
defaultInputModes: string[]
defaultOutputModes: string[]
skills: AgentSkill[]
signatures?: AgentCardSignature[]
iconUrl?: string
}
export interface AgentInterface {
url: string
protocolBinding: 'JSONRPC' | 'GRPC' | 'HTTP+JSON' | (string & {})
protocolVersion: string
tenant?: string
}
export interface AgentProvider {
organization: string
url: string
}
export interface AgentCapabilities {
streaming?: boolean
pushNotifications?: boolean
extensions?: AgentExtension[]
extendedAgentCard?: boolean
}
export interface AgentExtension {
uri: string
description?: string
required?: boolean
params?: Record<string, unknown>
}
export interface AgentSkill {
id: string
name: string
description: string
tags: string[]
examples?: string[]
inputModes?: string[]
outputModes?: string[]
}
export interface AgentCardSignature {
protected: string
signature: string
header?: Record<string, unknown>
}
export type SecurityScheme =
| { apiKeySecurityScheme: { location: 'header' | 'query' | 'cookie'; name: string; description?: string } }
| { httpAuthSecurityScheme: { scheme: string; bearerFormat?: string; description?: string } }
| { oauth2SecurityScheme: { flows: Record<string, unknown>; oauth2MetadataUrl?: string; description?: string } }
| { openIdConnectSecurityScheme: { openIdConnectUrl: string; description?: string } }
| { mtlsSecurityScheme: Record<string, never> }完全性
Agent Card の署名について、簡単に。
Agent Card は公開ウェブから取得されるため、v1.0 では署名を正式化しています：Agent Card（signatures フィールドとデフォルト値を除く）は RFC 8785 JSON Canonicalization で正規化された後、JWS として署名されます。クライアントは、Agent Card に基づいて行動する前に、kid/jku ヘッダーまたは信頼できる鍵ストアを通じて少なくとも 1 つの署名を検証すべきです。複数の署名は鍵のローテーションをサポートします。
公開前チェックリスト
HTTPS 経由で /.well-known/agent-card.json に Agent Card を提供する。
すべての supportedInterfaces エントリに到達可能で、宣言されたバインディングを話す。
スキルには必須タグと、明確なタスク境界を持つ説明がある。
宣言された能力がサーバーと一致している——宣言されていない機能はエラーを返す必要があり、宣言された機能は動作する必要がある。
securitySchemes は認証方法を記述しており、Agent Card のどこにも認証情報が現れない。
Agent Card の内容が変更されるたびに version が引き上げられる。
完全な v1.0 Agent Card。
OAuth 2.0、ストリーミング、プッシュ通知を備えたカスタマーサポートエージェント——すべての必須フィールドが揃っています。他のパターンは examples ライブラリにあります。
{
"name": "カスタマーサポートエージェント",
"description": "カスタマー サポートの質問に答え、注文のコンテキストを取得し、未解決の問題を人間のチームにエスカレーションします。",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/customer-support",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "株式会社イ例",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "resolve-customer-support-request",
"name": "カスタマーサポートリクエストを解決する",
"description": "顧客サポートのリクエストを分類し、必要なコンテキストを収集し、解決策を提案し、信頼性が低い場合はエスカレーションします。",
"tags": [
"support",
"orders",
"returns"
],
"examples": [
"注文品の返品を手伝ってください。"
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/customer-support/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}よくある質問
Agent Card スキーマに関するよくある質問
Agent Card がレビューを通過するかどうかを決めるバージョン変更、ディスカバリーフィールド、公開の詳細。
A2A v1.0 の Agent Card で何が変わりましたか？
v1.0 は url、preferredTransport、additionalInterfaces を 1 つの順序付き supportedInterfaces 配列に統合し、各エントリが独自の url、protocolBinding、protocolVersion を宣言します。supportsAuthenticatedExtendedCard は capabilities.extendedAgentCard に移動し、provider.name は provider.organization になり、スキルタグは必須になり、JWS Agent Card 署名は RFC 8785 正規化で正式化されました。
Agent Card は API スキーマと同じものですか？
いいえ。Agent Card はエージェントのディスカバリードキュメントです。身元、インターフェース、能力、スキル、モード、プロバイダー、セキュリティメタデータを要約しますが、完全な API スキーマは詳細なリクエストとレスポンスの形状を記述します。サービスにとっての README や OpenAPI 概要のような役割を果たします：それを呼び出すかどうか、どう呼び出すかを判断するのに十分な情報です。
ディスカバリーにとって最も重要なフィールドはどれですか？
name、description、supportedInterfaces、skills（タグ付き）、defaultInputModes、defaultOutputModes、capabilities、provider、およびセキュリティメタデータです。ルーティングシステムはタスクをあなたの description とスキルタグに照らして一致させ、その後インターフェースと能力を使って実際の呼び出しを計画します。
プライベートスキルは公開 Agent Card に表示すべきですか？
認証なしでの発見に対して安全なスキルのみを公開してください。より豊富なプライベート Agent Card が必要な場合は、capabilities.extendedAgentCard を true に設定し、認証済みの GetExtendedAgentCard 操作を通じて機密性の高いスキルを公開してください。
Agent Card はどこで公開されますか？
well-known URI である https://your-domain/.well-known/agent-card.json で、コンテンツタイプ application/a2a+json で公開されます（実務上 application/json も動作します）。以前の実装は /.well-known/agent.json を使用していたため、移行期間中は両方を公開するのが現実的な選択です。
スキーマを活用する
最初の検証で通過する Agent Card を作りましょう。
サービスの詳細から v1.0 形式の Agent Card を生成するか、既存の Agent Card をバリデーターに貼り付けて、どのフィールドに注意が必要かを正確に確認してください。
ブログから
A2A ディスカバリーの実践ガイド。v1.0 仕様に基づいて執筆しています。
Comparison
A2A vs MCP: two protocols solving two different problems
Compare A2A vs MCP: what each protocol connects, where they overlap, and why production AI agent systems often use both for tools and agent collaboration.
9 min readガイドを読むHow-toHow to create an agent.json file for A2A v1.0
Learn how to create an agent.json file for A2A v1.0, including required Agent Card fields, the well-known URL, response headers, and common mistakes.
11 min readガイドを読むIntegrationPublishing an Agent Card from ADK, LangGraph, CrewAI or Semantic Kernel
Learn how to publish an A2A Agent Card from Google ADK, LangGraph, CrewAI, or Semantic Kernel by mapping framework concepts to standard discovery fields.
10 min readガイドを読む記事は英語で公開されています。