A2A Agent Card バリデーター

Agent Card バリデーターは、貼り付けられた JSON、アップロードされた Agent Card ファイル、公開エージェント URL を A2A v1.0 のディスカバリー要件に照らしてチェックします。

エージェント Agent Card バリデータを使用する

JSON、パブリックエージェント URL を貼り付けるか、JSON ファイルをエディターにドラッグします。

Agent Card バリデーターのカバー範囲

クライアントがあなたのエージェントを発見する前に、Agent Card バリデーターがチェックすること。

Agent Card バリデーターは、A2A エージェントを公開する開発者、エージェントメタデータをレビューする社内プラットフォームチーム、送信された Agent Card に信頼できる呼び出しに十分な情報が含まれているかを確認するマーケットプレイス運営者のために設計されています。

開発中はローカルの JSON ドキュメントを貼り付け、リポジトリから Agent Card をアップロードするか、デプロイ済みドメインに対するライブ URL 検証を使用して公開ディスカバリーパスを確認します。

スキーマ準拠（A2A v1.0）

v1.0 仕様に対して必須フィールドをチェックします：name、description、version、インターフェースごとの protocolBinding と protocolVersion を持つ supportedInterfaces、capabilities、コンテンツモード、必須タグを持つ少なくとも 1 つのスキル。

意味的な問題と移行の問題

v1.0 以前の構造（トップレベルの url、preferredTransport、protocolVersion、provider.name、stateTransitionHistory）を検出し、各フィールドが v1.0 でどこに移動したかを正確に伝えます。

セキュリティと機密情報のスキャン

非公開エンドポイントに securitySchemes とセキュリティ要件が宣言されていることを確認し、非 HTTPS の URL にフラグを立て、埋め込まれた API キー、JWT、bearer トークンのように見える値をスキャンします。

ディスカバリーの準備状況

実際のドメインから /.well-known/agent-card.json と旧来の /.well-known/agent.json を取得し、両方が解析可能な Agent Card JSON を返すことを確認します。

検証が適合する場面

あらゆる段階で検証する：エディタ、CI パイプライン、本番ドメイン。

先月レビューを通過した Agent Card が、今日でもディスカバリーを壊す可能性があります——エンドポイントが移動したり、スキルが変わったり、再デプロイで well-known ルートが失われたりします。プラットフォームチームとマーケットプレイスのレビュアーは、検証を一度きりのチェックではなく、繰り返し可能なゲートとして扱います。

最もシンプルな CI ガードは curl だけで十分です：トラフィックが新しいデプロイに切り替わる前に、well-known パスが解析可能な JSON で応答することを確認します。

# deploy pipeline: fail if the published card breaks

curl -fsS https://your-domain/.well-known/agent-card.json \
  | python3 -c '
import json, sys
card = json.load(sys.stdin)
assert card.get("name"), "name is required"
assert card.get("supportedInterfaces"), "supportedInterfaces missing"
assert card.get("skills"), "skills missing"
print("agent card OK:", card["name"])'

修正ガイド

よくある Agent Card の修正

まず Agent Card バリデーターのレポートを使って必須フィールドに対応し、その後ディスカバリー性、信頼性、移行の詳細を改善してください。

プレースホルダーのエンドポイント URL を、デプロイ済みの HTTPS A2A サービス URL に置き換えます。

トップレベルの url と preferredTransport を、順序付き supportedInterfaces 配列に移します——最初のエントリが優先インターフェースです。

エージェント自体を説明する必須のトップレベル version フィールドを追加し、すべてのスキルにタグを追加します。

provider.name を provider.organization にリネームし、クライアントがエージェントをいつ呼び出すべきか分かるよう短い説明を拡充します。

エージェントのエンドポイントが完全に公開されていない場合は必ずセキュリティメタデータを宣言し、認証情報自体を決して埋め込まないでください。

同じ有効な Agent Card を /.well-known/agent-card.json に公開します（クライアントがまだ両方をチェックしている間は、旧来の agent.json パスにも公開します）。

よくある質問

Agent Card バリデーターに関するよくある質問

あなたのエージェントが A2A クライアントに到達する前に、基本を正しく整えましょう。

有効な例を比較する

バリデーターはどの A2A バージョンを対象としていますか？

チェックは A2A v1.0 の Agent Card 構造——supportedInterfaces、インターフェースごとのプロトコルバージョン、必須のスキルタグ、provider.organization——に従います。v1.0 以前の Agent Card が即座に拒否されるわけではありません。レガシーフィールドは、正確な v1.0 の代替とともに警告として表示されます。

なぜ両方の well-known URL をチェックするのですか？

v1.0 仕様は /.well-known/agent-card.json を登録していますが、以前の A2A 実装は /.well-known/agent.json を使用していました。両方をチェックすることで、クライアントが失敗する前にディスカバリーのギャップを捉えられます。

警告は無視してもよいですか？

警告はブロックする JSON エラーではありませんが、通常はエージェントの発見、信頼、呼び出しを容易にするメタデータ、または新しいクライアントが読み込まなくなる v1.0 以前のフィールドを指しています。

検証はいつ実行すべきですか？

3 つのタイミングです：開発中に Agent Card を編集しているとき、デプロイ前の CI ゲートとして、そして公開後——ライブサービスの URL を貼り付けて、両方のディスカバリーパスからクライアントが実際に受け取る内容を確認します。

検証の準備ができました

クライアントが発見する前に Agent Card を検証しましょう。

統合されたバリデーターワークスペースで JSON を貼り付けるか、Agent Card ファイルをドロップするか、公開 URL をチェックします。

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

ブログから

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

すべての記事

Troubleshooting

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