Agents That Coordinate

Single agents are powerful. Multiple agents working together are transformative. But coordinating agents—passing context, managing state, handling failures—is complex infrastructure you shouldn't build from scratch.

SystemPrompt implements the A2A (Agent-to-Agent) protocol for production multi-agent orchestration.

The Problem

Building multi-agent systems requires:

• Communication protocol: How do agents talk to each other?
• Task management: Who's doing what? What's the status?
• State sharing: How do agents share context and results?
• Discovery: How do agents find each other?
• Error handling: What happens when an agent fails mid-task?
• Permissions: Which agents can invoke which other agents?

Most teams build ad-hoc agent pipelines. They work until they don't.

The Solution

SystemPrompt provides a complete agent orchestration layer:

Agent-to-Agent Protocol (A2A)

Standard protocol for agent communication:

# services/agents/coordinator.yaml
name: coordinator
description: "Orchestrates research and writing agents"
capabilities:
  - agent:invoke
allowed_agents:
  - researcher
  - writer
  - reviewer
system_prompt: |
  You coordinate research and writing tasks.
  Use the researcher agent for gathering information.
  Use the writer agent for creating content.
  Use the reviewer agent for quality checks.

Agent Discovery

Agents are discoverable via standard endpoints:

# List all agents
curl https://yourdomain.com/api/v1/agents/registry

# Get agent card (A2A protocol)
curl https://yourdomain.com/.well-known/agent-card.json

# Get specific agent
curl https://yourdomain.com/.well-known/agent-cards/coordinator

Agent cards describe capabilities:

{
  "name": "coordinator",
  "description": "Orchestrates research and writing agents",
  "capabilities": ["agent:invoke", "task:manage"],
  "allowed_agents": ["researcher", "writer", "reviewer"],
  "endpoint": "https://yourdomain.com/api/v1/agents/coordinator"
}

Task Management

Track multi-step agent workflows:

# View active tasks
systemprompt admin agents tasks list

# Get task status
systemprompt admin agents tasks show <task-id>

# Cancel a task
systemprompt admin agents tasks cancel <task-id>

Tasks track:

• Current step and status
• Agent assignments
• Input/output artifacts
• Execution timeline
• Error states

Context Sharing

Agents share context through managed state:

# services/agents/researcher.yaml
name: researcher
context:
  shared: true  # Share context with invoking agent
  persist: true # Maintain context across invocations

# Create shared context
systemprompt core contexts create --name "research-project"

# Agents use shared context
systemprompt admin agents message researcher "Find information about MCP" \
  --context research-project

Real-Time Streaming (AGUI)

Stream agent execution events to your UI:

// Connect to agent GUI stream
const ws = new WebSocket('wss://yourdomain.com/api/v1/agents/coordinator/stream');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // data.type: 'step_start', 'tool_call', 'agent_invoke', 'step_complete'
  // data.agent: which agent is executing
  // data.content: execution details
};

Events include:

• Step start/complete
• Tool calls and results
• Agent invocations
• Artifact publications
• Error states

Multi-Agent Workflows

Define complex workflows with agent coordination:

# services/agents/content-pipeline.yaml
name: content-pipeline
type: orchestrator
workflow:
  steps:
    - agent: researcher
      task: "Research the topic"
      output: research_notes

    - agent: writer
      task: "Write article based on research"
      input: research_notes
      output: draft

    - agent: reviewer
      task: "Review and suggest improvements"
      input: draft
      output: feedback

    - agent: writer
      task: "Apply feedback and finalize"
      input: [draft, feedback]
      output: final_article

Artifact Sharing

Agents publish and consume artifacts:

# Artifacts can be:
artifacts:
  types:
    - text      # Markdown, code, prose
    - image     # Generated or referenced images
    - table     # Structured data
    - chart     # Visualizations
    - dashboard # Complex layouts
    - research  # Formatted research output

# View artifacts from a task
systemprompt admin agents artifacts list --task <task-id>

# Get specific artifact
systemprompt admin agents artifacts show <artifact-id>

Why This Matters

Beyond Single Agents

Single-player AI:

• One agent, one task
• Manual orchestration
• No state persistence

Multiplayer AI (SystemPrompt):

• Specialized agents collaborate
• Automatic coordination
• Shared state and context

Production Patterns

Common multi-agent patterns:

Research → Write → Review

researcher → writer → reviewer → final

Parallel Processing

coordinator → [agent1, agent2, agent3] → aggregator

Hierarchical Delegation

manager → [team_lead1 → workers, team_lead2 → workers]

Observability

Full visibility into agent coordination:

# View agent execution trace
systemprompt infra logs --trace <trace-id>

# See which agents were invoked
systemprompt analytics agents invocations --period day

# Track agent performance
systemprompt analytics agents performance

Security & Permissions

Agent-Level Permissions

Control which agents can invoke others:

# services/agents/restricted-agent.yaml
name: restricted-agent
security:
  oauth2:
    scopes: ["agent:invoke:researcher"]  # Can only invoke researcher

User-Scoped Agent Access

Users only access their permitted agents:

security:
  oauth2:
    scopes: ["user:{{user_id}}", "agent:coordinator"]

Audit Trail

Every agent invocation is logged:

systemprompt infra logs --type agent.invoke

Getting Started

Create a coordinator agent:

# services/agents/coordinator.yaml
name: coordinator
capabilities:
  - agent:invoke
allowed_agents:
  - helper
system_prompt: |
  You coordinate tasks with helper agents.

Create a helper agent:

# services/agents/helper.yaml
name: helper
system_prompt: |
  You help with specific tasks when invoked.

Invoke the coordinator:

systemprompt admin agents message coordinator \
  "Research and summarize the topic of AI safety"

The coordinator will automatically invoke helper agents as needed.

See the Agent Reference for detailed configuration options.