Skip to Content
A2A agents

A2A agents

Roadmap

This capability is on the Roadmap; the API shown here is the planned design.

Three steps take an agent from “runs on my laptop” to “callable by other agents, through the gateway”: serve it, expose it, and develop against a gateway locally. The protocol is the official a2a-sdk, wrapped; the SDK adds the governance around it.

Why the agent still runs a listener

An A2A agent is a server: it serves an agent card at a well-known path and answers JSON-RPC task calls. Something must accept the socket, so the SDK hides that listener behind one line rather than removing it.

What it can remove is everything painful around the listener — TLS, auth, rate limits, public exposure, and registration. Those are the gateway’s job. Omni Gateway is an Envoy-based data plane whose policies compile to WASM; it runs as a separate process in front of your agent, not as a library inside it.

Enforcement stays outside the agent’s process. If the enforcement point lived inside the agent, the agent’s own code could bypass it. The gateway’s value depends on being outside the thing it governs.

donkey serve — the listener, in one line

@donkey.agent(name="support-triage", skills=["triage", "draft-reply"])
async def handle(task: A2ATask) -> A2AResult:
    return await graph.ainvoke(task.input)
 
donkey.serve(handle)      # A2A server on 127.0.0.1:8000, card auto-generated
  • The card is generated from your code — the same @donkey.tool / @donkey.agent markers the scanner reads — so there is no second description of your agent to keep in sync.
  • It binds to localhost by default, so your agent is never the public face; the gateway is.
  • Inbound calls are governed. Every call arriving over A2A gets the same treatment as an outgoing one: correlation ID, cost tags, an OTel span, and typed refusals when the agent’s own downstream calls are blocked.

donkey expose — the ingress, registered from code

$ donkey expose --env prod
  ✓ A2A proxy  https://gw.acme.internal/agents/support-triage
  ✓ policies   token-budget, pii-detection, trusted-agent-identity
  ✓ registry   support-triage v1.4.0

The gateway does the work — provisioning the A2A proxy, attaching the policy set, and registering the card. donkey expose turns that console session into one command that runs in CI.

donkey dev — a gateway in front of your laptop

donkey dev puts a gateway in front of donkey serve on your machine, so you can call your agent over A2A through governance before deploying. Two modes are planned:

  • A real gateway. Where a self-managed Omni Gateway image is available for local development, donkey dev runs it alongside donkey serve, so A2A calls pass through real policies.
  • Simulated ingress. The local simulator gains an A2A ingress mode: a local fake gateway in front of donkey serve, replaying the same rejection fixtures. A plain A2A client sees byte-identical responses, and every response carries x-donkey-simulator: true.
Last updated on
A2A agent toolsScan & publish