Agent Configuration Guide

Agent configurations define the parameters for running different agent types. All configurations extend AgentConfigBase and are stored as YAML files in configs/agents/.

Quick Start

Create a minimal agent configuration:

# configs/agents/my-agent.yaml
type: claude_code
version: 2.0.51
cost_limits:
  cost_limit: 20
  step_limit: 100
  net_cost_limit: 0

Use it:

slop-code run --agent configs/agents/my-agent.yaml --model anthropic/sonnet-4.5

AgentConfigBase Schema

All agent configurations inherit from AgentConfigBase:

Required Fields

Field	Type	Description
type	string	Agent type identifier (e.g., claude_code, codex, mini_swe)
cost_limits	AgentCostLimits	Cost and step limits for execution

Optional Fields

Field	Type	Default	Description
docker_template	Path	None	Path to Jinja2 Docker template for agent setup

Validation

By default, AgentConfigBase uses strict validation (extra="forbid"), rejecting any unrecognized fields. Some agents (MiniSWE, OpenCode) override this to allow flexible configuration.

Cost Limits

The AgentCostLimits model controls execution constraints:

cost_limits:
  step_limit: 100       # Max steps per checkpoint (0 = no limit)
  cost_limit: 20.0      # Max cost per checkpoint in dollars
  net_cost_limit: 50.0  # Max total cost across all checkpoints

Fields

Field	Type	Default	Description
step_limit	int	0	Maximum steps per checkpoint (0 = unlimited)
cost_limit	float	required	Maximum cost per checkpoint in dollars
net_cost_limit	float	required	Maximum cumulative cost including prior checkpoints

Limit Checking

Limits are checked via is_above_limits(usage, prior_cost):

1. Step limit: usage.steps >= step_limit (if step_limit > 0)
2. Cost limit: usage.cost >= cost_limit (if cost_limit > 0)
3. Net cost limit: usage.cost + prior_cost >= net_cost_limit (if net_cost_limit > 0)

Configuration Registry

Agent configurations are automatically registered when their classes are defined.

Auto-Registration

Subclasses register via __init_subclass__:

class MyAgentConfig(AgentConfigBase, agent_type="my_agent", register=True):
    type: Literal["my_agent"] = "my_agent"
    # ... additional fields

Manual Registration

Use register_agent_config() for explicit registration:

from slop_code.agent_runner.registry import register_agent_config

register_agent_config("my_agent", MyAgentConfig)

Building Configs from Data

Use build_agent_config() to create config instances from dictionaries:

from slop_code.agent_runner.registry import build_agent_config

config = build_agent_config({
    "type": "claude_code",
    "version": "2.0.51",
    "cost_limits": {"cost_limit": 20, "net_cost_limit": 0}
})

Configuration Loading

Configs are loaded from YAML files via load_agent_config():

from slop_code.entrypoints.utils import load_agent_config

config = load_agent_config(Path("configs/agents/claude_code-2.0.51.yaml"))

Loading Process

1. Check file exists (raises FileNotFoundError if not)
2. Parse YAML with yaml.safe_load()
3. Validate YAML is a dict (raises ValueError if not)
4. Call build_agent_config() to instantiate the correct config class
5. Return validated config instance

Configuration Merging

When creating agents, settings merge from multiple sources:

Priority Order (highest to lowest)

1. CLI overrides - thinking_preset, thinking_max_tokens, image
2. Config file - YAML agent configuration values
3. Model catalog defaults - agent_specific settings from model definition

Example

# From model catalog (lowest priority)
agent_specific:
  claude_code:
    base_url: "https://default.api/v1"
    env_overrides:
      DEFAULT_VAR: "value"

# From agent config (medium priority)
env:
  MY_VAR: "override"

# From CLI (highest priority)
thinking_preset: "high"

Result: base_url from model, MY_VAR from config overrides DEFAULT_VAR, and thinking preset from CLI.

Docker Templates

Agents can define custom Docker templates for their execution environment.

Template Usage

Templates are Jinja2 files that render Dockerfiles:

FROM {{ base_image }}

# Install agent dependencies
RUN npm install -g @anthropic/claude-code@{{ version }}

USER 1000:1000
WORKDIR /workspace

get_docker_file() Method

def get_docker_file(self, base_image: str) -> str | None:
    """Render Docker template with base_image variable."""
    if self.docker_template is None:
        return None
    template = self.docker_template.read_text()
    return Template(template).render(base_image=base_image)

get_image() Method

Generates image names from agent type and environment:

def get_image(self, env_name: str) -> str:
    return f"{self.type}-{env_name}"

Supported Agent Types

Each agent type has its own configuration class with specific fields:

Agent Type	Config Class	Documentation
claude_code	ClaudeCodeConfig	Claude Code
codex	CodexConfig	Codex
mini_swe	MiniSWEAgentConfig	MiniSWE
opencode	OpenCodeAgentConfig	OpenCode
gemini	GeminiConfig	Gemini
openhands	OpenHandsConfig	OpenHands
pi	PiConfig	PI CLI agent

PI Agent

PI follows the same CLI-agent pattern as Codex/Gemini.

type: pi
binary: pi
version: 0.45.7
timeout: 7200
extra_args: []
env: {}
provider: null      # Optional PI provider override
thinking: null      # off|minimal|low|medium|high|xhigh
cost_limits:
  cost_limit: 0
  step_limit: 0
  net_cost_limit: 0

Notes:

• PI is always executed with --print --mode json --no-session for deterministic benchmark runs.
• provider is optional; by default SCB resolves a provider from the selected credential.
• codex_auth is converted to temporary PI openai-codex auth (PI_CODING_AGENT_DIR), never written into the user's real ~/.pi.
• Top-level SCB thinking presets map where compatible (low|medium|high|xhigh, plus none|disabled -> off).

Example runs:

uv run slop-code run \
  --agent configs/agents/pi.yaml \
  --model openai/gpt-5.2-codex \
  --problem <problem>

uv run slop-code run \
  --agent configs/agents/pi.yaml \
  --model codex_auth/gpt-5.2-codex \
  --problem <problem>

API Reference

AgentConfigBase

class AgentConfigBase(BaseModel):
    model_config = ConfigDict(extra="forbid")

    type: str = Field(frozen=True)
    cost_limits: AgentCostLimits
    docker_template: Path | None = None
    agent_type: ClassVar[str | None] = None

    def get_image(self, env_name: str) -> str:
        """Generate image name from agent type and environment."""

    def get_docker_file(self, base_image: str) -> str | None:
        """Render Docker template with base image."""

AgentCostLimits

class AgentCostLimits(BaseModel):
    step_limit: int = 0
    cost_limit: float
    net_cost_limit: float

    def is_above_limits(
        self, usage: UsageTracker, prior_cost: float | None
    ) -> bool:
        """Check if usage exceeds any defined limits."""

Registry Functions

def register_agent_config(agent_type: str, config_cls: type[AgentConfigBase]) -> None:
    """Register a config class for the given agent type."""

def get_agent_config_cls(agent_type: str) -> type[AgentConfigBase]:
    """Get the registered config class for an agent type."""

def available_agent_types() -> tuple[str, ...]:
    """List all registered agent type names."""

def build_agent_config(data: dict[str, Any]) -> AgentConfigBase:
    """Create config instance from dictionary data."""

Troubleshooting

Unknown Agent Type

ValueError: Agent configuration missing 'type'. Known types: claude_code, codex, ...

Solution: Ensure your config file includes a valid type field.

Type Mismatch

ValueError: Agent type mismatch. Expected 'claude_code', got 'my_agent'.

Solution: The type field must match the config class's expected agent type.

Extra Fields Not Allowed

ValidationError: Extra inputs are not permitted

Solution: Remove unrecognized fields from your config, or use an agent type that allows extra fields (MiniSWE, OpenCode).

Missing Cost Limits

ValidationError: Field required: cost_limits

Solution: Add cost_limits with at least cost_limit and net_cost_limit fields.

Missing or Empty Version Field

ValueError: Agent 'opencode' has a docker_template but missing or empty 'version'.

Cause: Agents that use custom Docker templates require a version field to install the correct CLI version.

Solution: Add the version field to your config:

type: opencode
version: "1.0.134"  # Add this field
cost_limits:
  cost_limit: 20
  net_cost_limit: 0

Note: Only agents with docker_template require the version field. MiniSWE and other agents that manage their own environments don't need it.

See Also

• Agent Class Guide - Agent implementation details
• Models Guide - Model definitions and agent-specific settings
• Run Configuration - CLI usage and run configs