Agent Discovery¶
Sites can publish an A2A agent at /.well-known/agent-card.json. With the a2a-cli plugin, your coding agent learns about the agent of a site when that site comes up in the conversation, and asks you before it delegates to it. This example serves a made-up documentation site with an agent at docs.acme.test, and asks opencode a question about it.

Prerequisites¶
a2a, Go and Docker, as in OpenCode Calls a Contact, whoserun-opencodethis example uses.- A Gemini API key in
GEMINI_API_KEY.
Run the commands in this directory. Serve the site in a second terminal:
go run ./site --addr 127.0.0.1:8080 --url http://docs.acme.test:8080
site/main.go serves three things: a page about the rate limits of the "Acme Payments API" that leaves out the retry policy, an agent card for the "Acme Docs Assistant" with a skill for exactly that, and the agent. The agent has no model and gives the same answer every time.
Point a name at the site¶
Discovery works on real host names, so give the site one. Outside Docker, add it to /etc/hosts:
echo "127.0.0.1 docs.acme.test" | sudo tee -a /etc/hosts
run-opencode runs opencode in a container, which takes the name from --add-host instead:
export OPENCODE_DOCKER_ARGS="--add-host docs.acme.test:127.0.0.1"
Ask opencode¶
Start opencode:
../opencode-contacts/run-opencode
Ask it about the site:
Read http://docs.acme.test:8080/ and tell me how my client should handle 429s from the Acme Payments API.
opencode fetches the page. The plugin sees the URL, finds the site's agent card, and adds it to the fetch result as an unverified agent. The page doesn't have the answer, so opencode offers the agent and asks first:
% WebFetch http://docs.acme.test:8080/
The documentation at http://docs.acme.test:8080/ indicates that requests exceeding your limit return an
HTTP 429, but specific retry policies and limits are not listed on that page.
It suggests consulting the Acme Docs Assistant, an A2A agent available at the same origin. Would you like me
to ask it how your client should handle 429s?
Say yes:
Yes, ask it.
opencode runs a2a send -a http://docs.acme.test:8080 "..." and answers from the agent's reply:
To handle HTTP 429 responses from the Acme Payments API, your client should follow this retry policy:
1. Respect Retry-After: If the response includes a Retry-After header, wait for the specified number of
seconds before retrying.
2. Exponential Backoff: If the header is missing, use exponential backoff starting at 1 second, doubling the
wait time up to 32 seconds, and include jitter.
3. Maximum Attempts: Give up after 5 attempts and report the error.
4. Idempotency: Only retry POST /v2/charges using the same Idempotency-Key to ensure a charge is not applied
multiple times.
The site's terminal shows the probe of the agent card, then the A2A request. To script the same exchange, use run-opencode run "<prompt>" and then run-opencode run --continue "Yes, ask it.".
How it works¶
When a URL appears in a prompt or a web fetch, the plugin runs a2a hook, which checks the card cache for the URL's origin. An origin it hasn't seen is probed by a detached a2a hook probe, which fetches /.well-known/agent-card.json; for a web fetch the plugin waits briefly for the probe, so the agent arrives with the fetch result. Each agent is reported once per session.
Discovered agents are marked unverified: the context tells opencode to ask you before delegating or sending data to them, and to treat the card's text as data, not instructions. To trust one, save it as a contact with a2a contact add acme-docs http://docs.acme.test:8080.
Coding Agents describes discovery and its settings, and Security where probes may connect. Set discovery: false in ~/.config/a2a-cli/config.yaml to turn it off.
Clean up¶
Stop the site with Ctrl-C, remove the /etc/hosts line if you added it, and remove the volumes run-opencode created:
docker volume rm a2a-example-opencode-data a2a-example-opencode-cache