Skip to content

Remote A2A Agents

Backend.AI GO can register an externally operated agent from an Agent2Agent (A2A) agent card. A remote agent stays identifiable as Remote (A2A) and is not treated as a local model, model provider, or MCP server.

Connect an agent

  1. Open Agent Extensions.
  2. Select Connect remote agent.
  3. Enter the agent card URL. Use HTTPS except for a service on a loopback address such as 127.0.0.1.
  4. Add a bearer token if the card is private. Under Advanced authentication, you can add custom headers and change the request timeout.
  5. Select Connect.

Backend.AI GO fetches the card, checks the A2A version and same-origin RPC endpoint, and saves the public identity, skills, and capabilities. Credential values are stored in the system credential vault. Profile reads show only whether a bearer token is configured and the names of configured headers, never their values.

Use a remote agent

A connected remote agent appears in the same target selectors as local agent profiles. You can select it for a conversation, mention it with @, add it to a Squad from its profile, or enable it as a delegate target. Remote cards display their destination and advertised skills so you can see where work will run.

Messages sent to a remote profile leave this device. Direct chat and mentions send the current request. Squad execution sends only the assigned task title and description; it does not automatically send dependency outputs, workspace files, local chat history, operator steering, or local tool credentials.

CLI registration

Keep secrets out of shell history and process arguments by placing them in environment variables:

export AIGO_AGENT_TOKEN='...'
export AIGO_AGENT_API_KEY='...'
aigo agent-profile register-remote \
  https://agent.example/.well-known/agent-card.json \
  --bearer-token-env AIGO_AGENT_TOKEN \
  --header-env X-API-Key=AIGO_AGENT_API_KEY \
  --timeout 300

The command prints the registered profile without credential values.

Cancellation and remote task lifetime

Stopping chat, delegation, or Squad work interrupts local waiting promptly and releases local reservations. If the remote task ID is known, Backend.AI GO makes one authenticated cancellation attempt: tasks/cancel for A2A 0.3 or CancelTask for A2A 1.0. SSE events retain the task ID while the stream is open. Timeouts and dropped background requests use the same cleanup path.

Remote cleanup has an independent two-second deadline. It does not delay the local Stop control. Direct chat records the result in a request-specific notification: confirmed remote cancellation, an already-ended task, refusal, or unconfirmed cancellation. Only a matching remote task response in the canceled state confirms cancellation. Unsupported methods, a missing task ID, a missing remote task, transport failures, and cleanup deadline expiry do not prove that the remote task stopped. It may still consume resources; use the remote service controls to inspect it. General remote task listing is not supported.

The cancellation API returns localInterrupted separately from remoteCancellation (confirmed, alreadyTerminal, refused, notFound, unsupported, or unknown). A locally interrupted request or an absent local request is never reported as confirmed remote cancellation. The interrupted send request itself fails with HTTP 409 and code remote_agent_cancelled. It returns before the remote attempt finishes, so it says nothing about the remote task; read the outcome from the cancellation API.

Connection errors

Registration rejects missing credentials, unsupported A2A versions, non-HTTPS public URLs, card RPC URLs on a different origin, unsafe destinations, invalid custom headers, and oversized responses. Correct the named field or remote service configuration and connect again. Removing a remote profile also removes its saved credentials.

Publish an agent from another GO instance

On the serving instance, publish a saved local profile and copy its authenticated A2A card URL from the connection panel. Register that URL here with a Management API key carrying agent_invoke. Remote registration still applies the URL and transport restrictions described above. See Agent endpoints for publishing and caller approval examples.