ディスカバリーツール · A2A v1.0

A2A Agent Card のディスカバリー URL をチェック

A2A クライアントは well-known URL から JSON 形式の Agent Card を取得してエージェントを発見します。実際のドメインで両方の命名規則をテストし、クライアントが実際に受け取る内容を確認できます。

同じベースドメインから両方の候補ディスカバリー URL を組み立てます。

返却された JSON を取得し、ステータスコードとコンテンツタイプを報告します。

可能な場合はレスポンスを Agent Card JSON として解析します。

インターフェース、スキル、プロバイダー、モード、能力、セキュリティメタデータについて準備状況チェックを実行します。

公開エージェントドメインをチェック

ベースドメインを入力してください。チェッカーは両方のディスカバリーパスを取得し、返却された JSON を解析して、Agent Card の準備状況チェックを実行します。

ディスカバリーの仕組み

1 つの well-known URL があらゆる A2A 統合の起点になります。

他のエージェントがあなたのサービスを呼び出す前に、まずあなたのドメインの well-known URI（RFC 8615）から Agent Card を取得し、スキルとセキュリティ要件を評価した上で、優先インターフェースを呼び出します。Agent Card が存在しない、古い、またはリダイレクトの背後に隠れている場合、統合は始まる前に失敗します。

このサイトは自らチェックしていることを実践しています。AgentCard.net は両方のパスに自身の Agent Card を公開しており、右側の例はその実際のドキュメントです。

実際の Agent Card を見る

agentcard.net discovery

GET /.well-known/agent-card.json HTTP/1.1
Host: www.agentcard.net

HTTP/1.1 200 OK
Content-Type: application/a2a+json

{
  "name": "AgentCard.net Toolkit",
  "version": "1.0.0",
  "supportedInterfaces": [
    { "url": "https://www.agentcard.net/api/agent-card",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0" }
  ],
  "skills": [
    { "id": "generate-agent-card", ... },
    { "id": "validate-agent-card", ... },
    { "id": "check-well-known-discovery", ... }
  ]
}

ディスカバリーパス

2 つの規約、1 つの Agent Card。

完全なバリデーターを開く

A2A v1.0 標準

/.well-known/agent-card.json

A2A v1.0 仕様で登録された well-known URI です。新しいクライアントはまずこのパスを取得します。コンテンツタイプ application/a2a+json で提供してください。

レガシー（v1.0 以前）

/.well-known/agent.json

初期の A2A 実装やコードラボの例で使用されています。デプロイ済みの多くのクライアントは今でもこのパスのみをチェックするため、ここに同じ Agent Card を提供することは安全な移行策です。

公開パターン

Agent Card のディスカバリーを堅牢にする。

ディスカバリーの失敗はたいてい単純です。リダイレクト、キャッシュされたエラーページ、あるいは片方のパスだけをデプロイしてもう片方を忘れる、といった具合です。この公開手順により、両方の規約が常に同じ最新の Agent Card を提供できます。

1
標準パスに公開する
A2A サービスと同じドメイン上で、レビュー済みの Agent Card を HTTPS 経由で /.well-known/agent-card.json に、コンテンツタイプ application/a2a+json で提供します。
2
レガシーパスをミラーする
古いクライアントがまだ存在する間は、/.well-known/agent.json からも同一のドキュメントを返します。両パスで Agent Card が異なるとルーティングが混乱します。
3
Agent Card を同期させる
エンドポイント、スキル、能力、認証のいずれかが変わったら、Agent Card を更新し version フィールドを上げ、両方のパスを同時に再デプロイします。
4
変更のたびに再チェックする
デプロイ、DNS 変更、ゲートウェイ移行、マーケットプレイス編集の後にこのチェッカーを実行してください。失敗の原因はたいていリダイレクト、HTML エラーページ、または片方のパスの取り忘れです。

よくある質問

Well-known Agent JSON に関するよくある質問

何を、どこに公開すべきか、そしてどちらの規約のクライアントも動作し続けるようにする方法。

どちらの well-known Agent Card パスを使うべきですか？

A2A v1.0 は /.well-known/agent-card.json を標準のディスカバリーパスとして登録しています。レガシーな /.well-known/agent.json は v1.0 以前のものですが、今でも多くのデプロイ済みクライアントがチェックしているため、移行期間中は両方のパスに同じ Agent Card を公開するのが現実的な選択です。

両方のパスは同一の JSON を返すべきですか？

はい。両方のパスから同じ公開 Agent Card を返すことで、片方の規約しかサポートしないクライアントとの一貫性を保てます。ドキュメントが異なると、クライアントがどちらのパスを取得したかによってエージェントが違って見えてしまいます。

Agent Card はどのコンテンツタイプで提供すべきですか？

仕様では Agent Card 用に application/a2a+json が登録されています。実務上は通常の application/json も広く受け入れられますが、コンテンツタイプが HTML の場合は、そのパスが Agent Card ではなくエラーページを返している確かな兆候です。

公開の Agent Card はプライベートな能力を隠せますか？

はい。公開 Agent Card にはディスカバリーに安全なメタデータのみを掲載し、capabilities.extendedAgentCard を true に設定して、認証済みの GetExtendedAgentCard 操作を通じて機密性の高いスキルを公開してください。

デプロイ後にディスカバリーチェックが失敗するのはなぜですか？

よくある原因は、ログインページやマーケティングページへのリダイレクト、ステータス 200 で返される HTML の 404 ページ、CDN にキャッシュされた古い JSON、あるいは 2 つの well-known パスのうち片方しかデプロイされていないことです。チェッカーは各パスのステータスコードとコンテンツタイプを報告するため、問題はすぐに可視化されます。

公開する前に

Agent Card を検証してから URL をチェックする。

まず JSON を完全なバリデーターに通し、両方の well-known パスに公開してから、このチェッカーでディスカバリーを確認してください。

バリデーターを開く Agent Card を生成する

ブログから

A2A ディスカバリーの実践ガイド。v1.0 仕様に基づいて執筆しています。

すべての記事

Comparison

記事は英語で公開されています。

A2A Agent Card のディスカバリー URL をチェック

公開エージェントドメインをチェック

1 つの well-known URL があらゆる A2A 統合の起点になります。

2 つの規約、1 つの Agent Card。

/.well-known/agent-card.json

/.well-known/agent.json

Agent Card のディスカバリーを堅牢にする。

標準パスに公開する

レガシーパスをミラーする

Agent Card を同期させる

変更のたびに再チェックする