Quick start
Updated on 11 November 2026.
This guide puts one agent behind the A2A Gateway and calls it. It takes about five minutes.
Before you start: you need an agent that speaks A2A on an HTTPS address, and either publishes an agent card or has card JSON you can upload. For an agent that does not speak A2A (Amazon Bedrock AgentCore, Vertex AI Agent Engine, Azure AI Foundry or an HTTP API), see Wrapped agents.
1. Add the agent
-
Go to Settings > AI Gateway > A2A Gateway and click Add agent.
-
Keep Agent card URL selected and paste the agent's card URL (or its base URL). Click Next.
-
Under How the gateway authenticates to the agent, pick the credential your agent expects, or No authentication. Click Next.
-
Review the card. Untick any skill you do not want callers to use. Click Next.
-
Check the Slug (it becomes part of the agent's URL). Turn on Skill-routed if you want to grant callers individual skills. Click Register agent.
The agent page opens. Its Endpoints box shows the gateway URLs callers use and a ready-made curl example.
2. Create a caller and copy its key
A caller is the app, agent or partner that will call your agent.
-
Open the Callers tab and click Create caller.
-
Enter a Name, pick a Type, keep Create a first key on, and click Create caller.
-
Copy the key and store it somewhere safe. It is shown only once.
3. Grant the caller access
- On the caller's page, under Access, choose the agent from Add an agent.
- Keep All current and future skills, or turn it off and tick only the skills this caller needs.
- Click Save access.
Until you save a grant, the agent does not exist for this caller.
4. Call the agent
Send a normal A2A request to the agent's gateway URL with the caller key. Copy the URL from the agent's Endpoints box.
curl -X POST 'https://<gateway-host>/a2a/<tenant-handle>/<agent-slug>' \
-H "Authorization: Bearer $QUILR_A2A_CALLER_KEY" \
-H 'Content-Type: application/json' \
-H 'A2A-Version: 1.0' \
-d '{
"jsonrpc": "2.0",
"id": "1",
"method": "SendMessage",
"params": {
"message": {
"messageId": "msg-1",
"role": "ROLE_USER",
"parts": [{"text": "Where is order 4411?"}]
}
}
}'
Any A2A client works the same way: point it at the agent card URL from the Endpoints box and send the key as a bearer token.
Each message names its skill in message.metadata.skill_id. If the caller can use exactly one skill on the agent, it can leave the skill out and the gateway fills it in.
5. Check the logs
Open the Logs tab. Each call shows the caller, agent, method, skill, task state, status and latency. Calls can take a minute or two to appear.
Click a row to see the decision, what data protection found, timing, the full request and response, and the delegation chain. See Monitor A2A traffic.
Next steps
- Agents: card changes, testing, wrapped agents and agent settings.
- Callers and keys: keys, end-user tokens, source IPs and limits.
- Gateway settings: data protection actions, defaults and signing keys.
- How it works: endpoints, versions, streaming, push, chains and error codes.