Summoner-Network/summoner

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

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 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:

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:

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.