Agent Connections

Enable communication between agents using the A2A (Agent-to-Agent) Protocol.

Overview

Agent-to-agent (A2A) connections allow:

• Cross-agent messaging via JSON-RPC 2.0
• Agent discovery with .well-known/agent.json
• Workflow triggers across agents
• State sharing and event subscriptions
• OpenAI-compatible API access

A2A Protocol

The A2A Protocol enables standardized inter-agent communication:

Agent Discovery

Each agent exposes a discovery endpoint:

GET /{agentId}/.well-known/agent.json

Response (Agent Card):

{
  "name": "Support Agent",
  "description": "Handles customer support queries",
  "url": "https://your-domain.com/a2a",
  "capabilities": {
    "streaming": true,
    "tools": ["search_knowledge", "send_email"]
  },
  "skills": [
    {
      "name": "answer_questions",
      "description": "Answer product questions"
    }
  ]
}

JSON-RPC Messaging

Send messages to agents via JSON-RPC 2.0:

POST /a2a
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "message",
  "params": {
    "content": "What's the status of order #12345?",
    "context": {
      "user_id": "user-123"
    }
  },
  "id": "req-001"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "content": "Order #12345 shipped on Jan 25th...",
    "metadata": {
      "model": "llama-4-scout",
      "tokens_used": 150
    }
  },
  "id": "req-001"
}

Streaming Responses

For real-time streaming:

POST /a2a/stream
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "message",
  "params": {
    "content": "Explain quantum computing"
  },
  "id": "req-002"
}

Returns Server-Sent Events (SSE) with content deltas.

OpenAI-Compatible API

Agents also expose an OpenAI-compatible chat completions endpoint:

POST /v1/chat/completions
Content-Type: application/json

{
  "model": "agent",
  "messages": [
    {"role": "user", "content": "Hello!"}
  ],
  "stream": true
}

This allows using any OpenAI SDK to interact with your agents.

Connection Types

Webhook

POST events to another agent:

{
  "connection_type": "webhook",
  "config": {
    "url": "https://agent-b.example.com/webhook",
    "events": ["workflow.complete", "message.received"]
  }
}

Direct

Direct Durable Object communication:

{
  "connection_type": "direct",
  "config": {
    "target_agent_id": "agent-b"
  }
}

Creating Connections

Via API

curl -X POST .../agent-connections \
  -d '{
    "source_agent_id": "agent-a",
    "target_agent_id": "agent-b",
    "connection_type": "webhook",
    "config": {
      "events": ["workflow.complete"]
    }
  }'

Event Types

Event	Description
workflow.complete	Workflow finished
workflow.error	Workflow failed
message.received	New message arrived
schedule.executed	Schedule ran
browser.action	Browser action completed

Use Cases

Workflow Chaining

Agent A completes → triggers Agent B:

{
  "events": ["workflow.complete"],
  "filter": {
    "workflow_id": "step-1"
  }
}

Message Routing

Forward messages between agents:

{
  "events": ["message.received"],
  "filter": {
    "channel": "support"
  }
}

State Sync

Share state updates:

{
  "events": ["state.update"],
  "config": {
    "fields": ["contacts", "config"]
  }
}

Security

Authentication

Connections include auth tokens:

{
  "config": {
    "auth": {
      "type": "bearer",
      "token": "{{secrets.agent_b_token}}"
    }
  }
}

Access Control

Only admins can create connections.

Using from Chat

Agents can communicate with each other using the send_to_agent tool:

{
  "name": "send_to_agent",
  "arguments": {
    "agent_id": "support-agent",
    "message": "Customer needs help with billing"
  }
}

The receiving agent processes the message and returns a response.

A2A Message Logging

All inter-agent messages are logged in the a2a_messages table:

Field	Description
direction	outgoing or incoming
connection_id	Agent connection reference
content	Message content
status	sent, delivered, failed
created_at	Timestamp

API Reference

See Agent Connections API for complete endpoint documentation.