Agent-to-Agent Protocol (A2A)

Connect to external AI agents using standardized communication protocols. M3 Forge implements the Agent-to-Agent (A2A) protocol for interoperability with third-party agent platforms and distributed agent networks.

Overview

A2A enables agents running in different environments to communicate:

• M3 Forge agent ↔ External A2A-compatible agent
• M3 Forge agent ↔ Another M3 Forge instance
• M3 Forge agent ↔ Third-party agent platforms (AutoGPT, LangGraph, etc.)

This creates hybrid agent ecosystems where specialized agents collaborate regardless of hosting platform.

Why Use A2A?

Leverage External Expertise

Access agents you don’t host:

• Specialized industry agents (legal, medical, financial)
• Partner organization agents (joint projects)
• Commercial agent services (translation, analysis, research)

Distribute Workload

Offload computationally expensive tasks to external agents with better resources.

Interoperability

Avoid vendor lock-in. Switch between agent platforms without rewriting integration logic.

Resilience

If your primary agent fails, delegate to external backup agents.

A2A Protocol Basics

Agent Card

External agents expose a JSON “agent card” describing capabilities:

{
  "id": "research-agent-v2",
  "name": "Research Agent",
  "version": "2.1.0",
  "description": "Comprehensive web research with citations",
  "provider": "ExampleAI",
  "capabilities": {
    "streaming": true,
    "tools": ["web_search", "pdf_extract", "summarize"],
    "maxTokens": 8192
  },
  "endpoints": {
    "invoke": "https://agent.example.com/v1/invoke",
    "stream": "wss://agent.example.com/v1/stream",
    "status": "https://agent.example.com/v1/status"
  },
  "authentication": "bearer",
  "documentationUrl": "https://docs.example.com/research-agent"
}

Key fields:

• capabilities — What the agent can do (tools, streaming, etc.)
• endpoints — URLs for invocation, streaming, health checks
• authentication — Required auth method (bearer token, API key, OAuth)

Discovery

M3 Forge auto-discovers agent capabilities:

1. Enter agent URL
2. M3 Forge fetches agent card from /.well-known/agent-card.json
3. Capabilities parsed and displayed
4. Agent ready for registration

Message Format

A2A messages use a standard schema:

Request:

{
  "id": "req-123",
  "agent": "research-agent-v2",
  "task": {
    "type": "research",
    "input": "quantum computing applications",
    "parameters": {
      "depth": "comprehensive",
      "citations": true
    }
  },
  "context": {
    "userId": "user-456",
    "sessionId": "session-789"
  }
}

Response:

{
  "id": "resp-123",
  "requestId": "req-123",
  "status": "completed",
  "result": {
    "summary": "Quantum computing has applications in...",
    "citations": [
      "https://example.com/quantum-paper-1",
      "https://example.com/quantum-paper-2"
    ]
  },
  "metadata": {
    "duration": 4523,
    "tokensUsed": 1234,
    "cost": 0.045
  }
}

Streaming Responses

For long-running tasks, agents stream progress via Server-Sent Events (SSE):

event: start
data: {"taskId": "task-123"}

event: progress
data: {"status": "searching", "progress": 0.3}

event: chunk
data: {"content": "Found 12 relevant papers..."}

event: complete
data: {"result": "...", "metadata": {...}}

M3 Forge displays streaming responses in real-time.

Connecting External Agents

A2A Agent Manager

The Agent Manager provides a UI for discovery, registration, and testing:

https://agent.example.com

Agent Status Monitoring

The A2A Manager displays connection status for all registered agents:

Status indicators:

• Online — Agent responding to health checks
• Offline — Agent not reachable (network or service down)
• Error — Agent returned error response
• Unknown — No recent health check data

Health Checks

M3 Forge automatically pings registered agents:

• Frequency — Every 5 minutes
• Timeout — 10 seconds
• Retry — 3 attempts before marking offline

Click “Health Check All” to manually check all agents immediately.

Using External Agents

Direct Invocation

Call an external agent directly from M3 Forge:

1. Select agent from A2A dashboard
2. Click “Invoke”
3. Fill in task parameters
4. Submit request
5. View response (real-time if streaming)

Use case: Ad-hoc queries to specialized agents without building workflows.

In Orchestrations

Include external agents in multi-agent orchestrations:

orchestration:
  type: sequential
  agents:
    - id: local_research_agent
    - id: external_translator  # A2A agent
      url: https://translate.example.com
    - id: local_formatter_agent

M3 Forge handles communication transparently — local agents and external agents coordinate seamlessly.

In Workflows

Add A2A nodes to workflows:

1. Drag “A2A Agent” node into workflow canvas
2. Select external agent from dropdown
3. Map workflow inputs to agent task parameters
4. Connect to downstream nodes

External agent executes as part of the workflow, with results passed to subsequent nodes.

A2A Task Monitor

Track long-running tasks from external agents:

Real-Time Progress

The Task Monitor displays:

• Task ID — Unique identifier for tracking
• Status — Starting, in_progress, completed, failed
• Progress — Percentage complete (if agent reports it)
• Elapsed time — Duration since task started

Streaming Chunks

For streaming agents, view chunks as they arrive:

[10:23:45] Starting research...
[10:23:47] Found 12 relevant papers
[10:23:52] Extracting content from sources
[10:24:05] Generating summary
[10:24:12] Complete

Task Cancellation

Cancel long-running tasks:

1. Click “Cancel” on active task
2. M3 Forge sends cancellation request to external agent
3. Agent stops processing and returns partial results

Security Considerations

Authentication

External agents require authentication to prevent unauthorized access:

Bearer Token:

Authorization: Bearer <token>

API Key:

X-API-Key: <key>

OAuth 2.0:

Authorization: Bearer <access_token>

Store credentials securely. M3 Forge encrypts API keys and tokens at rest.

Network Security

Use HTTPS only:

• Never connect to external agents over HTTP
• M3 Forge validates SSL certificates
• Self-signed certificates require explicit trust

Firewall rules:

• Whitelist specific agent URLs
• Block unauthorized outbound connections
• Log all A2A traffic for audit

Data Privacy

Consider before sending data to external agents:

• Does the agent log requests?
• Is data transmitted encrypted?
• Does the agent store data permanently?
• Is the agent GDPR/CCPA compliant?

Review external agent privacy policies before connecting.

Rate Limiting

Prevent abuse from external agents:

• Request rate limits — Max requests per minute from external agents
• Token limits — Max tokens consumed per request
• Cost caps — Budget limits for paid external agents

Configure limits in A2A settings to avoid unexpected costs.

Advanced A2A Features

Multi-Tenancy

Register external agents per workspace or user:

• Global agents — Available to all users
• Workspace agents — Scoped to specific workspaces
• User agents — Private to individual users

Prevents credential sharing and enables per-user billing.

Agent Proxy

Route requests through M3 Forge proxy for:

• CORS handling — Avoid cross-origin issues in browser
• Credential injection — Centralized credential management
• Request transformation — Convert between protocol versions
• Caching — Cache agent responses to reduce costs

Enable proxy mode in A2A settings.

Failover and Redundancy

Configure fallback agents:

a2a:
  primary: https://agent1.example.com
  fallback:
    - https://agent2.example.com
    - https://agent3.example.com

If primary agent fails, M3 Forge automatically tries fallbacks.

Custom Protocols

Extend A2A to support custom agent protocols:

1. Implement protocol adapter in TypeScript/Python
2. Register adapter with M3 Forge
3. Connect agents using custom protocol

Example: Adapter for legacy agents using proprietary message formats.

A2A Agent Card Specification

Host your own A2A-compatible agent by serving an agent card:

Location: https://your-agent.com/.well-known/agent-card.json

Schema:

{
  "id": "your-agent-id",
  "name": "Your Agent Name",
  "version": "1.0.0",
  "description": "What your agent does",
  "provider": "Your Organization",
  "capabilities": {
    "streaming": true,
    "tools": ["tool1", "tool2"],
    "maxTokens": 4096,
    "cancellable": true
  },
  "endpoints": {
    "invoke": "https://your-agent.com/v1/invoke",
    "stream": "wss://your-agent.com/v1/stream",
    "status": "https://your-agent.com/v1/status"
  },
  "authentication": "bearer",
  "documentationUrl": "https://docs.your-agent.com"
}

Implement the required endpoints:

• POST /v1/invoke — Synchronous task execution
• WS /v1/stream — Streaming task execution
• GET /v1/status — Health check endpoint

See A2A Protocol Reference  for full specification.

Troubleshooting

Agent Discovery Fails

Symptoms: “Agent card not found” error

Causes:

• Agent card not served at /.well-known/agent-card.json
• CORS headers missing
• Invalid JSON format

Solutions:

• Verify agent card URL is accessible
• Add CORS headers: Access-Control-Allow-Origin: *
• Validate JSON with linter

Authentication Errors

Symptoms: “401 Unauthorized” when invoking agent

Causes:

• Incorrect bearer token
• Expired credentials
• Auth header format mismatch

Solutions:

• Regenerate token and update in M3 Forge
• Check agent documentation for correct header format
• Test with curl to isolate issue

Streaming Not Working

Symptoms: No progress updates, task appears stuck

Causes:

• Agent doesn’t support streaming
• WebSocket connection failed
• Firewall blocking WS traffic

Solutions:

• Check agent card for "streaming": true
• Test WebSocket connection with wscat
• Whitelist WS endpoint in firewall

Best Practices

Agent Selection

Do:

• Verify agent provider reputation before connecting
• Test thoroughly in staging before production use
• Monitor agent performance and costs
• Have fallback agents for critical paths

Don’t:

• Connect to unknown/untrusted agents
• Send sensitive data without encryption guarantees
• Rely solely on external agents (single point of failure)

Error Handling

Do:

• Implement timeouts for external agent calls
• Retry with exponential backoff
• Return partial results on failure
• Log all A2A errors for debugging

Don’t:

• Hang indefinitely waiting for responses
• Retry immediately (causes cascading failures)
• Expose internal errors to users

Performance

Do:

• Cache external agent responses when possible
• Use streaming for long-running tasks
• Monitor response times and set SLAs
• Load balance across multiple external agents

Don’t:

• Call external agents synchronously in user-facing paths
• Ignore latency spikes (indicates agent issues)

Next Steps

• Create orchestrations mixing local and A2A agents
• Enable group memory for A2A agents to share context
• Monitor A2A usage in production