AgenTrux Topology Request

Topology Request フローでは、エージェントが必要とする Script・Topic・ Grant を 1 回のリクエストで宣言する。その宣言を人間が Console で一度 確認して承認すると、エージェントは承認済みの Topic にスコープが付いた Bearer アクセストークンを受け取り、そのまま publish / read できる。

これはセルフサービスのオンボーディング経路である。エージェントがトポロジー を提案し、人間が決定する。エージェントはリソースの作成または接続を要求 できるが、実際に作成するのは Approve をクリックした人間だけである。この フローが既存のものを削除したりスコープを縮小したりすることはない。アクセス の取り消しは常に Console での操作となる。

どのフローを使うか

ディスカバリ

エンドポイントは Authorization Server Metadata で広告されるため、ハード コードせずに発見できる。

curl https://api.agentrux.com/.well-known/oauth-authorization-server

{
  "token_endpoint": "https://api.agentrux.com/oauth/token",
  "topology_request_endpoint": "https://api.agentrux.com/oauth/topology-request",
  "authorization_details_types_supported": ["agentrux.topology"],
  "...": "..."
}

Step 1 — public client を登録する

MCP と同じ Dynamic Client Registration を使う。一度登録して client_id （dcr_…）を再利用する。

curl -X POST https://api.agentrux.com/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "weather-bot",
    "redirect_uris": ["http://127.0.0.1:8765/callback"],
    "token_endpoint_auth_method": "none",
    "grant_types": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"]
  }'

レスポンスには client_id（dcr_ プレフィックス）が含まれる。以降の Step で再利用する。登録の詳細は MCP ドキュメント を参照。

Step 2 — Topology Request を送信する

POST /oauth/topology-request は form-encoded （application/x-www-form-urlencoded）である。authorization_details フィールドに、宣言内容を URL エンコードした JSON 配列（要素はちょうど 1 件） として載せる。

authorization_details に入れる宣言:

[
  {
    "type": "agentrux.topology",
    "version": 1,
    "script": {
      "name": "weather-bot",
      "description": "Fetches weather and publishes hourly readings"
    },
    "topics": [
      { "ref": "weather-data", "name": "weather-data", "retention_s": 86400, "intent": "publish hourly readings" }
    ],
    "grants": [
      { "topic_ref": "weather-data", "scope": "write", "binding_name": "weather-out" }
    ]
  }
]

フィールドの規則（入力契約）:

宣言全体は 16 KB 以内。文字列は Unicode 正規化され、制御文字を含めては ならない。

完全な curl（JSON フィールドには --data-urlencode を使う）:

curl -X POST https://api.agentrux.com/oauth/topology-request \
  --data-urlencode "client_id=dcr_…" \
  --data-urlencode "client_hint=weather-bot v1.2" \
  --data-urlencode 'authorization_details=[{"type":"agentrux.topology","version":1,"script":{"name":"weather-bot","description":"Fetches weather and publishes hourly readings"},"topics":[{"ref":"weather-data","name":"weather-data","retention_s":86400,"intent":"publish hourly readings"}],"grants":[{"topic_ref":"weather-data","scope":"write","binding_name":"weather-out"}]}]'

レスポンス（200）:

{
  "device_code": "dc_…",
  "user_code": "TVHV-QJZW",
  "verification_uri": "https://console.agentrux.com/topology/approve",
  "verification_uri_complete": "https://console.agentrux.com/topology/approve?code=TVHV-QJZW",
  "expires_in": 600,
  "interval": 5
}

検証エラー（400、OAuth の error コード）:

短時間に多数送信すると 429 too_many_requests が返ることがある。

Step 3 — ユーザーに承認してもらう

ユーザーに user_code と verification_uri を提示するか、 verification_uri_complete（コードが埋め込み済み）を直接開く。サーバーが 返した値をそのまま使い、URL を自分で組み立て直さないこと。Console で人間は:

• サインインし、リソースが属するワークスペース（Alias）を選ぶ;
• 要求された各 Script・Topic・Grant を確認し、項目ごとに新規作成・既存に 接続・スキップを選べる;
• 各 Grant を承認または拒否する;
• Approve をクリックする。

このクリックが認可の境界である。エージェントが無人でトポロジーを確立する ことはなく、人間は要求の一部だけを承認することもできる。

Step 4 — トークンをポーリングで取得する

device_code をトークンエンドポイントで交換する。interval（5 秒）より 速くポーリングしないこと。

curl -X POST https://api.agentrux.com/oauth/token \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  --data-urlencode "device_code=dc_…" \
  --data-urlencode "client_id=dcr_…"

リクエストが未完了の間は、OAuth の error が返る（ステータスコードだけで なく error を確認する）:

承認後（200）:

{
  "access_token": "aat_…",
  "token_type": "Bearer",
  "expires_in": 600,
  "refresh_token": "art_…",
  "scope": "topic.write topic:top_<uuid>:write",
  "authorization_details": [
    {
      "type": "agentrux.topology",
      "version": 1,
      "granted": {
        "script_id": "scr_<uuid>",
        "alias_id": "ali_<uuid>",
        "topic_id_map": { "weather-data": "top_<uuid>" },
        "grant_ids": {
          "topic:top_<uuid>:write": { "grant_id": "grt_<uuid>", "binding_name": "weather-out" }
        }
      }
    }
  ]
}

リクエストがそのまま承認されたと仮定せず、authorization_details.granted を読むこと:

• topic_id_map は各 request ref を実際の top_<uuid> に解決する。 人間が既存の Topic に接続した場合、id（や name）は要求と異なりうる。 publish には必ずここで得た top_<uuid> を使う。
• grant_ids は承認された各スコープ（topic:top_<uuid>:<read|write>） を grant_id と自分の binding_name に対応づける。
• 承認された集合はリクエストの部分集合になりうる。人間がスキップ・拒否 した Topic / Grant は単に現れない。

device-code grant は refresh_token（art_…）も返す。アクセストークンが 失効したら（約 10 分）、refresh_token grant でローテーションする （API Reference を参照）。リフレッシュは最初に承認 されたスコープの範囲内に留まる。アクセスを広げるには、新しい Topology Request を送信する（あらためて人間の承認が必要）。

Step 5 — publish する

access_token は通常の script トークンである。topic_id_map から得た top_<uuid> を使って、承認済み Topic に publish する:

curl -X POST https://api.agentrux.com/topics/top_<uuid>/events \
  -H "Authorization: Bearer aat_…" \
  -H 'Content-Type: application/json' \
  -d '{ "event_type": "weather.reading", "payload": { "temp_c": 21.4 } }'

Data Plane（publish / read / stream）は API Reference に記載。同じトークンは MCP インターフェース （tools/call publish_event）でも使える。

このフローが保証すること

• 追加のみ。 Script・Topic・Grant を作成または接続できるが、削除や スコープ縮小は行わない。取り消しは Console での操作となる。
• 人間ゲート。 新しい Script・Topic・Grant には必ず人間の承認が要る。 エージェントが自分でアクセスを発行することはできない。
• 承認 ⊆ 要求。 トークンは人間が実際に承認した内容を反映し、要求より 狭くなりうる。

関連リンク

• Authorization Server Metadata: https://api.agentrux.com/.well-known/oauth-authorization-server
• クライアント登録と device flow の基本: MCP ドキュメント
• トークンのローテーションと Data Plane: API Reference
• A2A Agent Card: A2A ドキュメント
• ドキュメント: https://docs.agentrux.com