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
Open your Product in the dashboard.
Find the Surfaces section.
Click Add Surface.
Select A2A (Agent-to-Agent).
Enter a descriptive name, such as Public Agent API.
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
Tab | What it’s for |
|---|---|
Overview | Surface name, status, and basic settings |
Agent Card | Preview the auto-generated Agent Card that external Agents use to discover your skills |
Endpoints | View the Agent Card URL and A2A protocol endpoint URL to share with external consumers |
Orchestration | Configure how incoming requests are routed to your Capabilities |
Keys | Create and manage API keys for authenticating external Agents |
Agent Card
Your A2A Surface automatically generates an Agent Card. This JSON document describes your Product’s identity, skills, 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.jsonUse 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 schema
Endpoint URL — Where Agents send invocation requests using the A2A protocol
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.
Go to the Keys tab.
Click Create Key.
Enter a name, such as Partner Agent — Acme Corp.
Share the generated key with the authorized Agent team.
Calling Agents can authenticate with either header:
Authorization: Bearer <key>X-API-Key: <key>
If no keys are configured, your A2A Surface is open to any Agent that discovers it. 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.