Skip to main content
An agent delegates to an agent in another workspace over A2A: the target’s address, and a key bound to the target agent kept as a secret in the caller’s workspace. The two workspaces may belong to different people. The same steps reach any A2A v1.0 agent, not only one on AgentArea. The example below lets personal-assistant in the personal workspace hand documentation work to docs-writer in the aadocs workspace.

​
Prerequisites

  • Someone who is a member of aadocs issues the key. It acts as them, so a delegated task in aadocs is started by them.
  • You administer the calling workspace. Pointing a secret at an address sends the secret there, so only an admin may add or change that binding.

​
Steps

1

Issue a key for the target agent

In aadocs, open docs-writer → Settings → A2A access. Copy the agent’s Address, then select Issue key, name it after the caller, for example personal, and copy the key; it is shown once. Or:
The key reaches docs-writer over A2A and nothing else: no other agent, no data in aadocs, no REST route. Revoke it in the same section to cut the caller off.
2

Store the key as a secret in the calling workspace

In personal, open Secrets and create a secret named aadocs-key with the key as its value, or:
The agent keeps only the secret’s name. The value is read when the agent delegates, so rotating the key means updating this secret, not the agent.
3

Add the delegate to the calling agent

Open personal-assistant → Settings → Delegation → Agent, and fill in External agent (A2A):Select Add external agent, then Save changes. Through the API, the same delegate is one entry in the agent’s tools; the update replaces the whole list, so send every tool the agent should keep:

​
Verify

Start a task on personal-assistant that needs the delegate, for example “Write a one-sentence doc for add(a, b) and delegate it to docs-writer”. The task’s activity shows a delegate_to_docs_writer call, and a new task for docs-writer appears in the aadocs workspace, started by whoever issued the key.

​
Troubleshooting

Nothing at the address serves /.well-known/agent-card.json. Use the address from A2A access, not the JSON-RPC URL. For another A2A server, use the origin or base URL its card is published under.
No valid key reached the target. Check that Token names a secret, and that the secret holds a key that has not been revoked and whose issuer is still a member of the target workspace.
The key is bound to a different agent, or it is a key for another workspace. Issue one from the target agent’s A2A access.
The remote card points its endpoint at another host. The token is sent only to the address you configured, so the delegate refuses. Configure the host the card names as the address instead.
Adding a delegate with a Token, or changing its address or token, needs a workspace admin in the calling workspace. Ask one to add the delegate.
The detail names the delegate and the problem: a secret that does not exist or is managed by a connection, an address that is not http(s), or two delegates whose names become the same tool name.
The secret was renamed or deleted after the delegate was added. Recreate it under the same name, or pick another one on the delegate.
The outbound guard refused the address. Use the public one. A self-hosted deployment that must reach an internal host names it in OUTBOUND_PRIVATE_ALLOWLIST on the worker and the API.
The target did not finish within the 110-second A2A delegation budget. The task keeps running in the target workspace; its result does not come back to the caller.

Agent-to-agent communication

Delegation, the A2A binding, and its limits

Issue access tokens

Create, scope, rotate, and revoke API keys

Create and configure an agent

Create an agent and give it a model, instructions and tools
Last modified on October 2, 2026