Products & Surfaces

Setting Up an A2A Surface

A2A (Agent-to-Agent) Surfaces let external AI Agents discover and interact with your Runtype Product without custom integration work. Once set up, other Agents can find and invoke your Capabilities as part of their own workflows using the open A2A protocol.

A2A Surfaces are useful when you want your Product to participate in multi-Agent ecosystems. Instead of building one-off integrations, you publish a standard Agent Card that any A2A-compatible Agent can discover and use. If you are new to Surfaces, start with What are Surfaces?.

Why use an A2A Surface?

  • Cross-platform collaboration — An external sales Agent queries your inventory Agent for real-time availability
  • Specialized routing — A customer support Agent routes complex questions to your domain-specific Agents
  • Multi-Agent orchestration — Platforms like LangChain, CrewAI, or Vercel AI SDK discover and call your Capabilities as part of larger workflows

You need a Product with at least one Capability that you want to make available to external Agents. To get started, first create a Product. If you plan to expose an Agent, see What are Agents? and Creating and configuring Agents.

Start with a single, well-defined Capability to keep setup simple. You can add more later.

Create an A2A Surface

  1. Open your Product in the dashboard.
  2. Find the Surfaces section.
  3. Click Add Surface.
  4. Select A2A (Agent-to-Agent).
  5. Enter a descriptive name, such as Public Agent API.
  6. Click Create.

Your A2A Surface is now ready to configure. The Capabilities added to this Surface automatically appear as skills in your Agent Card.

A2A Surface tabs

TabWhat it’s for
OverviewSurface name, status, and basic settings
Agent CardPreview the auto-generated Agent Card that external Agents use to discover your skills
EndpointsView the Agent Card URL and A2A protocol endpoint URL to share with external consumers
OrchestrationConfigure how incoming requests are routed to your Capabilities
KeysCreate and manage API keys for authenticating external Agents

Agent Card

Your A2A Surface automatically generates an A2A Protocol v1.0 Agent Card. This JSON document describes your Product’s identity, skills, supported interfaces, security schemes, and how to invoke them. External Agents fetch this card to understand what your Product can do.

The Agent Card is published at:

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

Use the Agent Card tab to preview what external Agents will discover, including:

  • Agent metadata — Your Product’s name, description, and version
  • Skills — Each Capability with its name, description, and input/output modes
  • Endpoint URL — Where Agents send v1.0 JSON-RPC invocation requests using methods such as SendMessage and SendStreamingMessage

Write clear descriptions for your Capabilities. External Agents use these skill descriptions to decide when to call your Product.

Orchestration

The Orchestration tab controls how incoming A2A requests are routed to your Capabilities.

  • Delegate mode — Each Capability is exposed as a separate skill in the Agent Card. The calling Agent chooses which skill to invoke.
  • Managed mode — Runtype adds an orchestration layer that routes incoming requests to the right Capability behind the scenes. This works well when you have multiple Capabilities and want Runtype to handle the routing logic.

In Managed mode, you can choose which Capabilities appear as individual skills and which are available only through the orchestrator. This gives you more control over how your Product appears to external Agents.

Use Delegate mode when your Capabilities are clearly distinct. Use Managed mode when you want a single entry point that routes requests for you.

Authentication

A2A Surfaces support API key authentication so you can control which Agents can discover and invoke your Capabilities.

  1. Go to the Keys tab.
  2. Click Create Key.
  3. Enter a name, such as Partner Agent — Acme Corp.
  4. Share the generated key with the authorized Agent team.

Calling Agents can authenticate with either header:

  • Authorization: Bearer a2a_xxx
  • X-API-Key: a2a_xxx

A2A Surface keys use the a2a_ prefix.

The Agent Card discovery endpoint is always public so external Agents can find your Surface, but the JSON-RPC invocation endpoint always requires a valid A2A key. You must create at least one key before any external Agent can invoke your Capabilities. For production use, create separate keys for each authorized Agent so you can track usage and revoke access when needed.

Create a separate key for each external Agent or partner. This makes rotation and revocation easier.

Next steps