The coordination protocol for autonomous AI agents
Build, run, and coordinate agents across machines and organizations over a WAN

Website · Docs · Agent Blueprints · Discord · Twitter

Summoner is an open protocol and SDK for networked AI agents. Most agent frameworks coordinate reasoning inside a single process or organization. Summoner coordinates independent agents — running as separate processes — that connect to shared relay servers, like players joining an MMO world. Agents can travel between servers, form peer relationships, and coordinate across organizational boundaries, with self-assigned identities and built-in mechanisms for learning and adapting behavior.

Python SDK. Rust server. Easy deployment via the desktop app. No central orchestrator.

In other words: Your agents, your code, your network.

Map view provided by the Summoner Desktop app to monitor your agent network across the globe.

Quickstart

Clone

Clone this repo:

git clone https://github.com/Summoner-Network/summoner.git
cd summoner

Install

POSIX (macOS, Linux) using Bash

source build_sdk.sh setup --server python && bash install_requirements.sh

If source build_sdk.sh setup does not work in your shell:

bash build_sdk.sh setup --server python
source venv/bin/activate && bash install_requirements.sh

Windows (PowerShell)

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\build_sdk_on_windows.ps1 setup
.\install_requirements_on_windows.ps1

Run Agents

Choose your starting point:

• ⚡ Fastest way to see Summoner working — visual sanity check (recommended for first-time users)
• 🚀 Run real networked agents — full multi-agent interaction

⚡ Fastest Way to See Summoner Working

Want to verify your setup and visualize an agent immediately?

Run the template agent

python learn/webinar_01/template/agent.py

What you’ll see

• Browser opens with the flow graph
• Agent connects to the network
• Environment is fully validated

This is the quickest way to confirm everything is working.

Next steps

• Try learn/webinar_01/example_1 for basic receive routes
• Try learn/webinar_01/example_8 for state transitions
• Or jump below to run fully interactive agents

🚀 Run Real Networked Agents

Run two independent agents and watch them interact.

In Terminal 1:

bash get_agent.sh EchoAgent_0
bash get_agent.sh InputAgent
python server.py

In Terminal 2:

source venv/bin/activate
python agents/agent_EchoAgent_0/agent.py

In Terminal 3:

source venv/bin/activate
python agents/agent_EchoAgent_0/agent.py

In Terminal 4:

source venv/bin/activate
python agents/agent_InputAgent/agent.py

In Terminal 4, type Hello:

> Hello

You will see the two EchoAgent_0 agents interact:

• In Terminal 2:

  2026-03-05 08:28:13.897 - EchoAgent_0 - INFO - Buffered message from:(SocketAddress=127.0.0.1:55043).
  

• In Terminal 3:

  2026-03-05 08:28:32.963 - EchoAgent_0 - INFO - Buffered message from:(SocketAddress=127.0.0.1:55036).
  

• In Terminal 4:

  [Received] Hello
  [Received] Hello
  

What just happened

• Two independent processes connected to a shared relay
• They discovered each other automatically
• Messages flowed without HTTP or orchestration

You now have live, networked agents exchanging messages.

Where to go next

I want to…	Start here
Learn step by step	summoner — seminar from single agent to cross-server travel
Run agents immediately	summoner-agents — 58 ready-to-run blueprints from beginner to expert
Build my own agent from scratch	summoner-sdk — define a build.txt recipe and compose your own SDK
Read the full docs	summoner-docs — guides, API reference, architecture
Hack on core infrastructure	summoner-core — protocol primitives, Rust server, client runtime
Use the desktop UI	summoner-desktop — visual interface for launching servers and agents
Read the protocol spec	summoner-standard — formal specification and conformance requirements

The Programming Model

Define behavior with decorators. Summoner handles networking, transport, and concurrency.

# test.py
from summoner.client import SummonerClient
import asyncio

class MyAgent(SummonerClient):
    def __init__(self):
        super().__init__()
        self.queue = asyncio.Queue()

agent = MyAgent()

# Handle incoming messages
@agent.receive(route="chat")
async def on_message(msg: dict) -> None:
    print(f"Got: {msg}")
    agent.queue.put_nowait(msg)      # forward to send loop

# Produce outgoing messages
@agent.send(route="chat")
async def respond() -> str:
    msg = await agent.queue.get()
    return f"Echo: {msg}"

agent.run(host="127.0.0.1", port=8888)

No HTTP server to build. No executor to deploy. No orchestrator in the middle. The Rust relay handles transport, fan-out, and backpressure — your agent just defines behavior.

To run the example above (see test.py):

# Terminal 1
python server.py

# Terminal 2
python test.py

# Terminal 3
python agents/agent_InputAgent/agent.py
> Hello

What Makes Summoner Different

🔁 Agent mobility — Agents can travel_to(host, port) at runtime, moving between relay servers while preserving identity and resuming conversations.

🔄 True duplex messaging — @receive and @send run independently in parallel. Events, queues, and hooks connect them. No request/response bottleneck.

🧠 Explicit state machines — Routes compose into typed automata with hooks for validation, signing, and replay protection at each transition.

🌐 Relay servers as shared spaces — Servers are meeting points, not controllers. Agents connect outbound (NAT/firewall friendly) and interact with whoever else is in the room. Any party can run a relay.

How Summoner Compares

	Summoner	MCP (Anthropic)	A2A (Google)	LangGraph
Scope	SDK + relays for live agent networking	Model-to-tool/data protocol	Agent discovery + server executors	Graph DSL for workflows
Agent mobility	Yes (travel() / resume)	N/A	No (bound to server)	N/A (in-process)
Messaging	Direct, duplex events; parallel sends	Host-routed	Task/stream over HTTP	In-app node calls
Orchestration	In the agent (routes/flows/automata)	Host agent	Host + server executor	App graph engine
Identity	Hooks for user-defined DID	Host-managed	Registry/OIDC + Agent Cards	None
Cross-org	Designed for untrusted, cross-boundary	Single-organization	Shared enterprise security	Single-process

Summoner doesn't replace these tools — it connects them across the network. Use LangChain for reasoning, CrewAI for task planning, MCP for tool access, and Summoner for the hard part: live, cross-machine agent coordination.

58 ready-to-run blueprints

You can directly import agents from the summoner-agents repo into this repo:

bash get_agent.sh --list
bash get_agent.sh <agent_name>

The summoner-agents repo ships agents from beginner to advanced:

Category	Examples	What you'll learn
Core Messaging	SendAgent, RecvAgent, EchoAgent, StreamAgent	@send, @receive, @hook, LLM streaming
Chat & Control	ChatAgent 0–3	Interactive UI, remote commands, automaton routing
Feedback	ReportAgent, ExamAgent	Queued reports, timed Q&A flows
Graph-Based	CatArrowAgent, CatTriangleAgent, CatUpdateAgent	State machines, decision flows, supply chain modeling
Connectors	ConnectAgent, OrchBridgeAgent	SQLite, LangChain, CrewAI integration
MCP	MCPArXivAgent, MCPPubMedAgent, MCPGitHubAgent	MCP tool servers for external services
Security	HSAgent, HSSellAgent, HSBuyAgent	Nonce handshakes, DID identity, negotiation
MMO Game	GameMasterAgent, GamePlayerAgent	Multiplayer 2D sandbox over the protocol
DNA	DNACloneAgent, DNAMergeAgent	Agent cloning, merging, genetic composition

Multiplayer game running entirely over the Summoner protocol

Integrations

Summoner is the transport and coordination layer — your agent code calls whatever LLMs, APIs, and frameworks you already use:

Integration	How it works
OpenAI / Claude / local LLMs	Call model APIs directly from @receive or @send handlers
LangChain	Run LangChain chains inside Summoner routes via OrchBridgeAgent
CrewAI	Route Summoner payloads to CrewAI crews for multi-step reasoning
MCP	Connect to any MCP tool server (arXiv, PubMed, GitHub, Notion, Reddit)
SQLite / databases	Persistent agent memory via ConnectAgent patterns

Why this exists

The future of AI is not single agents running inside a single process. It is agent populations coordinating across machines, organizations, and trust boundaries — forming relationships, negotiating outcomes, and building reputation over time.

Today's frameworks solve the single-organization problem well. But very few are building the protocol layer for what comes next: autonomous agents that coordinate across the open internet the way web services coordinate over HTTP.

That's what Summoner is for.

Contributing

We welcome contributions at every level:

• 🌱 First time? Check out issues labeled good-first-issue — each one includes context and guidance
• 🧠 Build an agent? Add it to summoner-agents — follow the agent folder structure
• 🔧 Extend the SDK? Use the extension-template to create a module
• 📝 Improve docs? PRs welcome on summoner-docs

See CONTRIBUTING.md for full guidelines.

Community

• 💬 Discord — Chat with the team and other builders
• 🐦 Twitter — Updates and announcements
• 📧 info@summoner.org — Reach us directly

If Summoner is useful to you, please consider giving it a ⭐
It helps other developers find the project.