Key Features

  • Agent Discovery: Static JSON document at /.well-known/agent.json exposing capabilities, authentication methods, and endpoints for seamless agent discovery.
  • Task Lifecycle Management: Complete state machine with input-required, working, completed, failed, and cancelled states via HTTP + JSON-RPC 2.0.
  • Multi-modal Messaging: TextPart, FilePart (base64/URI), and DataPart support for comprehensive artifact exchange between agents.
  • Dual Communication Modes: Synchronous HTTP responses and asynchronous SSE streams or webhook push notifications for long-running tasks.
  • Enterprise Security: TLS 1.2+ mandatory, OAuth2/mTLS/API key authentication, RBAC via JWT scopes, and audit trails with traceId propagation.
  • Web Standards Based: Built on familiar HTTP, SSE, and JSON-RPC standards without requiring shared runtime dependencies.

Use Cases

  • Secure cross-agent workflows - Data analysis agent sends CSV to graphing agent, receives PNG artifacts
  • Enterprise automation - PagerDuty-style bots trigger monitoring agents with SSE log streaming
  • Inter-company collaboration - Supply chain partners exchange purchase orders over mTLS without VPN
  • Multi-modal agent pipelines - Text processing agents coordinating with image/video processing agents
  • Distributed agent orchestration - Complex workflows spanning multiple specialized agents

Pros & Cons

Advantages

  • Works with any HTTP stack without shared runtime requirements
  • Native support for long-running tasks and multi-modal data exchange
  • Enterprise-ready security with TLS/OAuth/mTLS and RBAC out-of-box
  • Leverages familiar web standards (HTTP, SSE, JSON-RPC)
  • Open-source under Apache 2.0 with 50+ partner ecosystem

Disadvantages

  • Discovery and authentication setup requires boilerplate code
  • No built-in tool invocation - must compose with MCP for tool calls
  • Orchestration, retries, and sagas left to caller implementation
  • Still early stage - observability and ops tooling still maturing

Architecture & Core Concepts

  • Agent Discovery Schema: Static /.well-known/agent.json with capabilities, authentication, and endpoints configuration
  • Task Endpoints: /tasks/send (POST), /tasks/sendSubscribe (POST SSE), /tasks/status/{id} (GET), /tasks/cancel/{id} (POST)
  • Message Structure: JSON-RPC 2.0 wrapper with task.parts[] array containing TextPart, FilePart, or DataPart objects
  • Artifact Handling: TaskStatus.artifacts[] with artifactId, mimeType, and inline bytes or signed URL references
  • Security Layer: TLS 1.2+ transport, OAuth2/mTLS/API key auth, RBAC scopes, X-Trace-Id audit propagation

Code Examples

Agent Discovery Document

// https://agent-host/.well-known/agent.json
{
  "capabilities": ["data-analysis", "report-generation"],
  "authentication": "oauth2",
  "endpoints": {
    "baseUrl": "https://agent-host/api/v1",
    "sendSubscribe": "/tasks/sendSubscribe",
    "pushNotifications": "/webhooks/tasks"
  }
}

Task Submission

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tasks/send",
  "params": {
    "task": {
      "id": "report-2025",
      "parts": [
        { "type": "TextPart", "text": "Generate Q3 sales report" },
        { "type": "FilePart", "uri": "s3://bucket/raw.csv" }
      ]
    }
  }
}

Task Status Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "taskId": "report-2025",
    "state": "completed",
    "artifacts": [
      {
        "artifactId": "sales-report-q3",
        "mimeType": "application/pdf",
        "uri": "https://signed-url/report.pdf"
      }
    ]
  }
}

Ecosystem Pattern

# Protocol Composition Pattern:
# - A2A: Agent-to-agent hand-off and coordination
# - MCP: Tool calls and function invocation
# - ACP: Structured workflow orchestration
# - ANP: Decentralized agent networks

# Security Requirements:
# - TLS 1.2+ mandatory (no plain HTTP)
# - OAuth2 (RFC 6749) or mTLS (RFC 8705)
# - RBAC scopes in JWT claims
# - X-Trace-Id header for audit trails