Summoner Agents
45A collection of Summoner clients and agents featuring example implementations and reusable templates
Getting Started
Or connect to the hosted endpoint: https://summoner.org/
README
Summoner Agent Library
Table of Contents
SDK Setup
This repo assumes you have installed Summoner. We keep platform setup on the organization page so this README stays focused on agents. Click these three sections on the org page (via the badges below), in order:
- ① Prereqs: installs Python/Git + optional Rust (depending on your platform).
- ② Use the SDK: runs the installer script for this repo and creates the local
venv/. - ③ Run Agents: installs per-agent dependencies and shows the server + agent launch workflow.
If the org profile README is not visible, use the same sections in the fallback docs:
.github
Desktop App Compatibility
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.pywhich 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.txtfile:-
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
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
ModuleNotFoundErrorwhen 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
There are 58 agents available in this repo.
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. |