Products & Surfaces

Setting up an A2A Surface

Use an A2A (Agent-to-Agent) Surface to expose your Runtype Product to external agents through the A2A protocol. External agents discover your Product through an Agent Card and invoke its exposed Capabilities through a JSON-RPC endpoint.

Use an A2A Surface when you want multiple AI systems to discover and call your Capabilities without a separate integration for each system. For a Surface overview, see What are Surfaces?.

Before you begin

Complete these prerequisites before you create an A2A Surface:

If you use an Agent as a Capability, create and configure it before you start. Read What are Agents? for an overview. For setup instructions, see Creating and configuring Agents.

Choose an A2A Surface

Use an A2A Surface for the following integration patterns:

  • Cross-platform collaboration: Let an external sales agent query an inventory Capability for availability.
  • Specialized routing: Let a customer support agent route complex questions to domain-specific Capabilities.
  • Multi-agent orchestration: Let platforms such as LangChain, CrewAI, or Vercel AI SDK discover and call your Capabilities in larger workflows.

Create an A2A Surface

To create and connect an A2A Surface, follow these steps:

  1. On the Products page, open your Product.
  2. In Product surfaces, click Add Surface.
  3. Select A2A Agent. The Product editor opens a draft Surface.
  4. In Overview, enter a name for the Surface, such as Public Agent API.
  5. In Visual view, drag a connection from a Capability node to the Surface node.
  6. In the page header, click Save. The Product editor saves the Surface and its connection.

Only connected and enabled Capabilities appear as skills in the Agent Card. The Product editor does not connect existing Capabilities to a new Surface automatically.

Configure the Surface

Open the Surface editor and use these tabs:

  • Overview: Edit the Surface name, status, and basic settings.
  • Agent Card: Configure the Agent Card name, description, icon URL, provider information, streaming, and push notifications.
  • Endpoints: Copy the A2A endpoint and Agent Card URL.
  • Orchestration: Choose which skills appear and whether a managed skill routes requests to Capabilities.
  • Keys: Generate and manage API keys for the Surface.

Configure the Agent Card

Your A2A Surface publishes an A2A Protocol v1.0 Agent Card. The Agent Card is a JSON document that describes your Product identity, skills, supported interface, security schemes, and invocation URL. External agents fetch the card before they send an authenticated request.

Use the following public URL to retrieve the Agent Card:

https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/a2a/.well-known/agent-card.json

Replace the placeholders in the URL as follows:

  • YOUR_PRODUCT_ID: The ID of your Product.
  • YOUR_SURFACE_ID: The ID of your A2A Surface.

The Agent Card includes the following fields:

  • Agent metadata: Your Product name, description, and Agent Card version.
  • Skills: Each connected and enabled Capability or exposed external-agent skill, with its name, description, and input and output modes.
  • Supported interfaces: The A2A endpoint URL and JSON-RPC protocol binding.
  • Security schemes: The authentication scheme that the external agent uses.

Write clear descriptions for your Capabilities. External agents select skills based on these descriptions.

Configure orchestration

The Orchestration tab controls how the A2A Surface routes incoming requests to Capabilities. Use one of these modes:

  • Delegate mode: Expose each connected Capability as a separate skill. The calling agent selects the skill.
  • Managed mode: Add a managed skill that routes incoming requests to the appropriate Capability.

In Managed mode, enable or disable individual skills in the Skills section. You can expose a Capability as an individual skill. You can also make a Capability available only to the managed skill, or expose both.

Use Delegate mode when the calling agent selects among distinct Capabilities. Use Managed mode when you want one entry point to route requests for you.

Generate an API key

The Agent Card discovery endpoint is public. External agents must authenticate JSON-RPC requests with an A2A API key. Dashboard testing can use a Clerk session instead.

To generate and share an A2A API key, follow these steps:

  1. On the Surface editor, click Keys.
  2. Click Generate Key.
  3. In Name (optional), enter a name such as Partner Agent.
  4. For a live integration, select Production: hash-only, uncapped in Key Type.
  5. Click Generate Key.
  6. Copy or download the key from the success dialog. The dialog does not show the key again after you close it.

Use either of these headers for an authenticated request:

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

Replace a2a_YOUR_API_KEY with the generated key. A2A API keys use the a2a_ prefix.

Create a separate key for each external agent or partner. Separate keys help you track usage and revoke one integration without affecting the others.

Request limits and required identity

These are best-effort request throttles, not strict concurrent quotas. KV counter updates are not atomic, so concurrent requests can exceed configured counts.

Configured per-minute and per-day key limits apply to every authenticated JSON-RPC request. This includes task reads, list requests, cancellation, and subscriptions. A subscription counts when it starts, not for each streamed event. Requests use the same counters regardless of the method alias. A null limit leaves that window unlimited; dashboard Clerk-session testing has no surface-key limit. Public Agent Card discovery does not use these counters.

An over-limit request returns a JSON-RPC error with code -32004 and reason RATE_LIMITED. Streaming sends and subscriptions receive that error in an SSE stream; other methods receive a JSON response. Both use HTTP 200. The Retry-After response header gives the wait in seconds. Back off before retrying and reduce polling frequency. Existing integrations that exceed their configured limits now receive this error instead of continuing unchecked. Counters reset at the next UTC minute or UTC day boundary for the window that rejected the request. Key request limits are separate from execution quotas.

Cancellation also consumes this budget. An over-limit cancellation does not stop the running task. Retry after the indicated wait, or cancel with another authorized credential that has request capacity.

Saved Agents retain their Tenancy Strategy on A2A calls, including quick, external, and Claude Managed Agents. The A2A endpoint does not establish a Product Tenant or verified End User identity. A Surface key or dashboard session cannot stand in for that identity, and identity-shaped request metadata does not grant it. Agents requiring one of these scopes reject A2A requests before execution quota or task creation. Managed orchestration also rejects requests if an offered saved Agent requires an identity that this endpoint cannot establish.

Use an identity-supporting execution path described in End-user identity for isolated Agents. If the Agent genuinely does not require isolation, the Product owner can correct its saved policy. Do not remove isolation merely to suppress an error.

Verify the Surface

To verify the setup, follow these steps:

  1. Open the Endpoints tab and copy the Agent Card URL.
  2. Open the URL without an authentication header. The response includes a supportedInterfaces entry with protocolVersion set to 1.0 and a skills array.
  3. Send an authenticated SendMessage request through an A2A-compatible client. Confirm that the client receives a task response.

Next steps

Continue with one of these guides: