A2A (Agent-to-Agent)

A2A (Agent2Agent) is an open protocol that lets one agent platform call agents hosted on another. Every VirtuAI agent can be reached over A2A. A caller finds the agent through its Agent Card, then sends it messages with an OAuth 2.0 token you control.

Use A2A to add a VirtuAI agent to Gemini Enterprise, or to call it from your own services.

What VirtuAI supports


Protocol versions	A2A 1.0 and 0.3, on the same endpoint
Transport	JSON-RPC 2.0 over HTTPS, with streaming
Input and output	Text
Push notifications	Not supported
Authentication	OAuth 2.0 authorization code (with optional PKCE), client credentials and refresh token
Scope	`a2a:invoke`: send messages to the agent and read its tasks

The two URLs

In the agent’s Integration URLs you’ll find:

Item	URL	Needs a token
A2A Agent Card	`https://<your-virtuai-host>/a2a/<agent-id>/.well-known/agent-card.json`	No
A2A Endpoint (JSON-RPC)	`https://<your-virtuai-host>/a2a/<agent-id>`	Yes

The Agent Card is public on purpose: callers read it before they authenticate. It describes the agent’s name, description and skills, and where to get a token. It never gives access by itself.

Most platforms ask for the card URL. Some ask for the endpoint instead.

1. Create an A2A client

Each service that calls your agents gets its own client.

Open Settings and find A2A Clients.
Enter the name of the consuming service, for example Gemini Enterprise, and select Create client.
Copy the Client ID, Client secret, Token URL and Scopes. Then select I’ve copied the secret.

A client created here can call every agent in the workspace. Its sign-in redirects are limited to Gemini Enterprise’s redirect addresses.

2. Register the agent in the other platform

Give the consuming service:

Field	Value
Agent Card URL	The agent’s A2A Agent Card URL
Authorization URL	`https://<your-virtuai-host>/a2a/oauth/authorize`
Token URL	`https://<your-virtuai-host>/a2a/oauth/token`
Client ID and secret	From step 1
Scope	`a2a:invoke`

For Gemini Enterprise, see Google’s guide to registering an A2A agent.

How callers authenticate

On behalf of a person (authorization code). This is what Gemini Enterprise uses. The first time someone uses the agent, they’re sent to VirtuAI and sign in. An Authorize access page shows which service is asking and what it may do. They select Allow or Deny.

If the agent’s tools act on that person’s own accounts, such as Gmail or Drive, the page lists them under These agents also act on your accounts. They can Connect each one now, or wait until the agent needs it.

After they allow access, the agent runs as that person, with their connected accounts. Access tokens last 1 hour. Refresh tokens last 30 days and are replaced each time they’re used.

As a service (client credentials). A backend service with no person behind it trades its client ID and secret at the token URL for a 1-hour access token. It doesn’t need the authorization URL or PKCE.

Send the token on every call:

POST /a2a/<agent-id> HTTP/1.1
Host: <your-virtuai-host>
Authorization: Bearer <access-token>
Content-Type: application/json

Revoke access

In Settings > A2A Clients, select the trash icon next to a client and confirm. Its tokens stop working immediately, and any service using it loses access.

Limits to keep in mind

A token only works for agents in the workspace that issued it.
Attachments aren’t accepted. Send text.
The agent can’t ask a person to approve commands over A2A, so it runs them without asking. See Command approvals.

Troubleshooting

401 “Missing bearer credential” or “Invalid credential” : The call has no token, or the token expired or was revoked. Get a new one.

403 “Credential is not authorized for this agent” : The token belongs to another workspace than the agent.

The consuming service can’t finish the sign-in : Its redirect address isn’t one VirtuAI allows for this client. Clients created in Settings only allow Gemini Enterprise’s addresses. Contact Support for other platforms.

404 “Agent not found” : Check the agent ID in the URL, and that the agent is active.