Skip to main content
Agent-to-Agent (A2A) Connections let you connect GenerativeAgent to your own sub-agents without writing any code. GenerativeAgent stays in control of the end-user conversation, calls your agent when its capabilities are relevant, and weaves the result back into the conversation. A2A is a native connection type in API Connections, alongside API Spec, MCP Server, Adapters, and Code. There is no source specification to upload.
Contact your ASAPP account team to enable this feature for your implementation.

​
What you get with A2A Connections

  • No-code setup: Connect a sub-agent with a URL and an authentication method.
  • Automatic capability discovery: ASAPP fetches your agent’s Agent Card and turns its skills into the connection’s description.
  • Sandbox and production environments: Separate URLs and credentials for testing and for live traffic.
  • A standard, fixed contract: Every A2A connection uses the same, predictable request and response shape.
  • Multi-turn conversations: GenerativeAgent can carry a conversation across multiple calls to your agent.
  • AWS-hosted agent support: Connect agents running on AWS, including Amazon Bedrock AgentCore.
  • Built-in testing: Test-call your agent from the connection screen before going live.
  • Full observability: Every call appears in the API Connection Logs with status, latency, and payloads.
Each of these is covered in detail below.

​
Understanding A2A

A2A (Agent-to-Agent) is an open protocol that lets agents discover and call one another. It has three concepts you need to know:
  • Agent Card: A published description of what an agent can do. It lists the agent’s name, an overall description, and a set of skills. The Agent Card is typically served at https://<your-agent-host>/.well-known/agent-card.json.
  • Skills: Capabilities the agent advertises, such as “book a flight” or “check order status”. Skills are descriptions, not fixed API endpoints. Each skill has a name, a description, and usually a few examples.
  • Single messaging endpoint: Clients send a natural-language message to one endpoint. The remote agent interprets the message, picks the right skill, does the work, and returns a result.
Because your agent interprets intent itself, you do not wire up individual endpoints or map every field. You describe the agent, and GenerativeAgent’s model constructs the request from the conversation.

​
How A2A Connections work

An A2A Connection does its discovery work when you configure it, and its calling work during a conversation. When you create the connection, ASAPP reads your agent’s Agent Card once, renders a description from the agent’s skills, and saves that description as a version. The version you deploy is the contract GenerativeAgent uses at runtime, so your agent’s capabilities never change mid-conversation. See Keep the Agent Card current. During a conversation, a Function that references the connection makes your agent available to GenerativeAgent:
1

GenerativeAgent decides your agent is relevant

While working through a Task, GenerativeAgent matches the conversation against the connection’s description and selects the Function.
2

GenerativeAgent composes the request

GenerativeAgent writes a natural-language message describing what it needs, and includes any structured data it has already gathered from the customer.
3

ASAPP calls your agent

ASAPP sends the request to your agent’s messaging endpoint, applies the credential configured for the environment, and passes a conversation context identifier so your agent can tie the call to the rest of the conversation.
4

Your agent picks a skill and responds

Your agent interprets the message, chooses the skill that applies, does the work, and returns a result. If it needs more information first, it returns input_required: true with a question and a task_id.
5

GenerativeAgent continues the conversation

GenerativeAgent relays the result to the customer in its own voice. If your agent asked for more information, GenerativeAgent asks the customer and calls your agent again with the answer and the task_id, until the task finishes. See Support multi-turn conversations.
Every call is recorded in the API Connection Logs, including the request sent and the response received.

​
Before you begin

Before you create the connection, your agent needs to publish an Agent Card and speak the A2A request and response contract. Every A2A Connection uses the same fixed request and response shape. You do not design or map this contract. It is the same across all A2A connections, which keeps behavior predictable and lets GenerativeAgent handle multi-turn flows consistently. Request, what GenerativeAgent sends your agent: Response, what your agent returns:
Because the contract is fixed, the request and response transformations available on other connection types do not apply. The request and response schemas are visible as read-only on the connection screen for reference and testing.

​
Support multi-turn conversations

Real tasks often need a back-and-forth. A2A Connections support this in two complementary ways, and both mechanisms work together. Conversation continuity. For every call within a single GenerativeAgent conversation, ASAPP passes a stable conversation context identifier to your agent. Agents that use this identifier retain memory across calls within the same conversation, so follow-up messages land in the same thread on your side. Input-required round-trips. When your agent needs a specific piece of information before it can finish, it returns input_required: true, a question in input_required_message, and a task_id. GenerativeAgent then:
  1. Asks the customer the question
  2. Calls your agent again with the customer’s answer and the returned task_id
  3. Continues until your agent returns a completed result
Agents that maintain their own conversation memory can also ask follow-up questions conversationally in the text field, and GenerativeAgent keeps the exchange on the same thread.
Multi-turn requires that your agent either honors the conversation context identifier or implements the input_required pattern. Stateless agents that do neither treat each call independently.

​
Connect your sub-agent

Creating an A2A Connection takes two inputs: your agent’s URL and an authentication method.
1

Create an A2A Connection

  1. Navigate to API Integration Hub > API Connections
  2. Click Create Connection
  3. Select A2A from the connection type list
2

Enter the Agent URL

Enter your agent’s endpoint. ASAPP fetches the Agent Card from /.well-known/agent-card.json relative to this URL.Configure a separate URL for each environment. See Configure sandbox and production environments.
If you provide the full well-known path, ASAPP uses it as-is.
3

Select an authentication method

Select or create an authentication method that ASAPP uses to reach your agent.Agents hosted on Amazon Bedrock AgentCore do not need a credential here. See Connect to Amazon Bedrock AgentCore agents.
4

Save the connection

On save, ASAPP:
  1. Fetches your agent’s Agent Card
  2. Renders a description from it, using the agent’s overall description followed by each skill’s name, description, and examples
  3. Creates the connection
If the Agent Card cannot be fetched because of a network error, a malformed response, or an authentication challenge, the setup screen reports what happened so you can correct the URL or the credential.
Next, review the generated description, then test the connection before you deploy it.

​
Configure sandbox and production environments

Every A2A Connection supports two independently configured environments:
  • Sandbox: Used for testing GenerativeAgent against your agent.
  • Production: Used for live customer conversations.
Each environment has its own Agent URL and its own authentication method. You can point sandbox traffic at a staging deployment of your agent with test credentials while production traffic goes to your live deployment, with no risk of crossing the two.

​
Authenticate to your agent

Configure each environment with its own authentication method. A2A Connections support these credential types:
  • Custom header, for API keys or bearer tokens supplied as a header
  • Basic authentication
  • OAuth
  • Code-based authentication for advanced scenarios
ASAPP stores credentials securely and applies them server-side when it calls your agent. Credentials are never exposed to the end user or the browser. See Authentication Methods for how to configure each type.

​
Handle per-skill security requirements

Some Agent Cards declare different security requirements for different skills. When you configure a connection, choose a credential that covers the skills you want GenerativeAgent to use. If your agent requires genuinely different credentials for different skills, model those as separate connections, each with its own credential. If your agent rejects a call because the supplied credential does not authorize a given skill, the error surfaces as a standard API Connection error in the logs.

​
Connect to Amazon Bedrock AgentCore agents

A2A Connections support agents hosted on Amazon Bedrock AgentCore, AWS’s managed runtime for A2A-compatible agents. For AgentCore agents, authentication is automatic and credential-free. When ASAPP detects that the target agent is an Amazon Bedrock AgentCore agent, it authenticates using ASAPP’s own AWS identity. ASAPP obtains a short-lived token through its IAM role and passes it in the header AgentCore expects. You never configure, share, or manage any AWS keys. This relies on a one-time trust setup between your AWS account and ASAPP:
  • On your side: Allow-list ASAPP’s AWS IAM role so it can invoke your AgentCore agent.
  • On ASAPP’s side: ASAPP grants that IAM role the permissions needed to invoke your AgentCore agent.
Your ASAPP team coordinates both steps with you during onboarding.
Once the trust is in place, an AgentCore-hosted agent behaves like any other A2A agent: same setup flow, same request and response contract, same multi-turn behavior. The only difference is that ASAPP handles authentication through its IAM role instead of a credential you configure on the connection.

​
Review and tune the connection description

GenerativeAgent’s model reads the connection description to decide when to call your agent and what to send it. ASAPP generates this description from your Agent Card, and you can edit it to tune how and when GenerativeAgent uses the agent.
  • The generated description is the default.
  • You can edit the text to sharpen wording, add guidance, or narrow scope.
  • Edits are saved as a new version and take effect when deployed.

​
Test your agent before going live

You can test-call an A2A Connection from the connection screen before deploying:
  1. Enter a test message, and optionally data and task_id
  2. Run the test against your sandbox environment, or against production
  3. Review the response returned by your agent
Test calls round-trip through your actual agent using the configured credentials, so you can verify authentication, latency, and behavior end to end. Test invocations also appear in the logs alongside production runs.

​
Deploy and reference the connection in a Function

A2A Connections follows our standard deployment model. Once deployed, an A2A Connection can be referenced by a Function, the unit GenerativeAgent invokes during a Task.
  • The Function inherits the A2A contract.
  • The Function’s name and description default to the connection’s name and description, and you can adjust them.
  • GenerativeAgent uses the connection description to decide when the Function is relevant and how to populate the request.
Functions bind to deployed versions of a connection. Drafts are never used at runtime, so live conversations only call the version you explicitly deployed.

​
Monitor calls and handle errors

Every A2A call, production and test, lands in the standard API Connection Logs view, with:
  • Timestamp, connection, status, and latency
  • The request sent and the response received
  • An error code and message when something goes wrong
These conditions surface as standard API Connection errors:
  • Your agent returns a failure state.
  • The call times out. Each connection has a configurable timeout, and the default is 30 seconds.
  • Your agent is unreachable or rejects the request because of insufficient authorization.

​
Keep the Agent Card current

Your agent’s capabilities may change over time. When you publish an updated Agent Card, use the Update Agent Card action on the connection. ASAPP re-fetches the card from your production Agent URL, re-renders the description, and saves it as a new version. A raw A2A client re-reads the Agent Card on every interaction. ASAPP instead captures your agent’s capabilities when the connection is created, and refreshes them when you choose to. You then deploy the new version. This gives you a stable, reviewable, versioned contract for each agent. What GenerativeAgent sees is what you deployed, and capability changes never take effect mid-flight without your action. To pick up a change: Update Agent Card, review, then deploy.

​
Next Steps

Create Functions

Learn how to create functions that use your A2A connection to enable GenerativeAgent to call your sub-agent.

API Connections Overview

Explore other API connection types and learn how connections, functions, and tasks fit together.