Products & Surfaces

Connecting external agents

Integrate external AI Agents with your Runtype A2A Surface to enable Agent-to-Agent communication and multi-Agent workflows.

Prerequisites

  • An active A2A Surface in Runtype
  • Your Agent Card URL (found in the Endpoints tab)
  • API key with the a2a_ prefix (if authentication is required)
  • Access to the external Agent platform you want to connect

Connection methods

How you connect depends on the external Agent platform:

A2A-compatible platforms

For platforms with native A2A support:

  1. In the external platform, add a new Agent connection
  2. Select “A2A” or “Agent-to-Agent” as the connection type
  3. Enter your Agent Card URL: 
    https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/a2a/.well-known/agent-card.json
  4. Add authentication (if required):
    • Type: Bearer token
    • Token: Your a2a_ prefixed API key
  5. Save and test the connection

The platform will discover your skills automatically from the Agent Card.

Custom integration

For platforms without native A2A support, implement the protocol manually:

1import requests
2
3# Discover skills via Agent Card
4agent_card_url = "https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/a2a/.well-known/agent-card.json"
5response = requests.get(agent_card_url)
6agent_card = response.json()
7
8print(f"Agent: {agent_card['name']}")
9print(f"Skills: {len(agent_card.get('skills', []))}")
10
11# Invoke via JSON-RPC
12a2a_url = "https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/a2a"
13headers = {"Authorization": "Bearer a2a_xxxxx"}
14payload = {
15    "jsonrpc": "2.0",
16    "method": "SendMessage",
17    "id": "1",
18    "params": {
19        "message": {
20            "role": "ROLE_USER",
21            "parts": [{"text": "What are your business hours?"}]
22        }
23    }
24}
25# Legacy v0.3 names (method "message/send", parts [{"type": "text", ...}]) are still accepted.
26
27result = requests.post(a2a_url, json=payload, headers=headers)
28print(result.json())

Providing authentication

If your A2A Surface requires authentication:

  1. Go to your A2A Surface and open the Keys tab
  2. Create an API key (keys use the a2a_ prefix)
  3. Share the key securely with the external Agent operator
  4. They include it as a Bearer token or X-API-Key header in all requests

Create separate API keys for each external Agent or organization. This makes it easier to track usage and revoke access when needed.

Testing the connection

Verify external Agents can access your Capabilities:

  1. From the external Agent, fetch the Agent Card
  2. Confirm your skills appear
  3. Invoke a simple skill
  4. Check execution logs in Runtype to see the invocation
  5. Verify the response is received correctly

Common integration patterns

Fallback agent

External Agent tries to handle a request, falls back to your Agent if it can’t:

1async function handleCustomerQuery(query) {
2  const localResponse = await tryLocalAgent(query);
3  
4  if (localResponse.confidence < 0.5) {
5    // Fall back to Runtype A2A agent
6    const response = await fetch(a2aUrl, {
7      method: 'POST',
8      headers: {
9        'Authorization': 'Bearer a2a_xxxxx',
10        'Content-Type': 'application/json'
11      },
12      body: JSON.stringify({
13        jsonrpc: '2.0',
14        method: 'SendMessage',
15        id: '1',
16        params: {
17          message: { role: 'ROLE_USER', parts: [{ text: query }] }
18        }
19      })
20    });
21    return response.json();
22  }
23  
24  return localResponse;
25}

Next steps