agents

version	last_updated
1.0	2025-12-10

Agents Documentation

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:

1. Run Configuration - CLI usage and config files
2. Agent Configuration - Configure agent behavior and limits
3. Providers - Set up API credentials
4. Models - Understand the model catalog
5. 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

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

See Models Guide for details.

Adding a New Provider

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

See Providers Guide for details.

Related Documentation

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