Managing Dependencies

Add and manage Python dependencies for your agent

Adding Python Dependencies

Add Python packages using uv from your agent/ directory:

uv add requests

This updates pyproject.toml and installs the package in your local environment.

After adding dependencies with uv add, you can immediately test with sb0 run --prompt without rebuilding.

Common Dependencies

Here are some commonly used packages for agents:

uv add httpx           # Modern async HTTP client
uv add pydantic        # Data validation
uv add sqlalchemy      # Database ORM
uv add redis           # Redis client
uv add beautifulsoup4  # HTML parsing
uv add pandas          # Data analysis

Development Dependencies

Add development-only dependencies with the --dev flag:

uv add --dev pytest    # Testing framework
uv add --dev ruff      # Linter and formatter
uv add --dev mypy      # Type checking

These won’t be included in production builds.

The .sb0/wheels/ Directory

Your agent includes embedded sb0 packages in .sb0/wheels/:

• sb0-runner - Agent runtime and execution environment
• sb0-protocol - Communication protocol definitions

These are automatically installed during sb0 init and referenced in pyproject.toml:

[[tool.uv.index]]
name = "local-wheels"
url = ".sb0/wheels"
format = "flat"
explicit = true

[tool.uv.sources]
sb0-runner = { index = "local-wheels" }
sb0-protocol = { index = "local-wheels" }

Don’t modify the .sb0/wheels/ directory or remove these package references.

Local Testing vs Production

Understanding dependency workflows:

Local Testing

uv add requests               # Add dependency
sb0 run --prompt "test"       # Test immediately (no rebuild)

Dependencies are installed in .venv/ and available immediately for local testing.

Production Deployment

uv add requests               # Add dependency
sb0 build                     # Rebuild Docker image
sb0 push                      # Deploy to platform

For production, you must rebuild the Docker image to include new dependencies.

Dependency Versions

Specify version constraints in pyproject.toml:

[project]
dependencies = [
  "requests>=2.31.0",     # Minimum version
  "httpx~=0.25.0",        # Compatible version (~= means ~0.25.0)
  "pydantic==2.5.0",      # Exact version
]

Or use uv add with version specifiers:

uv add "requests>=2.31.0"
uv add "httpx~=0.25.0"
uv add "pydantic==2.5.0"

Viewing Dependencies

List all installed dependencies:

uv pip list

View dependency tree:

uv pip tree

Lockfile

uv creates a uv.lock file that pins exact versions for reproducible builds:

uv lock    # Regenerate lockfile

Commit uv.lock to version control to ensure consistent builds across environments.

Next Steps

• Learn about agent configuration
• Understand the agent handler