Summoner Agent Library

Table of Contents

• SDK setup

• Desktop App Compatibility

• Running an Agent

• Agent Collection

  • Legend
  • Core Messaging Agents
  • Chat Agents
  • Feedback Agents
  • Connector Agents (to MCP, LangChain, CrewAI, etc.)
  • Security and Handshake Agents
  • API Agents 🚧 (in progress)
  • DNA-Induced Agents 🚧 (planned)

SDK Setup

To install the SDK, follow the installation pathways available on the Summoner-Network GitHub organization page. If the profile README is not visible, you can instead consult the fallback instructions in the .github repository.

Desktop App Compatibility

(Click to expand) This repository contains a collection of agent examples designed to run within the Summoner framework. These agents are organized in a structured and standardized format to ensure compatibility with the Summoner desktop application.

Repository Structure

• Agent examples are located in the agents/ directory.
• Supporting materials such as API adapters or shared tools are located in api_library/.

Each subdirectory within agents/ must follow a specific structure to be recognized and imported correctly by the desktop application (see the Required Structure for Agent Folders section below).

Required Structure for Agent Folders

Each folder inside agents/ must comply with the following strict formatting rules:

✅ Mandatory Requirements

• The folder name must follow the naming pattern:

  agent_<name>
  

• The folder must contain a file named agent.py which includes the agent's entry point:

  agent.run()  # should be called within an asyncio context

• All imports from the Summoner SDK should follow one of the two forms:

  from summoner.<module_name> import <function_or_class>
  # or
  import summoner

• The folder must include a requirements.txt file:

  • This file will be used by the desktop app to install the agent's dependencies.

  • If running agents locally from this repository, the SDK must first be installed using:

    source build_sdk.sh setup

  • Then install agent dependencies using:

    pip install -r agents/agent_<name>/requirements.txt

🟡 Optional Guidelines

• The folder may include any additional Python files or resources needed by agent.py. There are no restrictions on file layout beyond the rules listed above.

Here is a well-structured and clear section you can add to your README to explain how to run an agent. It separates environment setup, server launch, and agent execution, while noting where agent-specific overrides might apply:

Running an Agent

(Click to expand) To run an agent within the Summoner framework, follow these steps. This involves launching a server and then starting the agent process.

Activate the Virtual Environment

If you have opened a new terminal, make sure to activate the virtual environment that was created during the SDK installation:

source venv/bin/activate  # For POSIX systems (Linux/macOS)

📝 Note: If you have not installed the SDK yet, run:

source build_sdk.sh setup

Install agent requirements before running any agent

If you want run one specific agent, install the agent's dependencies as follows:

pip install -r agents/agent_<name>/requirements.txt

If you want all agents to be ready, run the helper script from the repository root (POSIX/bash):

bash install_requirements.sh

This script iterates over agents/agent_* and installs each requirements.txt it finds. If an agent folder has no requirements.txt, nothing is installed for that agent.

💡 Tip: If you encounter ModuleNotFoundError when launching an agent, install the requirements using one of the commands above.

Launch the Summoner Server

The Summoner server is defined in the root file server.py. It can be run using either default or custom configurations.

Run with Default Config:

python server.py

Run with Custom Config:

Configuration files are located in the configs/ directory. Some agents may require a specific server configuration — refer to the README file inside the agent's folder for details.

python server.py --config configs/<specific_config>.json

Run the Agent

Once the server is running, you can launch an agent. Most agents are located in folders under agents/ and follow the naming pattern agent_<name>.

Run with Default Behavior:

python agents/agent_<name>/agent.py

Run with Custom Agent Config:

Some agents require additional configuration (e.g., socket parameters, logging, backpressure behavior). These are usually stored in a file like <specific_config>.json in the configs/ folder.

python agents/agent_<name>/agent.py --config configs/<specific_config>.json

💡 Tip: Always consult the README inside the agent's folder for any overrides, environment variables, or preconditions specific to that agent.

Agent Collection

Legend

Click to show the legend.

Column	Description
Agent Name	Name or identifier of the agent.
Description	Brief summary of the agent's functionality.
Level	Difficulty level (e.g. Level 1 = Beginner).
Application	Primary use case (e.g. messaging, orchestration, negotiation).
Features	Key Summoner SDK capability demonstrated (e.g. core, aurora).
DB	✅ if the agent uses a persistent or in-memory database (asqlite, etc.).
Queue	✅ if the agent relies on asynchronous queues (asyncio.Queue, etc.).
Flows	✅ if the agent follows a modular, trigger-driven flow structure.
Logs	✅ if the agent demonstrates information logging via its logger attribute.
Hooks	✅ if the agent defines hooks for pre/postprocessing of messages.
Temp.	✅ if the agent is designed to serve as a reusable template.
Comp.	✅ if the agent is composable within a larger multi-agent system.

Core Messaging Agents

(Click to expand) Agents of level 1 and 2 introducing core messaging primitives like @send, @receive, and @hook.

Agent Name	Description	Level	Features	Applications	DB	Queue	Flows	Logs	Hooks	Temp.	Comp.
SendAgent_0	Demonstrates the use of @send		core		✗	✗	✗	✗	✗	✅	✅
SendAgent_1	Demonstrates the use of @send and @hook with Direction.SEND.		core DID		✗	✗	✗	✅	✅	✅	✅
RecvAgent_0	Demonstrates the use of @receive.		core		✅	✗	✗	✅	✗	✅	✅
RecvAgent_1	Demonstrates the use of @receive and @hook with Direction.RECEIVE.		core		✅	✗	✗	✅	✅	✅	✅
RecvAgent_2	Demonstrates the use of @receive and @hook to implement validation, banning, and message filtering.		core validation reputation		✅	✗	✗	✅	✅	✅	✅
EchoAgent_0	Combines both @send and @receive.		core		✗	✅	✗	✅	✅	✅	✅
EchoAgent_1	Combines both @send and @receive with a receiving hook.		core validation		✗	✅	✗	✅	✅	✅	✅
EchoAgent_2	Combines @send and @receive handlers with sending and receiving hooks checking for validation and signing messages.		core validation DID agent		✗	✅	✗	✅	✅	✅	✅

Chat Agents

(Click to expand) Agents of level 1-3 that implement chat-style user interfaces, remote commands, and automaton routing for interactive control.

Agent Name	Description	Level	Features	Applications	DB	Queue	Flows	Logs	Hooks	Temp.	Comp.
ChatAgent_0	Implements a minimal chat UI via @send/@receive; supports single- or multi-line input.		core		✗	✗	✗	✗	✗	✅	✅
ChatAgent_1	Extends ChatAgent_0 with remote/self commands (travel, go_home, quit).		core traveling		✗	✗	✗	✗	✗	✅	✅
ChatAgent_2	Activates automaton routing via @upload_states; toggles opened/locked to gate remote commands.		core upload_states traveling		✗	✗	✅	✗	✗	✅	✅
ChatAgent_3	Shows explicit automaton transitions with Move/Stay (opened → locked → opened); remote/self travel, lock/open, quit.		core upload_states download_states traveling		✗	✗	✅	✗	✗	✅	✅

Feedback Agents

(Click to expand) Agents of level 1-3 for structured feedback: question/answer flows, delayed responses, and reporting mechanisms.

Agent Name	Description	Level	Features	Applications	DB	Queue	Flows	Logs	Hooks	Temp.	Comp.
ReportAgent_0	Queues messages for a short window, then sends one newline-joined report.		core		✗	✅	✗	✗	✗	✅	✅
ReportAgent_1	Queues messages for a short window, then emits them separately using multi=True.		core multi		✗	✅	✗	✗	✗	✅	✅
ExamAgent_0	Demonstrates use of @receive and @send with queues and delays to run an automated Q&A round.		core		✗	✅	✅	✗	✗	✅	✅
ExamAgent_1	Extends ExamAgent_0 with flow-routed @receive; @send still runs timed scoring but delegates state handling to the flow engine.		core		✗	✅	✅	✗	✅	✅	✅

Connector Agents

(Click to expand) Agents of level 1-2 enabling composability via connectors to integrate external ecosystems (e.g., MCP, LangChain, CrewAI).

Agent Name	Description	Level	Features	Applications	DB	Queue	Flows	Logs	Hooks	Temp.	Comp.
ConnectAgent_0	Combines @receive and @send(multi=True) to relay Summoner messages via SQLite, using db_sdk (ORM) with batching and persistent connections.		core multi		✅	✗	✗	✗	✗	✅	✗
ConnectAgent_1	Combines @receive and @send(multi=True) to relay Summoner messages via SQLite, using raw aiosqlite with short-lived connections.		core multi		✅	✗	✗	✗	✗	✅	✗
OrchBridgeAgent	Direct bridge: routes Summoner payloads to CrewAI (JSON via Crew+ChatOpenAI) or LangChain (text/structured), enabling drop-in composition with external orchestrators.		core agent DID guardrails LangChain CrewAI		✗	✅	✗	✅	✅	✅	✅

MMO-game agents

(Click to expand) Agents of level 3–4 that implement a shared 2D sandbox: game masters simulate and broadcast world state while players send keyboard input and render a local view using @receive, @send, and @hook.

Agent Name	Description	Level	Features	Applications	DB	Queue	Flows	Logs	Hooks	Temp.	Comp.
GameMasterAgent_0	Authoritative simulator for a 2D world. Consumes player ticks via @receive, broadcasts world_state via @send. Uses @hook to normalize envelopes.		core DID		🟡	✗	✗	✅	✅	✅	✗
GameMasterAgent_1	Large-map simulator with clustered golden-angle spawning. Consumes player ticks via @receive, broadcasts world_state via @send. Uses @hook to normalize envelopes.		core DID		🟡	✗	✗	✅	✅	✅	✗
GamePlayerAgent_0	Minimal client UI. Polls keyboard into a keys dict, emits ticks at 20 Hz with @send, and renders world_state received via @receive. Uses @hook to normalize and stamp pid.		core DID		✗	✗	✗	✗	✅	✅	✗
GamePlayerAgent_1	Same messaging pattern as with GamePlayerAgent_0. Resizable client with camera follow, checkerboard grass, optional avatar. Adds persistent ID via --id and configurable client logger.		core DID		✗	✗	✗	✅	✅	✅	✗
GamePlayerAgent_2	Same messaging pattern as with GamePlayerAgent_1. Client with seeded pixel-art grass and an LRU tile cache for performance. Uses persistent ID and --seed for deterministic visuals.		core DID		✗	✗	✗	✅	✅	✅	✗

Security and Handshake Agents

(Click to expand) Agents of level 1, 4, 5 and 6 covering backpressure tests, validation hooks, cryptographic DID handshakes, and decision-making in negotiation flows.

Agent Name	Description	Level	Features	Applications	DB	Queue	Flows	Logs	Hooks	Temp.	Comp.
RateLimitAgent_0	Tests server backpressure using @send and @receive.		core multi		✗	✗	✗	✗	✗	✅	✅
RateLimitAgent_1	Tests server backpressure using @send(multi=True) and @receive to simulate concurrent sends		core multi		✗	✗	✗	✗	✗	✅	✅
RateLimitAgent_2	Tests backpressure using @send(multi=True) and terminates via .quit() in @receive.		core multi traveling		✗	✗	✗	✗	✗	✅	✅
HSAgent_0	Explores a nonce-echo handshake to initiate and finalize an exchange.		core multi upload_states download_states on_triggers validation DID		✅	✗	✅	✅	✅	✅	✗
HSAgent_1	Explores a cryptographic handshake with persistent DID identity to initiate and finalize an exchange.		core multi upload_states download_states on_triggers validation DID		✅	✗	✅	✅	✅	✅	✗
HSSellAgent_0	Explores a selling negotiation overlay on top of the handshake to initiate and finalize a deal.		core multi upload_states download_states on_triggers validation DID		✅	✗	✅	✅	✅	✅	✗
HSBuyAgent_0	Explores a buying negotiation overlay on top of the handshake to initiate and finalize a deal.		core multi upload_states download_states on_triggers validation DID		✅	✗	✅	✅	✅	✅	✗

API Agents 🚧

(Click to expand) Agents of level 1-3 bridging external services (registries, apps, LLM tools) to extend SDK capabilities.

Agent Name	Description	Level	Features	Applications	DB	Queue	Flows	Logs	Hooks	Temp.	Comp.
Wikipedia	...		core		✗	✗	✗	✗	✗	✗	✗
ArXiv	...		core		✗	✗	✗	✗	✗	✗	✗
PubMed	...		core		✗	✗	✗	✗	✗	✗	✗
GitHub	...		core		✗	✗	✗	✗	✗	✗	✗
Reddit	...		core		✗	✗	✗	✗	✗	✗	✗
Notion	...		core		✗	✗	✗	✗	✗	✗	✗
Slack	...		core		✗	✗	✗	✗	✗	✗	✗
GPTRespondAgent	Guarded GPT responder: builds (personality + format) prompt and returns JSON; adds token/cost guardrails to control API cost.		core agent DID guardrails		✗	✅	✗	✅	✅	✅	✅
LangChainCrewAIAgent	Guarded GPT responder with CrewAI/LangChain compatibility: JSON via CrewAI + ChatOpenAI, or using text/structured via LangChain; adds token/cost guardrails to control API cost.		core agent DID guardrails LangChain CrewAI		✗	✅	✗	✅	✅	✅	✅
GPTClusterAgent	Embeds texts with budget guards, then clusters via configurable algorithms (K-Means default; Agglomerative/DBSCAN optional).		core agent DID analytics guardrails		✗	✅	✗	✅	✅	✅	✅
InputAgent	Minimal bridge: emits raw strings or parsed JSON; supports single- or multi-line input.		core		✗	✗	✗	✗	✗	✅	✅

DNA-Induced Agents 🚧

(Click to expand) Agents of level 3 showcasing the use of agentic DNA to merge or clone agent code.

Agent Name	Description	Level	Features	Applications	DB	Queue	Flows	Logs	Hooks	Temp.	Comp.
MergeAgent	...		core		✗	✗	✗	✗	✗	✗	✗