> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent-to-Agent (A2A) Connections

> Learn how to connect GenerativeAgent to your own sub-agents using the A2A protocol

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.

<Note>
  Contact your ASAPP account team to enable this feature for your implementation.
</Note>

## 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](https://a2a-protocol.org/)) 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](#keep-the-agent-card-current).

**During a conversation**, a [Function](#deploy-and-reference-the-connection-in-a-function) that references the connection makes your agent available to GenerativeAgent:

<Steps>
  <Step title="GenerativeAgent decides your agent is relevant">
    While working through a Task, GenerativeAgent matches the conversation against the connection's description and selects the Function.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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](#support-multi-turn-conversations).
  </Step>
</Steps>

Every call is recorded in the [API Connection Logs](#monitor-calls-and-handle-errors), 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:

| Field | Type | Description |
| - | - | - |
| `message` | string (required) | The natural-language request to your agent. |
| `data` | object (optional) | Structured data GenerativeAgent has gathered, when relevant. |
| `task_id` | string (optional) | Omitted on the first call. Used to resume an interaction. See [Support multi-turn conversations](#support-multi-turn-conversations). |

**Response**, what your agent returns:

| Field | Type | Description |
| - | - | - |
| `text` | string | A natural-language result to relay to the customer. |
| `data` | object | Structured result data, when applicable. |
| `input_required` | boolean (required) | `true` if your agent needs more information to continue. |
| `input_required_message` | string | The question to ask the customer, when `input_required` is `true`. |
| `task_id` | string | An identifier to pass back on the next call to resume the interaction. |

<Note>
  Because the contract is fixed, the [request and response transformations](/generativeagent/configuring/connect-apis#request-interface) 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.
</Note>

### 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

<Accordion title="Example: booking a flight">
  ```text theme={null}
  Customer        -> GenerativeAgent: "Book me a flight to Boston"
  GenerativeAgent -> Your Agent:      { message: "Book a flight to Boston" }
  Your Agent      -> GenerativeAgent: { input_required: true, input_required_message: "What date?", task_id: "t1" }
  GenerativeAgent -> Customer:        "What date would you like to fly?"
  Customer        -> GenerativeAgent: "March 15"
  GenerativeAgent -> Your Agent:      { message: "March 15", task_id: "t1" }
  Your Agent      -> GenerativeAgent: { text: "Booked, confirmation ABC123", input_required: false }
  GenerativeAgent -> Customer:        "You're booked. Your confirmation is ABC123."
  ```
</Accordion>

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.

<Note>
  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.
</Note>

## Connect your sub-agent

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

<Steps>
  <Step title="Create an A2A Connection">
    1. Navigate to **API Integration Hub** > **API Connections**
    2. Click **Create Connection**
    3. Select **A2A** from the connection type list
  </Step>

  <Step title="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](#configure-sandbox-and-production-environments).

    <Note>
      If you provide the full well-known path, ASAPP uses it as-is.
    </Note>
  </Step>

  <Step title="Select an authentication method">
    Select or create an [authentication method](#authenticate-to-your-agent) 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](#connect-to-amazon-bedrock-agentcore-agents).
  </Step>

  <Step title="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

    <Warning>
      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.
    </Warning>
  </Step>
</Steps>

Next, [review the generated description](#review-and-tune-the-connection-description), then [test the connection](#test-your-agent-before-going-live) 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](/generativeagent/configuring/connect-apis/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.

<Note>
  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.
</Note>

## 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](/generativeagent/configuring/deploying-to-generativeagent.mdx).

Once deployed, an A2A Connection can be referenced by a [Function](/generativeagent/configuring#step-4-create-functions), 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](/generativeagent/configuring/connect-apis#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](/generativeagent/configuring/connect-apis#configure-api-connection-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

<CardGroup>
  <Card title="Create Functions" href="/generativeagent/configuring#step-4-create-functions">
    Learn how to create functions that use your A2A connection to enable GenerativeAgent to call your sub-agent.
  </Card>

  <Card title="API Connections Overview" href="/generativeagent/configuring/connect-apis">
    Explore other API connection types and learn how connections, functions, and tasks fit together.
  </Card>
</CardGroup>