Connecting A2A Clients

A2A clients connect to AireGlu agents over HTTP using the A2A protocol (JSON-RPC) with OAuth 2.0 authentication. AireGlu agents implement the A2A protocol via the official a2a-dotnet SDK at protocol version 1.0.

Endpoints

Every agent exposes two endpoints:

GET  https://<runtime-host>/a2a/<tenancy>/<agent-name>/.well-known/agent.json
POST https://<runtime-host>/a2a/<tenancy>/<agent-name>

The first is the public agent card discovery endpoint. The second is the authenticated JSON-RPC interface used for everything else.

Unlike MCP servers, the agent URL does not include a version segment. A2A clients consume the agent card to learn what version is currently being served, and the default version is selected automatically. To change which version is exposed, update the agent's Default Version.

Copying the Connection URL

1. Navigate to AI Tools > Agents
2. Click the three-dot menu on the agent row
3. Select Copy URL

Agent Card Discovery

The agent card is the A2A protocol's public, unauthenticated discovery document. Calling agents fetch it first to learn what the agent does, what skills it advertises, and how to authenticate.

curl https://<runtime-host>/a2a/<tenancy>/<agent-name>/.well-known/agent.json

The card returned by AireGlu includes:

• name and description from the agent configuration
• version of the currently-default version
• skills advertised by that version
• defaultInputModes and defaultOutputModes
• capabilities — streaming is supported; push notifications are not
• securitySchemes — OpenID Connect against the AireIdentity authority
• securityRequirements — the AireGluAgent scope
• supportedInterfaces — a single JSON-RPC binding pointing at the agent endpoint

Authentication

A2A clients obtain a JWT token from the OpenID Connect provider advertised in the agent card and pass it as a Bearer token on every JSON-RPC request.

The required OAuth scope is AireGluAgent. The user (or service principal) authenticated by the token must hold the run:Agent permission for the request to be authorised.

1. The client fetches OpenID Connect metadata from the URL in the agent card
2. The client obtains a token via OAuth 2.0 (typically authorization code or client credentials, depending on the client)
3. The token is included as a Bearer token in subsequent JSON-RPC requests
4. AireGlu validates the token, checks for run:Agent, and resolves the tenant

Troubleshooting

Issue	Cause	Fix
404 on agent card	Agent or its default version is inactive, or no default is set	Check the Active toggle on both the agent and its versions; confirm a default version is set
401 Unauthorized	Invalid or expired token, or missing run:Agent permission	Re-authenticate; confirm your account has the run:Agent claim
Token tenant mismatch	Token was issued to a different tenant than the URL	Use a token issued to the same tenant the agent belongs to
405 Method Not Allowed on agent endpoint	Client called something other than POST	A2A JSON-RPC uses POST only
No tools available to the agent	No MCP servers configured, or referenced servers are missing	Edit the agent version and add or fix MCP server references