systemprompt-agent

A2A protocol implementation for agent-to-agent communication

On this page

Agent-to-Agent (A2A) protocol implementation providing agent registry, discovery, and inter-agent communication.

Overview

The agent crate implements the A2A protocol for agent discovery and communication. It enables agents to find each other, negotiate capabilities, and exchange messages with proper authentication.

Layer Position

Domain Layer
├── systemprompt-users
├── systemprompt-mcp
├── systemprompt-agent  ← You are here
├── systemprompt-ai
└── ...

Depends on: systemprompt-database, systemprompt-security, systemprompt-ai Used by: systemprompt-api, systemprompt-cli

Key Features

  • Agent registry - Central registry of all agents
  • A2A cards - Standardized agent capability declaration
  • Discovery endpoints - Well-known URLs for agent discovery
  • Message handling - Secure agent-to-agent messaging
  • Skill system - Composable agent capabilities

Configuration

Define agents in services/agents/:

# services/agents/assistant.yaml
name: assistant
description: A helpful AI assistant

a2a_card:
  protocol_version: "1.0"
  display_name: "Assistant"
  capabilities:
    text: true
    images: false
    streaming: true
  transport:
    type: http
    endpoint: "/api/v1/agents/assistant"
  security_schemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: "/oauth/token"
          scopes:
            chat: "Send messages"
            admin: "Administrative access"

skills:
  - general_assistance
  - content_writing

system_prompt: |
  You are a helpful AI assistant. Be concise and accurate.

security:
  oauth2:
    scopes: ["chat"]

ai:
  provider: anthropic
  model: claude-sonnet-4-20250514
  max_tokens: 4096

Public API

AgentRegistry

use systemprompt_agent::{AgentRegistry, Agent};

// Get registry
let registry = ctx.agent_registry.clone();

// List all agents
let agents = registry.list_agents().await?;

// Get specific agent
let agent = registry.get_agent("assistant").await?;

// Check agent status
let status = registry.get_status("assistant").await?;

Agent Cards

use systemprompt_agent::A2ACard;

// Get agent's A2A card
let card = agent.a2a_card();

// Serialize for discovery endpoint
let json = serde_json::to_string(&card)?;

Message Handling

use systemprompt_agent::{AgentMessage, AgentResponse};

// Send message to agent
let response = registry.send_message(AgentMessage {
    agent: "assistant".into(),
    content: "Hello, how are you?".into(),
    context: None,
}).await?;

// Handle streaming response
let mut stream = registry.send_message_streaming(message).await?;
while let Some(chunk) = stream.next().await {
    print!("{}", chunk.content);
}

Discovery Endpoints

The agent crate exposes well-known discovery endpoints:

Endpoint Description
/.well-known/agent-card.json Default agent card
/.well-known/agent-cards List all agent cards
/.well-known/agent-cards/{name} Specific agent card
/api/v1/agents/registry Full registry with status

Example card response:

{
  "protocol_version": "1.0",
  "display_name": "Assistant",
  "capabilities": {
    "text": true,
    "images": false,
    "streaming": true
  },
  "transport": {
    "type": "http",
    "endpoint": "/api/v1/agents/assistant"
  },
  "security_schemes": {
    "oauth2": {
      "type": "oauth2",
      "flows": {
        "clientCredentials": {
          "tokenUrl": "/oauth/token",
          "scopes": {
            "chat": "Send messages"
          }
        }
      }
    }
  }
}

Skills System

Skills are composable capabilities for agents:

# services/skills/content_writing/index.yaml
name: content_writing
description: Write and edit content
tags: ["writing", "editing", "content"]

capabilities:
  - Write blog posts
  - Edit documents
  - Generate summaries

tools:
  - search_content
  - create_content
  - edit_content

Use skills in agent definitions:

# services/agents/writer.yaml
skills:
  - content_writing
  - research

CLI Commands

# List agents
systemprompt admin agents list

# Show agent details
systemprompt admin agents show assistant

# Send message
systemprompt admin agents message assistant "Hello"

# View agent tools
systemprompt admin agents tools assistant