A2A 協議模型 #

本頁說明 kiro-discord-bot 如何實作 A2A-like 整合。它是 使用 NATS 啟用 A2A 的概念補充。Operator 可用本頁理解 /doctor、/a2a peers、/a2a status 與內建 bot-tools MCP tools 中出現的關鍵字。

本專案沒有公開 A2A HTTP server。它實作的是內部 custom NATS binding，但保留重要 A2A task concepts：agent cards、skills、tasks、status、artifacts、cancellation、input/auth replies、durable state 與 explicit authorization。

設計摘要 #

心智模型 #

Discord bot process/account = transport host 與 runtime container
Discord bot + guild + channel/thread + A2A policy = runtime agent
NATS-visible AgentID = runtime_agent_id

一個 bot process 可以發布多個 runtime peers，每個 enabled/discoverable channel 或 thread policy 各一個。遠端 peer 應委派到 runtime peer，而不是整個 bot process。

一般使用流程 #

先在相關頻道執行 /a2a peers，複製清單中你要協作的 bot/頻道 ID。

Receiver 端同意很簡單：在接收工作的頻道執行 /a2a allow peer_agent:<來自 /a2a peers 的 bot/頻道 ID>，或直接告訴 bot 允許該 bot/頻道委派。一般 consent 在不放大既有 skill restriction 時會直接套用到該精確 bot/頻道 runtime；不是 wildcard bot-prefix grant，也不是 bidirectional trust。

Sender 端委派也維持高階語意：執行 /a2a ask peer_agent:<來自 /a2a peers 的 bot/頻道 ID> message:<任務>，或用自然語言請 bot 委派任務。一般委派不需要能力 ID、目標頻道標籤或回覆模式欄位。若有多個目標符合，bot 會要求釐清，而不是猜測。

同一個 Discord guild+channel/thread 代表對話協作：receiver policy 與 Discord permissions 都允許時，雙方可共享同一段 transcript。不同 channel 則由 receiver 在自己的 channel/thread 開始工作，結果再回到 requester。已 queue 的 delegation 不代表 accepted 或 completed；請用 /a2a status 或 bot_a2a_task_status 查權威狀態。

關鍵字表 #

Identity Model #

Bot Base Identity #

A2A_AGENT_ID 代表 bot process 與 credential owner：

A2A_AGENT_ID=adam-n200

它必須穩定且 subject-safe。它會用來產生 runtime IDs，並在 audit/doctor 中顯示 bot host identity。Runtime mode 中，它本身不是 user-facing peer route。

Runtime Agent ID #

Runtime ID 代表一個 channel 或 thread runtime：

runtime_agent_id = <bot-prefix>-<public-channel-alias-slug>

如果 alias 不安全、太長、隱私風險、碰撞，或包含 raw Discord snowflake-like digits，實作會 fallback 到短 hash：

runtime_agent_id = <bot-prefix>-rt-<short-hash>

範例：

remote-bot-erp-support
remote-bot-backend
m5bot-main
m5bot-rt-4f8a9c01

Runtime IDs 必須在 restart 後保持穩定。不得包含 PID、boot timestamp、random suffix、raw Discord snowflake、private host path 或 secret material。

Channel Reference #

channel_ref 是 operator-readable、subject-safe 的 runtime channel alias。Runtime mode 中它不是主要 durable route，但會出現在 peer cards、policy display 與 skill context。

允許格式：

[A-Za-z0-9_-]{1,64}

避免 dots、spaces、slashes、wildcards 與 private channel names，除非 manager 明確要把該 alias 公開。

Runtime ID Modes #

新部署應使用 A2A_RUNTIME_ID_MODE=runtime。

NATS Subject Schema #

所有 production task/control/event traffic 都使用 JetStream。Subjects 使用 a2a.v1 prefix。

常見 event/control kinds：

accepted
rejected
status
artifact
result
cancel
input_reply
auth_reply

不使用舊的 unversioned subjects，例如 a2a.task.{agent-id}、a2a.status.{task-id} 與 a2a.announce。

JetStream Topology #

實作使用這些 streams：

Consumers 是 runtime-targeted。一個 runtime 只 consume address 到自己 exact runtime ID 的 task/control/event subjects。

Task Lifecycle #

1. Delegator 驗證本地 outbound policy。
2. Delegator 用穩定 Nats-Msg-Id publish task message。
3. Executor 驗證 inbound subject、envelope、sender、policy、skill、quota 與 runtime context。
4. Executor 在 ack JetStream message 前，先 durable store admitted task。
5. Executor 在自己的 Discord channel 或 thread runtime 執行 task。
6. Executor publish accepted、status、artifact 與 result events。
7. Delegator 儲存收到的 events，並透過 /a2a status 或 bot_a2a_task_status 回報狀態。

系統是 at-least-once，不宣稱 exactly-once。NATS redeliver 時，durable idempotency 會避免重複 terminal effects。

Task States #

accepted event 是 event 與 state transition，會讓 TaskStore 進入 TASK_STATE_WORKING；它不是獨立的 TaskStore state。Queued tool call 不代表 remote task 完成。回報完成前務必檢查 task state。

Policy Model #

A2A policy 由 channel runtime 擁有。重要 fields：

Legacy fields 如 accept_from、delegate_to、delegate_skills 只作 compatibility inputs。新 setup 寫入 canonical runtime fields。

Delivery 與 Transcript Modes #

trusted=true 不代表 transparent 或 co-present ready。若要 direct same-thread replies，對方 bot 的 inbound policy、co-present allowlist、target channel policy 與 Discord send permissions 都必須通過。

Security Boundaries #

A2A 不會繞過既有 bot 邊界：

• Remote tasks 不會得到額外 MCP tools，除非 executor channel policy 有 expose。
• Remote tasks 不會得到 memory-write 權限，除非明確設定 allow_memory_write=true。
• Discord delivery 仍使用 safe egress 與 AllowedMentions guards。
• Confirmation tokens 保護 policy changes 與敏感 remote delegation。
• /doctor 會遮蔽 tokens、credentials、TLS material、private paths 與敏感 environment values。
• Heartbeat 只代表 liveness，不是 authorization。

Operator Surfaces #

一般操作不要檢查或編輯 raw data/a2a/*.sqlite files。

相關頁面 #

• 使用 NATS 啟用 A2A
• A2A NATS Rollout
• 環境變數參考
• Bot Tools MCP
• 安全模型