Agent-to-Agent Interface (A2A)

Overview

The A2A (Agent-to-Agent) Interface provides a standardized protocol for inter-agent communication, based on JSON-RPC 2.0, supporting both synchronous and streaming communication modes.

Protocol Standards

• JSON-RPC 2.0: Industry-standard RPC protocol
• Server-Sent Events (SSE): Streaming response transport
• RESTful HTTP: HTTP-based endpoint implementation

Core Components

pkg/agentos/a2a/
├── types.go      # Protocol type definitions
├── validator.go  # Request validation
├── mapper.go     # Protocol mapping
├── a2a.go        # A2A interface management
└── handlers.go   # HTTP handlers

Quick Start

1. Create A2A Interface

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/rexleimo/agno-go/pkg/agentos/a2a"
    "github.com/rexleimo/agno-go/pkg/agno/agent"
)

func main() {
    // Create agent
    myAgent, _ := agent.New(&agent.Config{
        Name:  "my-agent",
        Model: model,
        // ... other config
    })

    // Create A2A interface
    a2aInterface := a2a.New("/api/v1/a2a")

    // Register agent as entity
    a2aInterface.RegisterEntity("my-agent", myAgent)

    // Setup Gin routes
    router := gin.Default()
    a2aInterface.SetupRoutes(router)

    router.Run(":8080")
}

2. Send Synchronous Message

curl -X POST http://localhost:8080/api/v1/a2a/sendMessage \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "sendMessage",
    "id": "req-001",
    "params": {
      "message": {
        "messageId": "msg-001",
        "role": "user",
        "agentId": "my-agent",
        "contextId": "session-123",
        "parts": [
          {
            "type": "text",
            "content": "Hello, agent!"
          }
        ]
      }
    }
  }'

Response Example:

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "result": {
    "task": {
      "taskId": "task-001",
      "status": "completed",
      "messages": [
        {
          "messageId": "msg-002",
          "role": "assistant",
          "agentId": "my-agent",
          "contextId": "session-123",
          "parts": [
            {
              "type": "text",
              "content": "Hello! How can I help you?"
            }
          ]
        }
      ]
    }
  }
}

3. Send Streaming Message

curl -X POST http://localhost:8080/api/v1/a2a/streamMessage \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "streamMessage",
    "id": "req-002",
    "params": {
      "message": {
        "messageId": "msg-003",
        "role": "user",
        "agentId": "my-agent",
        "contextId": "session-123",
        "parts": [
          {
            "type": "text",
            "content": "Tell me a story"
          }
        ]
      }
    }
  }'

SSE Response Stream:

data: {"type":"content","content":"Once"}

data: {"type":"content","content":" upon"}

data: {"type":"content","content":" a"}

data: {"type":"content","content":" time..."}

data: {"type":"done"}

Protocol Details

JSON-RPC 2.0 Request Format

type JSONRPC2Request struct {
    JSONRPC string        `json:"jsonrpc"`  // Must be "2.0"
    Method  string        `json:"method"`   // "sendMessage" or "streamMessage"
    ID      string        `json:"id"`       // Unique request ID
    Params  RequestParams `json:"params"`   // Request parameters
}

type RequestParams struct {
    Message Message `json:"message"`  // Message content
}

Message Structure

type Message struct {
    MessageID string `json:"messageId"`  // Unique message ID
    Role      string `json:"role"`       // "user" or "assistant"
    AgentID   string `json:"agentId"`    // Target agent ID
    ContextID string `json:"contextId"`  // Session context ID
    Parts     []Part `json:"parts"`      // Message parts
}

type Part struct {
    Type    string `json:"type"`              // "text" or "data"
    Content string `json:"content,omitempty"` // Text content
    Data    string `json:"data,omitempty"`    // Structured data (JSON)
}

Response Format

Success Response

type JSONRPC2Response struct {
    JSONRPC string        `json:"jsonrpc"`  // "2.0"
    ID      string        `json:"id"`       // Matching request ID
    Result  *ResultObject `json:"result"`   // Result object
}

type ResultObject struct {
    Task Task `json:"task"`  // Task information
}

type Task struct {
    TaskID   string    `json:"taskId"`   // Task ID
    Status   string    `json:"status"`   // "completed" or "failed"
    Messages []Message `json:"messages"` // Response messages
}

Error Response

type JSONRPC2Response struct {
    JSONRPC string       `json:"jsonrpc"`
    ID      string       `json:"id"`
    Error   *ErrorObject `json:"error"`
}

type ErrorObject struct {
    Code    int    `json:"code"`    // Error code
    Message string `json:"message"` // Error message
}

Standard Error Codes:

• -32700: Parse error (JSON parsing failed)
• -32600: Invalid Request (invalid request format)
• -32601: Method not found (method does not exist)
• -32602: Invalid params (invalid parameters)
• -32603: Internal error (internal server error)

Validation Mechanism

Request Validation

The A2A interface provides complete request validation:

func ValidateRequest(req *JSONRPC2Request) error {
    // 1. Check JSON-RPC version
    if req.JSONRPC != "2.0" {
        return fmt.Errorf("invalid jsonrpc version, must be 2.0")
    }

    // 2. Check method
    if req.Method != "sendMessage" && req.Method != "streamMessage" {
        return fmt.Errorf("invalid method, must be sendMessage or streamMessage")
    }

    // 3. Check request ID
    if req.ID == "" {
        return fmt.Errorf("request id is required")
    }

    // 4. Validate message
    return ValidateMessage(&req.Params.Message)
}

func ValidateMessage(msg *Message) error {
    // Check required fields
    if msg.MessageID == "" {
        return fmt.Errorf("messageId is required")
    }
    if msg.Role == "" {
        return fmt.Errorf("role is required")
    }
    if msg.AgentID == "" {
        return fmt.Errorf("agentId is required")
    }
    if len(msg.Parts) == 0 {
        return fmt.Errorf("message must have at least one part")
    }

    // Validate each part
    for i, part := range msg.Parts {
        if err := ValidatePart(&part); err != nil {
            return fmt.Errorf("invalid part at index %d: %w", i, err)
        }
    }

    return nil
}

Advanced Features

1. Entity Management

The A2A interface supports registering multiple entities (Agent/Workflow):

// Register multiple agents
a2aInterface.RegisterEntity("sales-agent", salesAgent)
a2aInterface.RegisterEntity("support-agent", supportAgent)
a2aInterface.RegisterEntity("analytics-agent", analyticsAgent)

// Get entity
entity, exists := a2aInterface.GetEntity("sales-agent")

// List all entities
entities := a2aInterface.ListEntities()
// Returns: ["sales-agent", "support-agent", "analytics-agent"]

2. Custom Path Prefix

// Default prefix: "/api/v1/a2a"
a2aInterface := a2a.New("/api/v1/a2a")

// Custom prefix
a2aInterface := a2a.New("/my/custom/path")

// Endpoint paths:
// POST /my/custom/path/sendMessage
// POST /my/custom/path/streamMessage

3. Protocol Mapping

The A2A interface automatically handles protocol mapping:

// A2A Message → Agent RunInput
runInput, err := a2a.MapA2ARequestToRunInput(req)

// Agent RunOutput → A2A Task
task := a2a.MapRunOutputToTask(output, &req.Params.Message)

Complete Example

Server Side

package main

import (
    "context"
    "log"

    "github.com/gin-gonic/gin"
    "github.com/rexleimo/agno-go/pkg/agentos/a2a"
    "github.com/rexleimo/agno-go/pkg/agno/agent"
    "github.com/rexleimo/agno-go/pkg/agno/models/openai"
)

func main() {
    // 1. Create model
    model, err := openai.New("gpt-4", openai.Config{
        APIKey: "your-api-key",
    })
    if err != nil {
        log.Fatal(err)
    }

    // 2. Create agent
    myAgent, err := agent.New(&agent.Config{
        Name:         "customer-service",
        Model:        model,
        Instructions: "You are a helpful customer service agent.",
    })
    if err != nil {
        log.Fatal(err)
    }

    // 3. Create A2A interface
    a2aInterface := a2a.New("/api/v1/a2a")
    a2aInterface.RegisterEntity("customer-service", myAgent)

    // 4. Setup routes
    router := gin.Default()
    a2aInterface.SetupRoutes(router)

    // 5. Start server
    log.Println("A2A server listening on :8080")
    router.Run(":8080")
}

Client Side (Go)

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"

    "github.com/rexleimo/agno-go/pkg/agentos/a2a"
)

func main() {
    // Build request
    request := &a2a.JSONRPC2Request{
        JSONRPC: "2.0",
        Method:  "sendMessage",
        ID:      "req-001",
        Params: a2a.RequestParams{
            Message: a2a.Message{
                MessageID: "msg-001",
                Role:      "user",
                AgentID:   "customer-service",
                ContextID: "session-123",
                Parts: []a2a.Part{
                    {
                        Type:    "text",
                        Content: "How do I return a product?",
                    },
                },
            },
        },
    }

    // Serialize
    requestBody, _ := json.Marshal(request)

    // Send request
    resp, err := http.Post(
        "http://localhost:8080/api/v1/a2a/sendMessage",
        "application/json",
        bytes.NewBuffer(requestBody),
    )
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    // Read response
    body, _ := io.ReadAll(resp.Body)

    var response a2a.JSONRPC2Response
    json.Unmarshal(body, &response)

    // Process result
    if response.Error != nil {
        fmt.Printf("Error: %s\n", response.Error.Message)
        return
    }

    task := response.Result.Task
    fmt.Printf("Task Status: %s\n", task.Status)
    for _, msg := range task.Messages {
        for _, part := range msg.Parts {
            fmt.Printf("Agent Response: %s\n", part.Content)
        }
    }
}

Best Practices

1. Error Handling

// Use standard error codes
if err := validateInput(); err != nil {
    return &a2a.ErrorObject{
        Code:    -32602, // Invalid params
        Message: err.Error(),
    }
}

2. ContextID Management

// Use unique contextId for each session
contextID := fmt.Sprintf("session-%s-%d", userID, time.Now().Unix())

// All messages in the same session use the same contextId
message1.ContextID = contextID
message2.ContextID = contextID

3. Concurrent Processing

// A2A interface is concurrency-safe
// Can handle multiple requests simultaneously

for i := 0; i < 10; i++ {
    go func(id int) {
        // Send requests concurrently
        sendMessageToAgent(fmt.Sprintf("req-%d", id))
    }(i)
}

4. Timeout Control

// Set request timeout
client := &http.Client{
    Timeout: 30 * time.Second,
}

resp, err := client.Post(url, contentType, body)

Performance Metrics

• Average Response Time: ~200ms (depends on model)
• Concurrent Processing: 1000+ requests/s
• Memory Footprint: ~50KB per active connection

Troubleshooting

Common Issues

1. "Invalid JSON-RPC version"

Cause: jsonrpc field is not "2.0"

Solution:

{
  "jsonrpc": "2.0",  // Must be string "2.0"
  "method": "sendMessage",
  ...
}

2. "Agent not found"

Cause: agentId is not registered

Solution:

// Check registered entities
entities := a2aInterface.ListEntities()
fmt.Println(entities)

// Ensure agent is registered
a2aInterface.RegisterEntity("your-agent-id", agent)

3. "Invalid message format"

Cause: Message is missing required fields

Solution:

{
  "messageId": "msg-001",     // ✅ Required
  "role": "user",             // ✅ Required
  "agentId": "my-agent",      // ✅ Required
  "contextId": "session-123", // ⚠️ Optional but recommended
  "parts": [                  // ✅ Required, at least one
    {
      "type": "text",
      "content": "Hello"
    }
  ]
}

Related Documentation

• Session State Management - Session state management
• Multi-Tenant Support - Multi-tenant support
• Architecture Design - Architecture design

Version History

• v1.1.0 (2025-01-XX): Initial A2A interface implementation
  • JSON-RPC 2.0 protocol support
  • Synchronous and streaming modes
  • Complete validation and error handling

---

Last Updated: 2025-01-XX