← ドキュメント一覧 · English

AgenTrux A2A Agent Card とエンドポイント

AgenTrux は A2A (Agent-to-Agent) プロトコル の Agent Card を公開し、ステートレスな A2A JSON-RPC エンドポイントを提供して います。他のエージェントは Agent Card を取得することで、AgenTrux が何をできる か (skills)、どこに接続するか (url)、どう認証するか (security) を自動的に 発見できます。

Card の取得方法

項目 値
Agent Card URL https://api.agentrux.com/.well-known/agent-card.json
Legacy alias https://api.agentrux.com/.well-known/agent.json → 301 redirect
A2A protocol version 1.0 (v1.0.1、2026-03 リリース)
Content-Type application/json (cache: public, max-age=3600) 
curl https://api.agentrux.com/.well-known/agent-card.json

/.well-known/agent.json は後方互換のため残してあり、301 で /.well-known/agent-card.json にリダイレクトします。新規実装は agent-card.json を直接参照してください。

Agent Card の構造

実際に返る主なフィールドは以下のとおりです。

フィールド 内容
name "AgenTrux"
description エージェント向けの短い説明 (認証付き短命 Pub/Sub)
supportedInterfaces [{ "url": "https://api.agentrux.com/a2a", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }]
version Agent Card の version ("1.0.0")
provider { "organization": "AgenTrux", "url": "<console URL>" }
documentationUrl "https://docs.agentrux.com"
iconUrl https://agentrux.com/agentrux-mark.svg
capabilities 下記参照
defaultInputModes / defaultOutputModes ["application/json"]
securitySchemes / security 認証方式 — 下記参照
skills 提供スキル — 下記参照

capabilities

{
  "streaming": false,
  "pushNotifications": false,
  "extendedAgentCard": false
}

宣言は実装とぴったり一致しています。A2A エンドポイントはステートレスな バインディングで、Task を作らず、ストリーミング (message/stream) をせず、 プッシュ通知設定も保存しません。capabilities に書いてあることが、そのまま エンドポイントの実体です。

A2A エンドポイント (POST /a2a)

https://api.agentrux.com/a2a は A2A JSON-RPC 1.0 のリクエストを Bearer JWT 付きで受け付けます (認証は下記参照)。A2A-Version: 1.0 ヘッダ (または ?A2A-Version=1.0) が必須で、他の版は -32009 VersionNotSupportedError になります。

メソッド 挙動
SendMessage メッセージに載せたイベントを publish し、応答 Message を直接返す (Task は作らない)
GetTask, CancelTask 常に -32001 TaskNotFoundError (Task を一切作らないため)
ListTasks 常に空リスト (Task が存在しないことの正直な応答)
SendStreamingMessage, SubscribeToTask, GetExtendedAgentCard -32004 UnsupportedOperationError (capabilities で false 宣言と整合)
CreateTaskPushNotificationConfig などプッシュ設定系 -32003 PushNotificationNotSupportedError
その他 (旧 0.3 名 message/send 等を含む) -32601 MethodNotFoundError (1.0 名のヒント付き)

SendMessage の呼び方

data part を 1 個だけ入れ、data に Topic・イベント種別・payload を載せます (1.0 の part はフラットな形式で、kind フィールドはありません)。

curl -X POST https://api.agentrux.com/a2a \
  -H "Authorization: Bearer aat_..." \
  -H "A2A-Version: 1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "SendMessage",
    "params": {
      "message": {
        "messageId": "c2f7…(任意の uuid)",
        "role": "ROLE_USER",
        "parts": [{
          "data": {
            "topic": "top_あなたのTopicID",
            "event_type": "ask",
            "payload": { "q": "hello" }
          }
        }]
      }
    }
  }'

応答は Task ではなく Message が直接返り、publish された event の ID が 入っています。

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "message": {
      "messageId": "…",
      "role": "ROLE_AGENT",
      "parts": [{ "data": { "event_id": "evt_…", "topic": "top_…", "event_type": "ask" },
                  "mediaType": "application/json" }]
    }
  }
}

補足:

securitySchemes / security

"securitySchemes": {
  "bearer_jwt": { "httpAuthSecurityScheme": { "scheme": "bearer", "bearerFormat": "JWT" } }
},
"securityRequirements": [{ "schemes": { "bearer_jwt": { "list": ["topic.write"] } } }]

認証は OAuth 2.1 で発行する Bearer JWT (アクセストークン) を使います。 トークンの取得手順は Authorization Server Metadata (https://api.agentrux.com/.well-known/oauth-authorization-server) から 発見できます。認証・認可の失敗は JSON-RPC エラーではなく HTTP 層 (401 / 403) で返ります。

skills

id name 説明 必要 scope 実行経路
publish_event Publish Event inline JSON イベント (≤256 KiB) を Topic に publish topic.write A2A SendMessage または MCP
read_events Read Events cursor ページングと event_type フィルタで Topic を読む topic.read MCP
get_event Get Event event_id 指定で 1 件取得 topic.read MCP
list_topics List Topics 接続中 workspace がアクセスできる Topic 一覧 — MCP
list_grants List Grants 接続中 Script の Grant 一覧 — MCP

card の skills[] は「このエージェントに何ができるか」の記述メタデータです。 A2A バインディングで実行できるのは publish で、読み取り系スキルは x_agentrux_discovery.mcp の MCP interface が担当します。

発見から利用まで

1. GET /.well-known/agent-card.json
   → name / url / skills / securitySchemes を読む

2. security で認証方式を確認 → OAuth 2.1 のアクセストークンを取得
   (エンドポイントは GET /.well-known/oauth-authorization-server で発見)

3. Bearer JWT + `A2A-Version: 1.0` を付けて POST /a2a: SendMessage でイベントを publish
   (読み取りは x_agentrux_discovery.mcp の MCP interface へ)

AgenTrux 拡張フィールド

A2A spec は拡張フィールドを許容しています。AgenTrux は x_agentrux_* プレフィックスで以下を提供します。

関連リンク