Setting up an A2A surface

A2A (Agent-to-Agent) surfaces enable AI Agents to discover and communicate with your Runtype capabilities, facilitating multi-Agent systems and cross-platform collaboration.

What is A2A?

A2A is a protocol for AI Agents to find and invoke each other's capabilities. When you create an A2A surface, your Product becomes discoverable by external Agents, which can then call your capabilities as part of their workflows.

This enables scenarios like:

• An external sales Agent querying your inventory Agent

• A customer support Agent routing to your specialist Agents

• Multi-Agent orchestration across different platforms

Before you begin

You'll need a Product with capabilities you want to expose to external Agents. Consider which capabilities are safe for external access.

Create an A2A surface

1. Open your Product

2. Find the Surfaces section

3. Click Add Surface

4. Select A2A (Agent-to-Agent)

5. Configure the surface:

   • Name: Descriptive name (e.g., "Public Agent API")

   • Environment: Development or Production

   • Status: Active

   • Orchestration: Orchestrated (recommended for A2A)

6. Click Create

A2A surface tabs

Your A2A surface has five tabs:

• Overview — Surface status and basic settings

• Endpoints — Agent Card URL and A2A endpoint URL

• Orchestration — Routing mode and skill visibility

• Keys — API key management and authentication settings

• Ship — Deployment and sharing options

The Endpoints tab shows the well-known Agent Card URL and the A2A protocol endpoint. The Keys tab is where you configure authentication and generate API keys for authorized Agents.

Orchestration (advanced)

The Orchestration tab controls routing and skill visibility:

• Delegate mode — Each capability is exposed as a separate skill in the Agent Card

• Orchestrated mode — Runtype routes invocations to the appropriate capability behind a single skill

In Orchestrated mode, you can optionally add a Runtype-managed orchestrator skill that routes requests to your capabilities. You can also control which capabilities appear as individual skills vs. which are only accessible through orchestration.

Agent discovery

Your A2A surface publishes an Agent Card at the well-known URI:

https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/a2a/.well-known/agent.json

External Agents fetch this Agent Card to discover your skills, their input schemas, and the A2A endpoint for invocation. Both Product ID and Surface ID are required because each Product can have multiple A2A surfaces.

What gets exposed

The Agent Card includes:

• Agent metadata — Product name, description, version

• Skills — Each capability with name, description, and input schema

• A2A endpoint URL — Where to send invocation requests using the A2A protocol

Authentication for A2A

A2A surfaces support two authentication modes:

• Key-based — Calling Agents must include an API key (recommended)

• Open — Anyone can discover and invoke (use with caution)

Configure this in the Keys tab of your A2A surface. For key-based access, generate keys in the same tab and share them with authorized Agents.

Next steps

• How A2A works to understand the protocol details

• Connecting external agents to integrate with other systems

• Surface orchestration modes for routing configuration