Agents Documentation

December 17, 2025 · View on GitHub

This module covers agent configuration, model selection, provider setup, and credential management for running agents with slop-code run.

Quick Start

New to running agents? Start here:

Run Configuration - CLI usage and config files
Agent Configuration - Configure agent behavior and limits
Providers - Set up API credentials
Models - Understand the model catalog
Credentials - How API keys are resolved

Implementing a new agent? See:

Agent Class Guide - Agent lifecycle and implementation

Documentation Index

Document	Description
Run Configuration	CLI commands, config files, output paths
Agent Configuration	AgentConfigBase, cost limits, registry
Agent Class Guide	Agent lifecycle, abstract methods, implementation
Providers	Provider definitions and credential sources
Models	Model catalog, pricing, agent-specific settings
Credentials	Credential resolution and troubleshooting

Agent Types

Agent	Description
Claude Code	Anthropic's Claude Code CLI agent
Codex	OpenAI's Codex CLI agent
MiniSWE	Lightweight bash-based agent
OpenCode	OpenCode CLI agent
Gemini	Google's Gemini CLI agent
OpenHands	OpenHands framework agent

Core Concepts

Concept	Description	Configuration
Provider	Defines where credentials come from	`configs/providers.yaml`
Model	API endpoint, pricing, agent-specific settings	`configs/models/*.yaml`
Credential	Resolved API key or auth file	Environment variables or files
Agent Config	Agent type, cost limits, Docker template	`configs/agents/*.yaml`
Agent Class	Agent implementation and lifecycle	Source code

Configuration Flow

RunConfig (YAML or CLI)
    │
    ├─ model.provider ──► ProviderCatalog ──► ProviderDefinition
    │                                              │
    │                                              ▼
    │                                         APIKeyStore
    │                                              │
    ├─ model.name ─────► ModelCatalog ──────► ModelDefinition
    │                                              │
    │                                              ▼
    └─ agent ──────────► AgentConfigBase ◄── ProviderCredential
                               │
                               ▼
                            Agent.from_config()

Common Workflows

Running an Agent

# Minimal - uses defaults
slop-code run --model anthropic/sonnet-4.5 --problem file_backup

# With config file
slop-code run --config my_run.yaml --problem file_backup

# Override thinking budget
slop-code run --model anthropic/opus-4.5 thinking=high --problem file_backup

Setting Up Credentials

# Environment variable (most providers)
export ANTHROPIC_API_KEY=sk-...

# Or use a different env var
slop-code run --model anthropic/sonnet-4.5 --provider-api-key-env MY_KEY

Adding a New Model

Create configs/models/my-model.yaml
Specify provider, internal_name, pricing
Add agent_specific settings if needed

See Models Guide for details.

Adding a New Provider

Add entry to configs/providers.yaml
Set up the credential (env var or file)
Reference provider in model configs

See Providers Guide for details.

Environment Configuration - Execution environment setup
Problem Configuration - Problem and checkpoint config