• 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).

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

• 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

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

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.

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

python server.py

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

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

python agents/agent_<name>/agent.py

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.