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, all with cryptographic identity and behavior-based reputation.
Python SDK. Rust server. No central orchestrator. Your agents, your code, your network.
Two agents negotiating a deal via cryptographic handshake — one of 58 ready-to-run blueprints
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
Want to verify your setup and visualize an agent immediately?
git clone https://github.com/Summoner-Network/learn-summoner.git
cd learn-summoner
source build_sdk.sh setup --server python
bash install_requirements.shpython learn/template/agent.py- 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.
- Try
learn/example_1for basic receive routes - Try
learn/example_8for state transitions - Or jump below to run fully interactive agents
Run two independent agents and watch them interact.
git clone https://github.com/Summoner-Network/summoner-agents.git
cd summoner-agents
source build_sdk.sh setup # creates venv, installs SDK + Rust server
pip install -r agents/agent_EchoAgent_0/requirements.txtsource venv/bin/activate
python server.pysource venv/bin/activate
python agents/agent_EchoAgent_0/agent.pyOpen a third terminal and run a second agent to see them interact.
- 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.
Windows? Use
.\build_sdk_on_windows.ps1 setupin PowerShell.
See the full platform setup: https://github.com/Summoner-Network#-install-essential-dependencies
| I want to… | Start here |
|---|---|
| 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 |
| Learn step by step | learn-summoner — seminar from single agent to cross-server travel |
| 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 |
Define behavior with decorators. Summoner handles networking, transport, and concurrency.
from summoner.client import SummonerClient
class MyAgent(SummonerClient): pass
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.
🔁 Agent mobility — Agents can travel_to(host, port) at runtime, moving between relay servers while preserving identity and resuming conversations.
🔐 Cryptographic identity — Self-assigned decentralized IDs (DIDs), nonce handshakes, and signed/encrypted messages. Trust is earned through behavior, not granted by a central authority.
🔄 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.
| 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) |
No | No | 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 | Self-assigned DIDs; nonce handshake | 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.
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
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 |
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 nobody is 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.
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-templateto create a module - 📝 Improve docs? PRs welcome on
summoner-docs - 💡 Propose a change? Open an issue or start a Discussion
See CONTRIBUTING.md for full guidelines.
- 💬 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.