> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sb0.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Configuration

> Configure your agent environment with agent.config.yaml

## Configuration File

Configure your agent environment with `agent.config.yaml`:

```yaml theme={null}
version: "0.1"
image: "my-agent:latest"

build:
  python_version: "3.12"
  python_project: "pyproject.toml"
  system_packages: [] # Additional system dependencies (e.g., "git")

runtime:
  handler: "handle_query:Handler" # Python module and class
```

## Configuration Options

### Version

```yaml theme={null}
version: "0.1"
```

The configuration schema version. Always use `"0.1"` for now.

### Image

```yaml theme={null}
image: "my-agent:latest"
```

The Docker image name and tag for your agent.

### Build Configuration

```yaml theme={null}
build:
  python_version: "3.12"
  python_project: "pyproject.toml"
  system_packages: []
```

* **`python_version`** - Python version to use (3.12 or higher recommended)
* **`python_project`** - Path to your pyproject.toml file
* **`system_packages`** - List of system packages to install (e.g., `git`, `ffmpeg`, `imagemagick`)

### Runtime Configuration

```yaml theme={null}
runtime:
  handler: "handle_query:Handler"
```

* **`handler`** - Python module and class for your handler (format: `module:ClassName`)

## Common System Packages

If your agent needs additional system dependencies, add them to `system_packages`:

```yaml theme={null}
build:
  python_version: "3.12"
  python_project: "pyproject.toml"
  system_packages:
    - git           # Version control operations
    - ffmpeg        # Audio/video processing
    - imagemagick   # Image manipulation
    - curl          # HTTP requests
    - postgresql    # Database client
```

## When to Rebuild

You need to rebuild with `sb0 build` when you change:

* **`system_packages`** - Adding or removing system dependencies
* **`python_version`** - Changing Python version
* **`handler`** - Changing handler module or class name
* **`image`** - Changing Docker image name/tag

You do NOT need to rebuild when:

* Adding Python dependencies with `uv add` (for local testing with `sb0 run`)
* Editing handler code in `handle_query.py`

<Tip>
  Use `sb0 run --prompt` for rapid iteration without rebuilding. Only rebuild when ready to deploy with `sb0 push`.
</Tip>

## Next Steps

* Learn how to [add Python dependencies](/v0-docs/agents/dependencies)
* Understand the [agent handler structure](/v0-docs/agents/handler)