Core Concepts

Agents

An agent is an LLM with a system prompt, a set of tools, and optional delegation capabilities. Agents are defined in YAML files in the agents/ directory.

name: myagent
description: A helpful coding assistant
type: interactive

model:
  provider: anthropic/claude-sonnet-4-5-20250929
  temperature: 0.7

system_prompt: |
  You are a coding assistant. Help users write, debug, and test code.

tools:
  allow:
    - "shell:*"
    - "files:*"
    - "edit:*"
    - "search:*"
    - "git:*"

delegates:
  - planner

Agent Types

Tools

Tools are Python scripts that agents can call. Each tool is a standalone script in powers/ with:

1. A Pydantic BaseModel for input validation
2. A function that takes input: YourModel and returns a result
3. Dependencies declared in the # /// script header

# /// script
# dependencies = ["httpx"]
# ///
"""Weather lookup tool."""

from pydantic import BaseModel, Field
import httpx

class GetWeatherInput(BaseModel):
    """Get current weather for a city."""
    city: str = Field(description="City name")

def get_weather(input: GetWeatherInput):
    """Fetch current weather data."""
    resp = httpx.get(f"https://wttr.in/{input.city}?format=j1")
    data = resp.json()
    current = data["current_condition"][0]
    return {
        "city": input.city,
        "temp_c": current["temp_C"],
        "description": current["weatherDesc"][0]["value"],
    }

Tools follow the supypower contract:

• Every function takes exactly one parameter named input typed as a Pydantic BaseModel
• No print() statements (breaks JSON output)
• No input() calls (no interactive terminal)
• Return a Python dict or Pydantic model — it gets serialized to JSON automatically

Tool Naming

Tools are exposed to the LLM as script__function (double underscore). For example:

• powers/shell.py → shell__run_command, shell__run_script
• powers/files.py → files__read_file, files__write_file
• powers/weather.py → weather__get_weather

Tool Permissions

Control which tools an agent can use with allow/deny patterns:

tools:
  allow:
    - "*"              # Allow all tools
  deny:
    - "shell:*"        # But deny shell access

Pattern syntax: script:function or script:* for all functions in a script. Use * for everything.

Delegation

Agents can delegate tasks to other agents. This enables multi-agent workflows where specialized agents handle different parts of a task.

delegates:
  - planner    # Can delegate planning tasks
  - coder      # Can delegate coding tasks

When an agent delegates, it gets a delegate_to_planner and delegate_to_coder tool injected automatically. The delegate runs as a subprocess with its own context and tools.

User → assistant → "Plan how to build a REST API"
                    → delegate_to_planner
                      → planner analyzes, creates plan
                      → returns plan to assistant
                    → "Now implement the plan"
                    → delegate_to_coder
                      → coder writes code, tests
                      → returns results to assistant
                    → presents final result to user

Sessions

Every interactive conversation is a session. Sessions persist to disk as JSONL files and can be resumed, exported, or searched.

# List sessions for an agent
supyagent sessions myagent

# Resume a specific session
supyagent chat myagent --session abc123

# Start a fresh session
supyagent chat myagent --new

# Export a session to markdown
supyagent sessions myagent --export abc123

Sessions are stored in .supyagent/sessions/<agent>/<session_id>.jsonl.

Context Management

Long conversations can exceed the LLM's context window. Supyagent handles this automatically:

1. Full history always persists to disk
2. Context window is managed separately — only recent messages plus an optional summary are sent to the LLM
3. Auto-summarization triggers when message count or token count exceeds thresholds

context:
  auto_summarize: true
  max_messages_before_summary: 30
  max_tokens_before_summary: 128000
  min_recent_messages: 6

When summarization triggers, the system creates a structured state snapshot that captures what's been discussed, what's in progress, and what matters for the next response.

Configuration

Supyagent uses three configuration layers:

# Manage global API keys
supyagent config set ANTHROPIC_API_KEY
supyagent config list
supyagent config delete OPENAI_API_KEY