Protocols

Protocols

Sandcastle implements three open protocol standards for interoperability with other AI systems and frontends.

A2A - Google Agent-to-Agent Protocol

Module: src/sandcastle/api/a2a.py

The Agent-to-Agent (A2A) protocol enables standardized communication between AI agents from different vendors.

Agent discovery

Sandcastle exposes an agent card at the well-known URL:

GET /.well-known/agent.json

Returns:

{
  "name": "Sandcastle",
  "description": "AI workflow orchestrator",
  "url": "http://localhost:8080",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [
    {
      "id": "workflow-execution",
      "name": "Execute Workflow",
      "description": "Run any workflow from YAML or natural language"
    }
  ]
}

Task operations

JSON-RPC 2.0 endpoint at /a2a:

Method	Description
tasks/send	Submit a new task (workflow execution)
tasks/get	Get task status and result
tasks/cancel	Cancel a running task
tasks/sendSubscribe	Submit task with SSE streaming

Use case

Other AI agents can discover Sandcastle, delegate tasks to it, and receive results - all through a standardized protocol. An orchestrating agent could use Sandcastle as a "workflow specialist" in a multi-agent system.

---

AG-UI - CopilotKit Protocol

Module: src/sandcastle/api/agui.py

The AG-UI protocol (Agent-User Interaction) from CopilotKit provides standardized SSE streaming for real-time AI agent updates in frontends.

Streaming endpoint

GET /api/agui/stream/{run_id}

Streams Server-Sent Events with structured messages:

Event type	Description
RUN_STARTED	Workflow execution began
STEP_STARTED	A step began execution
TEXT_MESSAGE_START	Agent started producing output
TEXT_MESSAGE_CONTENT	Incremental text content
TEXT_MESSAGE_END	Agent finished output
STEP_FINISHED	Step completed with result
RUN_FINISHED	Workflow execution complete

Use case

Any AG-UI compatible frontend (CopilotKit, custom React apps) can display real-time workflow progress with streaming text output. The protocol handles the complexity of multi-step, multi-agent execution with a clean event stream.

---

MCP - Model Context Protocol

CLI command: sandcastle mcp

The Model Context Protocol (MCP) from Anthropic allows AI models to use external tools and data sources through a standardized interface.

Starting the MCP server

sandcastle mcp --url http://localhost:8080

This exposes Sandcastle's capabilities as MCP tools that Claude (or any MCP client) can use:

Tool	Description
run_workflow	Execute a workflow by name or YAML content
list_workflows	List available workflows
list_templates	Browse workflow templates
get_run_status	Check run status and results
search_hub	Search community templates

Use case

When configured as an MCP server in Claude Desktop or another MCP client, Sandcastle becomes a tool that Claude can use directly. Ask Claude "Run my lead enrichment workflow for Acme Corp" and it will invoke Sandcastle through MCP.

Configuration example (Claude Desktop)

{
  "mcpServers": {
    "sandcastle": {
      "command": "sandcastle",
      "args": ["mcp", "--url", "http://localhost:8080"]
    }
  }
}

---

Protocol comparison

Aspect	A2A	AG-UI	MCP
Direction	Agent-to-agent	Agent-to-user	Model-to-tool
Transport	JSON-RPC 2.0	SSE streaming	stdio / HTTP
Primary use	Multi-agent orchestration	Real-time UI updates	Tool integration
Discovery	/.well-known/agent.json	N/A	Config file
Streaming	Optional (sendSubscribe)	Always	N/A
Standard by	Anthropic	CopilotKit	Anthropic