Agent-to-Agent (A2A)

The Agent2Agent (A2A) protocol is an open standard for communication between independent agents. An agent publishes an Agent Card that describes what it can do, where to reach it and how to authenticate. Other agents send it messages over JSON-RPC and follow the resulting task until it is done. Agents stay opaque to each other. They share results, not internals.

Unique supports A2A 1.0 in both directions through an optional A2A gateway:

• Way in. A Space Admin publishes a space as an A2A agent. External agents call it.

• Way out. A Space Admin connects an external A2A agent as a space. Users chat with it, and other spaces use it as a sub-agent.

Way in: publish a space as an A2A agent

One published space is one A2A agent. Every Space Admin can publish the spaces they manage.

1. Open the space in the admin interface and go to Advanced Settings.

2. Open the A2A section and switch A2A publication to Enabled.

3. Fill in the Agent Card. Only these fields are shown to callers. Internal names, models, prompts and tools stay private.

4. Click Publish. The section now shows the Agent Card URL, the Agent URL and the state Published.

Share the Agent Card URL with the team that integrates the external agent. Everything they need is in the card.

To stop publishing, switch A2A publication to Disabled. New calls are rejected immediately. Tasks that are already running finish and stay readable for their owner. Deleting the space also retracts the publication.

Only native spaces can be published. An A2A External Agent space (see below) can never be published again over A2A.

Way out: connect an external A2A agent

An external agent is connected as a space of its own type. Nothing is discovered automatically. You enter the Agent Card URL, provide the credential the agent asks for, test the connection, and save.

1. In the admin interface, click Create Space and choose A2A External Agent.

2. Enter a Name and Description. These are shown to your users.

3. Enter the Agent card URL of the external agent. HTTPS only. The host must be on the allowlist configured by your IT operator.

4. Unique reads the Agent Card and shows the Authentication the agent requires. Enter the matching credential.

5. Click Test connection. The Agent preview shows the agent's name, version, provider, skills, authentication and whether it supports streaming.

6. Optionally enable Sub-Agent so other spaces can delegate to this agent.

7. Click Create external space. Then grant users access as for any other space.

Authentication follows the Agent Card

The external agent declares in its Agent Card which security schemes it accepts. Unique supports every scheme defined by A2A 1.0 and uses the one the card requires. You only provide the credential.

If the card offers several schemes, you pick one. If the card changes its requirements later, the connection test tells you what is missing.

Shared or on behalf of the user. With a shared credential, every user of the space calls the external agent with the same identity, and the external agent does not see individual Unique users. With a per-user flow, Unique calls the external agent on behalf of the signed-in user, exactly as external agents call Unique inbound. The external agent then applies that user's own permissions. Users who have not signed in yet are asked to do so in the chat the first time they use the space.

Secrets are write-only and encrypted. Use Rotate credential to replace a client secret, key or certificate without recreating the space. Per-user tokens are refreshed automatically and revoked when the user's access to the space is removed.

Model, tools and instructions of an external space are managed by the external provider. The space therefore has no module, prompt, model or knowledge settings, and it cannot be duplicated, exported or imported.

Using an external agent

• Direct chat. Users with access open the space and chat as usual. Answers stream in. Structured data is shown as JSON, files are attached to the chat, and Stop cancels the remote task.

• As a sub-agent. Enable Sub-Agent on the external space and add it in the parent space under Sources & Tools → Sub-agents, exactly like a native sub-agent. See Sub Agent.

• Clarifications. If the external agent needs input, the user gets a form in the chat. If it needs a login, the user gets a link. Nothing is approved automatically.

Identity and permissions

For developers: calling a published space

A published space behaves like any A2A 1.0 agent with the JSON-RPC binding. Use the official A2A SDK of your framework or plain HTTPS.

Authentication. Let the user sign in to your Unique tenant with the standard OpenID Connect authorization code flow with PKCE. Send the resulting access token as Authorization: Bearer. Each request needs a valid token for the same user. A running task continues when the token expires. You need a fresh token to read it again.

Mapping.

Supported operations. SendMessage, SendStreamingMessage, GetTask, ListTasks, CancelTask, SubscribeToTask, push notification configuration and GetExtendedAgentCard. Streaming uses server-sent events. A non-streaming SendMessage waits up to 30 seconds and then returns the task in state WORKING for polling.

Inputs. text parts, data parts and file parts with inline bytes. File parts by URI are rejected.

POST {Agent URL}
Authorization: Bearer {access token}
A2A-Version: 1.0
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "parts": [{ "text": "Summarise the Q3 risk report." }]
    }
  }
}

Limitations

• A2A 1.0 with the JSON-RPC binding only. No 0.3, no REST or gRPC bindings, no protocol extensions, no signed Agent Cards.

• Inbound calls require a signed-in human user. Machine-to-machine clients are not supported.

• Per-user authentication to an external agent requires the agent to offer an OAuth 2.0 or OpenID Connect flow with user sign-in. API keys, HTTP schemes and client credentials are always shared.

• Unique does not use push notifications as a client. It streams or polls the external agent.

• Streaming is limited to 20 concurrent streams per user.

Related

• Sub Agent

• Agent-to-Agent Architecture

• A2A 1.0 specification