Remote agents and trusted installs
Agents calling agents covers calls between the agents of one project. This page covers the other direction: your agents calling an agent that runs outside the project, on another platform or on another Orchestrate install, over the Agent2Agent protocol.
Remote agents, agent identity and trusted installs are part of the code agents feature. While your operator has code agents switched off, the A2A surface answers 404. See Code agents.
Add a remote agent
A remote agent is a connector of type Remote agent (A2A). You need the developer or admin role on the project.
-
Open Connectors and choose Add connector > Remote agent (A2A).
-
Fill in:
Field What it is Agent card URL Where the agent publishes its A2A card, usually …/.well-known/agent-card.json.Name for your agents What your agents call it: the tool agent:<name>. Lowercase letters, digits and dashes, at most 40. It must not clash with an agent of the project.Authentication None, a bearer token, or an API key in a header you name. The secret goes to Vault and is never shown again. Endpoint URL Optional. Only when the agent is served from another host than its card. Binding How calls are sent: as the card prefers (the default), JSON-RPC, HTTP+JSON or gRPC. A binding the card doesn't offer falls back to the card's first. Stream answers On by default. When the card says it can stream, the answer arrives as the agent writes it, with no polling. Time limit Per call, 1 to 600 seconds, default 120. A task still working then is cancelled. Description for the model What your agents are told it does. Empty uses the card's description. Only answers questions Marks it read-only. See Approval. -
Save, then choose Refresh card on the connector's panel. Calls fail until the card has been read.
The card is read by the tool execution service, through the connector sandbox: redirects aren't followed, sizes are capped, and the platform's own services, loopback and cloud metadata addresses are always refused. The card's JSON-RPC address must be on the card URL's origin, unless an admin sets Endpoint URL. The panel shows the card's protocol version, provider, skills, the bindings it offers and whether it streams.
Orchestrate speaks A2A 1.0 and the older 0.3 message/send.
Give it to an agent
Pick agent:<name> in an agent's tools, under Agents, the same way as one of the project's own agents. The model sees a tool named agent__<name> that takes one message.
Each call goes through the same checks as a call to one of your own agents: who may call it, the caller's tool list, policy (the policy engine sees remote: true, the connector and whether the call writes), the call-depth limit, budgets and rate limits. It writes the same agent_call audit events, plus its own tool-call event, trace span and usage. See The checks on every call.
Approval
Nothing on this platform governs what an outside agent does with a request, so a remote agent counts as a write: every call waits for a person to approve it, on text and voice alike, and an eval run never sends it. Turn on Only answers questions for an agent that only reads, and its calls run without approval.
When the remote agent asks a question
A remote task can stop and ask for more input (A2A's input-required state). Your agent's model gets the question back, with a note, and can answer it on its next call to the same remote agent in the same conversation. Orchestrate keeps the remote task and context ids per calling agent, remote agent and conversation, so that next call continues the same remote task instead of starting a new one. A context is kept for 30 days.
If the remote agent no longer knows the task, the message is sent as a new one.
Agent identity and sponsor
Every agent has an Identity block in its A2A section:
- Principal: who the agent is on every audit event and policy decision,
agent:<project>/<name>, whichever key or run carries the call. - Sponsor: optional. The person who answers for the agent, such as
name@example.com. It goes with every call the agent makes, on the audit record and to the policy engine, so a policy can decide on it.
A project admin sets the sponsor.
Trusted installs
A call chain (A calls B calls C) is cut at a depth limit, so a loop stops. Across installs, the remote side can't see your depth unless it trusts you. Trusted installs fix that.
Each install has an identity: an install id and a signing key, created with code agents. Its identity document is a signed, one-line text with the install id, its public key and its A2A address. It holds no secret.
To trust another install, on a project:
- Open Connectors > Trusted installs and choose Show identity document. Send it to the other install's project admin.
- They do the same and send theirs.
- Choose Trust an install, paste their document, give it a label and choose Trust it. Its signature is checked against the key it names, and that key is pinned.
Each side does this, so the trust is mutual. Adding and removing a trusted install are audited.
The call chain
Once installs trust each other, every agent-to-agent call between them carries a signed call-chain claim with a chain id and the current depth. The receiving install reads the depth from it, so the depth limit holds across both installs. A loop such as A here, B there, A here again, even through public card URLs, is still cut.
The remote agent's panel tells you which case applies:
| Case | What it means |
|---|---|
| This install | The card is this install's own, reached through its public URL. Calls carry the chain. |
| Trusted install | It runs on an install this project trusts. Calls carry the chain. |
| Outside agent | Calls carry no chain. Nothing about the chain leaves your install, and the remote side counts depth from its own start. |
The claim names no project, agent or person. A claim signed by a key the install doesn't know is ignored and the call is audited as untrusted. A claim from a known key that doesn't verify, has expired or names another audience is refused.
Cross-install calls need each install's A2A address to be reachable by the other, through the operator's exposure settings. See Configuration.