inspect_agents

Inspect‑AI–native, CLI‑first agents with typed state, tools, and rich traces. Ship agents in minutes, not days.

Quick Demo

Build Tests Coverage License: MIT PyPI Version PyPI Downloads Last Commit Docs

Quickstart (Offline, 60 seconds)

Works with zero API keys and no local model server. New here? Follow these three steps, then see the docs Home.

Start Here

python scripts/quickstart_toy.py
# Expected: Completion: DONE

Next: Examples — Start Here →

Docs Home →

Why Inspect Agents?

Setting up practical LLM agents is slow: you fight glue code, logging, state, and tool orchestration. Inspect Agents removes the overhead with an Inspect-AI-native, CLI-first workflow: one command to run; typed state (todos/files); built-in tools; transcripts and traces by default. Ship in minutes, not days.

Key Features

Table of Contents

Installation

Prerequisites

# Set cache directory (avoids re-downloading in restricted environments)
export UV_CACHE_DIR=.uv-cache

# Install dependencies
uv sync

# Verify installation
uv run python -c "import inspect_agents; print('inspect_agents OK')"

Using pip/venv

# Create and activate virtual environment
python3.11 -m venv .venv
source .venv/bin/activate

# Install in editable mode
pip install -e .

# Verify installation
python -c "import inspect_agents; print('inspect_agents OK')"

Configure Environment Variables

Use the interactive configurator to generate .env files with sensible defaults:

uv run python env_templates/configure.py

This writes a .env at the repo root and examples/inspect/.env. You can also point runners to the file with --env-file or by exporting INSPECT_ENV_FILE=path/to/.env.

Usage

Scaffold a new agent

Generate a minimal agent module (and optional smoke test) in seconds.

# Create src/<pkg>/<name>.py and tests/<pkg>/test_<name>.py
python scripts/scaffold_agent.py <name> \
  --package inspect_agents \
  --path . \
  --include-test      # default; use --no-test to skip

# Example
python scripts/scaffold_agent.py my_helper

# Run the generated smoke test (offline)
CI=1 NO_NETWORK=1 PYTHONPATH=src:external/inspect_ai uv run pytest -q -k my_helper

Notes

CLI (Inspect)

Basic evaluation with built-in tools:

inspect eval examples/inspect/prompt_task.py -T prompt="Write a concise overview of LangGraph"

Provider quick switch (pick one):

# LM Studio (OpenAI-compatible local server)
export DEEPAGENTS_MODEL_PROVIDER=lm-studio
export LM_STUDIO_BASE_URL="http://127.0.0.1:1234/v1"
export LM_STUDIO_MODEL_NAME="local-model"
inspect eval examples/inspect/prompt_task.py -T prompt="..."

With optional tools:

# Enable structured thinking
INSPECT_ENABLE_THINK=1 inspect eval examples/inspect/prompt_task.py -T prompt="..."

# Enable web search (requires API key)
INSPECT_ENABLE_WEB_SEARCH=1 TAVILY_API_KEY=... inspect eval examples/inspect/prompt_task.py -T prompt="..."

Policy note: Enabling INSPECT_ENABLE_EXEC=1 exposes only single‑shot bash() and python() tools. The stateful bash_session tool is never surfaced by this repo’s standard_tools(); it is reserved for internal filesystem‑sandbox operations (e.g., sed, ls, wc -c).

For prompts with special characters, use single quotes:

uv run inspect eval examples/inspect/prompt_task.py \
  -T 'prompt="Identify research about: Cultural traditions and scientific processes"'

Viewing Logs (Inspect View)

Start the Inspect log viewer to explore evaluation logs in your browser:

# Default: uses ./logs and serves on http://127.0.0.1:7575
uv run inspect view

# Specify an alternate directory/port
uv run inspect view --log-dir ./experiment-logs --port 6565

See docs: docs/cli/inspect_view.md

Provider Examples

# LM Studio
uv run python examples/inspect/run.py --provider lm-studio --model local-model "Your prompt"

# Ollama
uv run python examples/inspect/run.py --provider ollama --model llama3.1:8b "Your prompt"

# OpenAI (requires OPENAI_API_KEY)
uv run python examples/inspect/run.py --provider openai --model gpt-4o-mini "Your prompt"

Advanced Usage

Sub-agents Configuration

Define sub-agents in YAML and load programmatically. You can also set root-level runtime limits:

# inspect.yaml
supervisor:
  prompt: |
    You are a helpful supervisor. Use sub-agents when appropriate.
subagents:
  - name: researcher
    description: Focused web researcher that plans and cites sources
    prompt: Research the user's query. Plan, browse, then draft findings.
    mode: handoff
    tools: [web_search, write_todos, read_file, write_file]
    context_scope: scoped
    include_state_summary: true
limits:
  # Minimal schema: {type: time|message|token, value: <number>}
  - type: time
    value: 60    # seconds
  - type: message
    value: 8     # total messages
  # - type: token
  #   value: 10000  # optional total tokens

from inspect_agents.config import load_and_build
from inspect_agents.run import run_agent
import asyncio, yaml

cfg = yaml.safe_load(open("inspect.yaml"))
agent, tools, approvals, limits = load_and_build(cfg)
result = asyncio.run(run_agent(agent, "start", approval=approvals, limits=limits))
print(getattr(result.output, "completion", "[no completion]"))

Architecture

flowchart LR
    SP[[System Prompt / Config]] --> S[Supervisor]
    MR[Model Resolver] --> S
    S --> L[Logs / Traces]
    S -->|tool call| AP[Approvals & Policies]
    AP --> ST[Stateless Tools]
    AP --> SS[Stateful Tools]
    ST -.-> S
    SS -.-> S

    subgraph "FS Path Modes (MODE=store|sandbox)"
      direction LR
      FST[FS Tools] -->|"store (default)"|VFS["(VFS)"]
      FST -->|sandbox| SBX[["Sandboxed Editor (no delete)"]]
      SBX --> HFS[(Host FS)]
    end
    AP --> FST
    VFS -.-> S
    SBX -.-> S
    HFS -.-> S

    S -->|handoff| CG[Context Gate]
    CG <-->|iterate| SA[Sub-Agents]
    SA -.-> S

Fallback: docs/diagrams/architecture_overview.png

Documentation

Docs (MkDocs)

Preview the documentation site locally with MkDocs.

Using uv (recommended):

uv sync --extra docs
uv run mkdocs serve

Using pip/venv:

pip install -e '.[docs]'
mkdocs serve

Then open http://127.0.0.1:8000. Sources live under docs/ and the site is configured via mkdocs.yml.

Project Status

Coming Soon

Contributing

See CONTRIBUTING.md for guidelines.

Quick Setup for Contributors

# Install with dev dependencies
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev,testing,utilities]'

# Run tests (ensure local Inspect-AI src is visible)
export PYTHONPATH=src:external/inspect_ai/src
pytest -q tests/unit/inspect_agents

# Lint and format
ruff check && ruff format

# Explore testing guides (markers, examples, CI surfacing)
echo "See tests/README.md; locally opt-in to CI-style guide links: export DEEPAGENTS_SHOW_TEST_GUIDES=1"

Support

License & Acknowledgments

This site is open source. Improve this page.