A2A Protocol Model #

This page explains how kiro-discord-bot implements its A2A-like integration. It is the conceptual companion to Enable A2A with NATS. Operators can use this page to understand the keywords shown by /doctor, /a2a peers, /a2a status, and the built-in bot-tools MCP tools.

This project does not expose a public A2A HTTP server. It implements a custom internal NATS binding that preserves A2A task concepts where they matter: agent cards, skills, tasks, status, artifacts, cancellation, input/auth replies, durable state, and explicit authorization.

Design Summary #

Mental Model #

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

One bot process can publish multiple runtime peers, one per enabled/discoverable channel or thread policy. A remote peer should delegate to the runtime peer, not to the bot process as a whole.

Normal User Flow #

First run /a2a peers in the relevant channel and copy the bot/channel ID shown for the channel you want.

Receiver-side consent is simple: in the receiving channel, run /a2a allow peer_agent:<bot/channel ID from /a2a peers> or tell the bot to allow that bot/channel to delegate. Normal consent applies immediately for that exact bot/channel runtime when it does not widen an existing skill restriction; it is not a wildcard bot-prefix grant and not bidirectional trust.

Sender-side delegation is also high level: run /a2a ask peer_agent:<bot/channel ID from /a2a peers> message:<task> or ask the bot to delegate the task in natural language. Normal delegation does not require a capability ID, target channel label, or reply-mode fields. If multiple targets match, the bot asks for disambiguation instead of guessing.

Same Discord guild+channel/thread means conversation collaboration: both sides can share the same transcript when receiver policy and Discord permissions allow it. A different channel means the receiver starts work in its own channel/thread and the result returns to the requester. A queued delegation is not acceptance or completion; check /a2a status or bot_a2a_task_status for authoritative state.

Keyword Glossary #

Identity Model #

Bot Base Identity #

A2A_AGENT_ID identifies the bot process and credential owner:

A2A_AGENT_ID=adam-n200

It must be stable and subject-safe. It is used to derive runtime IDs and to display bot host identity in audit/doctor output. In runtime mode it is not the user-facing peer route by itself.

Runtime Agent ID #

A runtime ID identifies one channel or thread runtime:

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

If the alias is unsafe, too long, private, colliding, or contains raw Discord snowflake-like digits, the implementation falls back to a short hash:

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

Examples:

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

Runtime IDs must remain stable across restarts. They must not include PID, boot timestamp, random suffix, raw Discord snowflake, private host path, or secret material.

Channel Reference #

channel_ref is an operator-readable, subject-safe alias for the runtime channel. It is not the primary durable route in runtime mode, but it appears in peer cards, policy displays, and skill context.

Allowed shape:

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

Avoid dots, spaces, slashes, wildcard characters, and private channel names unless a manager intentionally makes the alias public.

Runtime ID Modes #

New deployments should use A2A_RUNTIME_ID_MODE=runtime.

NATS Subject Schema #

All production task/control/event traffic uses JetStream. Subjects use the a2a.v1 prefix.

Common event/control kinds:

accepted
rejected
status
artifact
result
cancel
input_reply
auth_reply

Old unversioned subjects such as a2a.task.{agent-id}, a2a.status.{task-id}, and a2a.announce are not used.

JetStream Topology #

The implementation uses these streams:

Consumers are runtime-targeted. A runtime consumes only task/control/event subjects addressed to its exact runtime ID.

Task Lifecycle #

1. The delegator validates local outbound policy.
2. The delegator publishes a task message with a stable Nats-Msg-Id.
3. The executor validates inbound subject, envelope, sender, policy, skill, quota, and runtime context.
4. The executor stores the admitted task durably before acknowledging the JetStream message.
5. The executor runs the task in its own Discord channel or thread runtime.
6. The executor publishes accepted, status, artifact, and result events.
7. The delegator stores received events and reports status through /a2a status or bot_a2a_task_status.

The system is at-least-once, not exactly-once. Durable idempotency prevents duplicate terminal effects when NATS redelivers messages.

Task States #

An accepted event is an event and state transition into TASK_STATE_WORKING; it is not a distinct TaskStore state. A queued tool call is not a completed remote task. Always check task state before reporting completion.

Policy Model #

A2A policy is owned by the channel runtime. Important fields:

Legacy fields such as accept_from, delegate_to, and delegate_skills are compatibility inputs only. New setup writes canonical runtime fields.

Delivery and Transcript Modes #

trusted=true does not imply transparent or co-present readiness. For direct same-thread replies, the opposite bot's inbound policy, co-present allowlist, target channel policy, and Discord send permissions must all pass.

Security Boundaries #

A2A does not bypass existing bot boundaries:

• Remote tasks do not gain extra MCP tools unless the executor channel policy exposes them.
• Remote tasks do not get memory-write permission unless allow_memory_write=true is explicitly set.
• Discord delivery still uses safe egress and AllowedMentions guards.
• Confirmation tokens protect policy changes and sensitive remote delegation.
• /doctor redacts tokens, credentials, TLS material, private paths, and sensitive environment values.
• Heartbeat is liveness only; it is not authorization.

Operator Surfaces #

Do not inspect or edit raw data/a2a/*.sqlite files for normal operation.

Related Pages #

• Enable A2A with NATS
• A2A NATS Rollout
• Environment Reference
• Bot Tools MCP
• Security Model