Agent Cardの書き方
実践チュートリアル
Agent Cardは、A2Aプロトコルにおけるエージェントの「名刺」です。 他のエージェントがあなたのエージェントを発見し、能力を理解するための情報を記述します。 基本概念については「A2Aエージェントカードとは？完全ガイド」をご覧ください。本記事では、実際にAgent Cardを書く手順を解説します。
最小構成のAgent Card
動作するAgent Cardに必要な最小限のフィールドは以下の通りです。まずはこの形から始めましょう。
{
"name": "my_first_agent",
"description": "最初のA2Aエージェント",
"version": "1.0.0",
"defaultInputModes": ["text/plain"],
"defaultOutputModes": ["text/plain"],
"capabilities": {
"streaming": false,
"pushNotifications": false
},
"supportedInterfaces": [
{
"url": "https://example.com/a2a",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"skills": [
{
"id": "hello",
"name": "挨拶",
"description": "ユーザーに挨拶を返す",
"tags": ["greeting", "basic"]
}
]
}フィールド解説（実例付き）
name / description
nameはエージェントの一意な識別子です。スネークケースまたはケバブケースを推奨します。
booking_agent機能が明確、スネークケース
My Agent v2 Finalスペース含む、バージョン混在
version
セマンティックバージョニング（semver）形式を使います。MAJOR.MINOR.PATCHの3つの数字で構成されます。
"1.0.0" // 初回リリース "1.1.0" // 後方互換性のある機能追加 "2.0.0" // 破壊的変更（スキルIDの変更等）
supportedInterfaces
エージェントへの接続方法を定義します。3つのプロトコルバインディングから選択できます。
| バインディング | 特徴 | 推奨場面 |
|---|---|---|
| JSONRPC | 標準的、最も広くサポート | 一般的なWebサービス |
| GRPC | 高速、型安全、バイナリ転送 | 高パフォーマンスが必要な場面 |
| HTTP+JSON | シンプル、デバッグしやすい | プロトタイピング、小規模 |
capabilities
エージェントの通信能力を宣言します。
"capabilities": {
"streaming": true, // リアルタイム応答が可能
"pushNotifications": true, // 非同期タスクの完了通知
"extendedAgentCard": false // 拡張仕様への対応
}- streaming: チャットボットや対話型エージェントなら
trueに - pushNotifications: 長時間タスク（レポート生成等）を処理するなら
trueに
skills
エージェントが提供するスキル（アクション）を定義します。
"skills": [
{
"id": "search_products",
"name": "商品検索",
"description": "キーワードや条件に基づいて商品を検索する",
"tags": ["search", "product", "e-commerce"],
"examples": [
"赤いスニーカーを探して",
"1万円以下のワイヤレスイヤホン"
]
}
]id の命名規則: スネークケース推奨。動詞+名詞の形式（例: send_email, create_booking）
tags のコツ: 一般的なキーワードと具体的なキーワードを混ぜる。3-5個が目安
examples の書き方: 実際のユーザー発話を想定。自然な日本語で2-3個
プリセットを活用して素早く始める
agentjukuのGenerator画面には5つのプリセットテンプレートが用意されています。 ゼロから書く代わりに、最も近いプリセットを選んでカスタマイズするのが最速の方法です。
- 予約管理エージェント — 予約・スケジュール管理に特化
- カスタマーサポート — FAQ回答とチケット管理の2スキル構成
- 営業・見積もり — 見積もり作成と商品レコメンド
- データ分析 — レポート生成とクエリ実行
- 空のテンプレート — すべて手動で入力したい場合
デプロイ方法
Agent Cardは/.well-known/agent-card.jsonに配置します。プラットフォーム別の手順を紹介します。
Vercel
// public/.well-known/ ディレクトリに配置するだけ
// Vercelが自動的に静的ファイルとして配信します
project/
public/
.well-known/
agent-card.json ← ここに配置Nginx
location /.well-known/agent-card.json {
alias /var/www/html/agent-card.json;
default_type application/json;
add_header Access-Control-Allow-Origin "*";
}Express
const express = require('express');
const app = express();
app.get('/.well-known/agent-card.json', (req, res) => {
res.json(require('./agent-card.json'));
});よくある間違い
"version": "v1"
"version": "1.0.0"
semver形式（MAJOR.MINOR.PATCH）を使用してください
2つのスキルに同じ "id": "search" を設定
"search_products" と "search_docs" のように区別
スキルIDはAgent Card内で一意である必要があります
"url": ""
"url": "https://api.example.com/a2a"
実際にアクセス可能なエンドポイントURLを指定してください
"tags": []
"tags": ["email", "communication", "notification"]
他のエージェントがスキルを発見するためにtagsは重要です
まとめ
Agent Cardの作成は、適切な命名規則とフィールド構成を理解すれば難しくありません。 最小構成から始めて、プリセットを活用し、必要に応じてフィールドを追加していくのが最も効率的です。
Agent Cardを作成する
agentjukuのGeneratorなら、GUIで簡単にAgent Cardを作成できます。プリセットから始めて、すぐにダウンロード。
agentjuku Generator で作成する