Configuration Reference

Every agent is defined by a YAML file in the agents/ directory. This page documents every field, its type, default value, and behavior.

Complete Annotated Example

agents/myagent.yaml

# Required fields
name: myagent                    # string (1-50 chars), must be unique
description: A helpful assistant # string, shown in delegation tool descriptions
version: "1.0"                   # string, for your own tracking
type: interactive                # "interactive" | "execution" | "daemon"

# LLM model settings
model:
  provider: anthropic/claude-sonnet-4-5-20250929  # LiteLLM model identifier (required)
  temperature: 0.7               # float 0-2 (default: 0.7)
  max_tokens: 8192               # int or null (default: null = provider max)
  max_retries: 3                 # int >= 0 (default: 3)
  retry_delay: 1.0               # float > 0, initial retry delay in seconds
  retry_backoff: 2.0             # float > 1, exponential backoff multiplier
  fallback:                      # list of fallback model identifiers
    - openai/gpt-4o
    - google/gemini-2.5-flash
  cache: true                    # enable prompt caching (default: true)

# System prompt (required, min 1 char)
system_prompt: |
  You are a helpful AI assistant with access to tools.
  Use your tools to help the user accomplish their tasks.

# Tool permissions
tools:
  allow:
    - "*"                        # glob patterns for allowed tools
  deny:
    - "shell:*"                  # glob patterns for denied tools

# Agents this agent can delegate to
delegates:
  - planner
  - coder

# Whether to inject tool-creation instructions into the system prompt
will_create_tools: false

# Credential specifications
credentials:
  - name: GITHUB_TOKEN
    description: GitHub personal access token for API calls
    required: true
  - name: SLACK_WEBHOOK
    description: Slack webhook URL for notifications
    required: false

# Execution limits
limits:
  max_tool_calls_per_turn: 50
  max_total_tool_calls: 200
  circuit_breaker_threshold: 3   # consecutive failures before blocking a tool
  repetition_threshold: 4        # identical calls before blocking

# Context window management
context:
  auto_summarize: true
  max_messages_before_summary: 30
  max_tokens_before_summary: 128000
  min_recent_messages: 6
  response_reserve: 4096

# Process supervisor settings
supervisor:
  default_timeout: 60
  on_timeout: background         # "background" | "kill" | "wait"
  max_background_processes: 10
  force_background_patterns:
    - "*__start_server*"
    - "*__run_server*"
    - "*__serve*"
  force_sync_patterns:
    - "*__read_*"
    - "*__list_*"
    - "*__get_*"
  tool_settings:
    "web__scrape_page":
      timeout: 120
      mode: sync                 # "sync" | "background" | "auto"
  default_delegation_mode: subprocess
  delegation_timeout: 600

# Delegation behavior
delegation:
  share_credentials: true
  share_summary: true
  default_mode: subprocess       # "subprocess" | "in_process"
  default_timeout: 300

# Long-term memory
memory:
  enabled: true
  extraction_threshold: 5
  retrieval_limit: 10
  auto_extract: true

# Workspace directory
workspace: /path/to/project

# Container sandbox
sandbox:
  enabled: false
  image: python:3.12-slim
  runtime: auto                  # "auto" | "podman" | "docker"
  network: bridge                # "none" | "host" | "bridge"
  memory_limit: 2g
  allow_shell: true
  setup_commands:
    - pip install pandas
  extra_mounts:
    - host_path: /data/datasets
      container_path: /mnt/data
      readonly: true
  env:
    MY_VAR: value

# Service integration (supyagent cloud)
service:
  enabled: true
  url: https://app.supyagent.com

# Daemon schedule (only used when type=daemon)
schedule:
  interval: 5m                   # "30s", "5m", "1h"
  max_events_per_cycle: 10
  prompt: null                   # optional task to run each cycle

Field Reference

Top-Level Fields

Field	Type	Default	Description
`name`	`string`	required	Agent name, 1-50 characters. Must match the filename (e.g., `agents/coder.yaml` has `name: coder`).
`description`	`string`	`""`	Human-readable description. Shown in delegation tool descriptions when other agents delegate to this one.
`version`	`string`	`"1.0"`	Version string for your own tracking.
`type`	`string`	`"interactive"`	Agent execution type. One of `interactive`, `execution`, or `daemon`.
`system_prompt`	`string`	required	The system prompt sent to the LLM. Use YAML `\|` for multi-line.
`will_create_tools`	`bool`	`false`	When `true`, appends tool-creation instructions to the system prompt so the agent can write new supypowers scripts at runtime.
`delegates`	`list[string]`	`[]`	Names of agents this agent can delegate to. Each name must match a YAML file in `agents/`.
`workspace`	`string \| null`	`null`	Working directory for tool execution. Tools run relative to this path.

Agent Types

Type	Command	Behavior
`interactive`	`supyagent chat`	Stateful chat with session persistence, streaming, credential prompting.
`execution`	`supyagent run`	Stateless input-to-output pipeline. No session storage, no credential prompting.
`daemon`	`supyagent daemon`	Event-driven polling loop. Reads from AI inbox, processes events, archives them.

model

Controls the LLM provider and generation parameters.

Field	Type	Default	Description
`provider`	`string`	required	LiteLLM model identifier (e.g., `anthropic/claude-sonnet-4-5-20250929`). See Models for all providers.
`temperature`	`float`	`0.7`	Sampling temperature, 0-2. Lower values are more deterministic.
`max_tokens`	`int \| null`	`null`	Maximum response tokens. `null` uses the provider default (usually the model maximum).
`max_retries`	`int`	`3`	Maximum retries on transient LLM errors (rate limits, service unavailable).
`retry_delay`	`float`	`1.0`	Initial delay in seconds between retries.
`retry_backoff`	`float`	`2.0`	Exponential backoff multiplier applied to retry delay.
`fallback`	`list[string]`	`[]`	Fallback model identifiers tried in order when the primary model exhausts retries on transient errors. Non-transient errors (auth, not found) raise immediately without fallback.
`cache`	`bool`	`true`	Enable prompt caching when supported by the provider. Currently activates Anthropic's prompt caching beta header.

tools

Controls which tools the agent can access. See Tool Permissions for details.

Field	Type	Default	Description
`allow`	`list[string]`	`[]`	Glob patterns for allowed tools.
`deny`	`list[string]`	`[]`	Glob patterns for denied tools. Deny takes precedence over allow.

credentials

Declare credentials the agent needs. These are prompted from the user at runtime via the request_credential tool and stored encrypted on disk.

Field	Type	Default	Description
`name`	`string`	required	Environment variable name (e.g., `GITHUB_TOKEN`).
`description`	`string`	`""`	Explains what this credential is for. Shown to the user when prompted.
`required`	`bool`	`false`	Whether this credential is required for the agent to function.

limits

Execution limits as a flat dictionary.

Key	Type	Default	Description
`max_tool_calls_per_turn`	`int`	`100`	Maximum tool call iterations per user message before stopping.
`max_total_tool_calls`	`int`	none	Optional cap on total tool calls across the session.
`circuit_breaker_threshold`	`int`	`3`	Consecutive failures of the same tool before it is blocked for the turn.
`repetition_threshold`	`int`	`4`	Identical tool calls (same name and arguments) before blocking.

context

Controls how long conversations are managed within token limits. See Sessions for usage details.

Field	Type	Default	Description
`auto_summarize`	`bool`	`true`	Automatically summarize when trigger thresholds are reached.
`max_messages_before_summary`	`int`	`30`	Trigger summarization after this many messages since the last summary.
`max_tokens_before_summary`	`int`	`128000`	Trigger summarization when total tokens exceed this threshold.
`min_recent_messages`	`int`	`6`	Minimum recent messages to always include in context (never summarized away).
`response_reserve`	`int`	`4096`	Tokens reserved for the LLM's response.

supervisor

Controls how tool and agent execution is managed by the ProcessSupervisor.

Field	Type	Default	Description
`default_timeout`	`float`	`60`	Seconds to wait before auto-backgrounding a tool.
`on_timeout`	`string`	`"background"`	Action when timeout is reached: `background` (keep running), `kill` (terminate), `wait` (block forever).
`max_background_processes`	`int`	`10`	Maximum concurrent background processes.
`force_background_patterns`	`list[string]`	`["__start_server", ...]`	Glob patterns for tools that always run in background.
`force_sync_patterns`	`list[string]`	`["__read_", ...]`	Glob patterns for tools that always run synchronously.
`tool_settings`	`dict`	`{}`	Per-tool execution settings, keyed by tool name pattern. Each value has `timeout` (float) and `mode` (`sync`, `background`, `auto`).
`default_delegation_mode`	`string`	`"subprocess"`	Default execution mode for delegated agents.
`delegation_timeout`	`float`	`600`	Default timeout for delegated agent tasks in seconds.

delegation

Controls how this agent delegates to other agents. See Delegation for details.

Field	Type	Default	Description
`share_credentials`	`bool`	`true`	Share stored credentials with delegated agents.
`share_summary`	`bool`	`true`	Pass conversation summary to delegated agents for context.
`default_mode`	`string`	`"subprocess"`	Default execution mode: `subprocess` (isolated) or `in_process` (faster, shared memory).
`default_timeout`	`int`	`300`	Default timeout in seconds for delegated agent tasks.

memory

Controls the long-term entity-graph memory system.

Field	Type	Default	Description
`enabled`	`bool`	`true`	Enable entity-graph memory across sessions.
`extraction_threshold`	`int`	`5`	Extract memories every N signal-flagged exchanges.
`retrieval_limit`	`int`	`10`	Maximum memories injected into context per turn.
`auto_extract`	`bool`	`true`	Automatically extract memories from conversation.

sandbox

Container sandbox for isolated tool execution. Requires podman or docker.

Field	Type	Default	Description
`enabled`	`bool`	`false`	Run tools inside a container.
`image`	`string`	`"python:3.12-slim"`	Container image to use.
`runtime`	`string`	`"auto"`	Container runtime: `auto`, `podman`, or `docker`.
`network`	`string`	`"bridge"`	Container network mode: `none`, `host`, or `bridge`.
`memory_limit`	`string`	`"2g"`	Container memory limit (e.g., `2g`, `512m`).
`allow_shell`	`bool`	`true`	Allow shell/exec tool execution inside sandbox.
`setup_commands`	`list[string]`	`[]`	Commands to run inside container after creation.
`extra_mounts`	`list[MountConfig]`	`[]`	Additional bind mounts into the container.
`env`	`dict`	`{}`	Extra environment variables inside the container.

service

Integration with supyagent cloud for third-party tools (Gmail, Slack, GitHub, etc.). See Cloud Integrations for setup.

Field	Type	Default	Description
`enabled`	`bool`	`true`	Use service tools when connected. Auto-uses if an API key exists.
`url`	`string`	`"https://app.supyagent.com"`	Service base URL.

schedule

Daemon schedule settings. Only used when type: daemon. See Daemon Mode.

Field	Type	Default	Description
`interval`	`string`	`"5m"`	Poll interval. Supports `s` (seconds), `m` (minutes), `h` (hours).
`max_events_per_cycle`	`int`	`10`	Maximum inbox events to process per cycle (minimum: 1).
`prompt`	`string \| null`	`null`	Optional scheduled task to run each cycle even with no events.

Validation

When loading a config, supyagent performs two layers of validation:

Pydantic type checks -- enforces types, ranges, and required fields with clear error messages.
Semantic validation -- checks that the model provider is recognized by LiteLLM, delegate names reference existing agent files, and tool patterns are valid strings.

# See validation errors
supyagent chat badagent
# Error: Invalid configuration for agent 'badagent':
#   - model.provider is required (e.g., 'anthropic/claude-sonnet-4-5-20250929')
#   - system_prompt is required (multi-line string starting with '|' in YAML)

Minimal Config

The smallest valid configuration:

agents/minimal.yaml

name: minimal
model:
  provider: anthropic/claude-sonnet-4-5-20250929
system_prompt: |
  You are a helpful assistant.

Everything else uses sensible defaults.

Models -- Provider setup and fallback configuration
System Prompts -- Writing effective prompts
Tool Permissions -- Allow/deny patterns
Sessions -- Context management settings
Delegation -- Multi-agent delegation settings

Configuration Reference

On this page