Environment Setup

Before you can build agentic systems with Deep Agents, you need to prepare your development environment. This guide walks you through installing Python, the uv package manager, and the Deep Agents library.

Check your Python version

Check what Python version you currently have:
```
python3 --version
```
Sample output
```
Python 3.12.4
```
Don’t worry if your system Python is older than 3.13 — in the next section you’ll install uv, which can download and manage Python 3.13 for your project automatically without touching your system installation.

Install uv

uv is a fast Python package and project manager from Astral. It handles dependency management, virtual environments, and — crucially for this workshop — Python version management per project, so you never need to change your system Python.

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Sample output

downloading uv 0.6.14 (aarch64-apple-darwin)
installing to /Users/you/.local/bin
  uv
  uvx
everything's installed!

Verify the installation:
```
uv --version
```
Sample output
```
uv 0.6.14
```
You should see version 0.6.x or later. If you have an older version, re-run the install script above to upgrade.

Create your workshop project

Initialize a new project pinned to Python 3.13. Even if your system Python is an older version, uv will automatically download and manage Python 3.13 for this project.

Create the project and add Deep Agents:

uv init --python 3.13 deep-agents-workshop
cd deep-agents-workshop
uv add deepagents

Sample output

Initialized project `deep-agents-workshop` at `/home/you/deep-agents-workshop`
Using CPython 3.13.2
Creating virtual environment at: .venv
Resolved 12 packages in 3.21s
...
Installed 12 packages in 156ms
 + deepagents==0.2.1
 + langchain-core==0.3.51
 + langgraph==0.4.1

This creates an isolated project directory with its own pyproject.toml, .python-version file (pinned to 3.13), and virtual environment. Your system Python is untouched — uv downloads and caches the correct Python version automatically.

Verify which Python the project is using:
```
uv run python --version
```
Sample output
```
Python 3.13.2
```
This should show Python 3.13.x regardless of what python3 --version reports system-wide.

This per-project Python management is one of the key reasons we use uv throughout this workshop. Each project gets exactly the Python version it needs, and you can have multiple projects using different versions side by side.

Set your API key

Deep Agents uses Claude as its reasoning engine. You’ll need an Anthropic API key to run the examples in this workshop.

Set your API key as an environment variable:
```
export ANTHROPIC_API_KEY="your-key-here"
```
You can obtain an API key from console.anthropic.com. Navigate to "API Keys" in your account settings and create a new key.

You’ll need this API key set for all modules in this workshop. Consider adding it to your shell profile (~/.bashrc, ~/.zshrc, etc.) to persist it across sessions.

Validate your setup

Create a validation script:

cat > validate_setup.py << 'EOF'
from deepagents import create_deep_agent

agent = create_deep_agent()
print("Deep Agents installed successfully!")
print(f"Agent type: {type(agent).__name__}")
EOF

Run the validation script:
```
uv run validate_setup.py
```
Expected output
```
Deep Agents installed successfully!
Agent type: CompiledStateGraph
```
If you see this output, your environment is ready for the workshop.

Create the workshop utility

Throughout this workshop, scripts need to print agent responses. Different model providers return content in different formats — Anthropic returns a plain string, some OpenAI-compatible endpoints return a list of content blocks. This small utility handles both:

Create utils.py:

cat > utils.py << 'EOF'
def agent_response(result):
    """Extract the text content from an agent result.

    Handles both string content (Anthropic, OpenAI) and list-of-blocks
    content (some vLLM/LiteLLM endpoints).
    """
    content = result["messages"][-1].content
    if isinstance(content, list):
        return "\n".join(
            b["text"] for b in content
            if isinstance(b, dict) and b.get("type") == "text"
        )
    return content


def delegation_trace(result, subagents=None):
    """Show the sequence of subagent delegations from an agent result.

    Prints each task() tool call: which subagent was called, its model
    (if subagents config is provided), and what it was asked to do.

    Args:
        result: The agent invocation result dict.
        subagents: Optional list of subagent dicts — if provided,
                   the model for each subagent is shown in the trace.
    """
    # Build name -> model lookup if subagents provided
    models = {}
    if subagents:
        for sa in subagents:
            models[sa["name"]] = sa.get("model", "inherited")

    steps = []
    for msg in result["messages"]:
        if hasattr(msg, 'tool_calls') and msg.tool_calls:
            for tc in msg.tool_calls:
                if tc['name'] == 'task':
                    args = tc['args']
                    agent_name = args.get('subagent_type', 'unknown')
                    desc = args.get('description', '')[:80]
                    steps.append((agent_name, desc))

    if not steps:
        return "No delegations found."

    lines = ["", "=== Delegation Trace ==="]
    for i, (agent_name, desc) in enumerate(steps, 1):
        model_info = f" ({models[agent_name]})" if agent_name in models else ""
        lines.append(f"  Step {i}: {agent_name}{model_info}")
        lines.append(f"          {desc}...")
    lines.append(f"  Total: {len(steps)} delegation(s)")
    lines.append("")
    return "\n".join(lines)
EOF

You’ll use these in scripts with a simple import:

from utils import agent_response, delegation_trace

print(delegation_trace(result))  # Shows which subagents were called
print(agent_response(result))    # Shows the final response

Install the Deep Agents CLI

Install the CLI:

curl -LsSf https://raw.githubusercontent.com/langchain-ai/deepagents/main/libs/cli/scripts/install.sh | bash

Sample output

downloading deepagents-cli
installing to /Users/you/.local/bin
  deepagents
installation complete!

Verify the installation:

deepagents --help

Sample output (your results may vary)

usage: deepagents [-r [ID]] [-a NAME] [-M MODEL] [-m TEXT] [-q]
                  [--no-stream] [--json] [-y] [-v] [-h]
                  {help,list,reset,skills,threads} ...

Deep Agents CLI - The batteries-included agent harness

You should see the CLI’s help output with available options and subcommands.

Optional: Local Showroom experience

If you prefer a full split-pane UI for this workshop (code editor + terminal + instructions), you can run the local Showroom environment:

Start the local Showroom:
```
./localroom.sh start
```
This launches a browser-based interface at http://localhost:8080 that mirrors the online Showroom experience.

Troubleshooting

Python version too old

If uv run python --version inside your project still shows an older version, ensure you created the project with the --python 3.13 flag. You can fix an existing project:

Pin the Python version and resync:
```
uv python pin 3.13
uv sync
```
This tells uv to download Python 3.13 and recreate the virtual environment. Your system Python remains unchanged.

API key not set

If you see authentication errors when running examples, check your ANTHROPIC_API_KEY environment variable:

Verify the key is set:
```
echo $ANTHROPIC_API_KEY
```
If this prints an empty line, re-export your API key.

uv not on PATH

After installing uv, you may need to restart your terminal or manually add it to your PATH. The installer typically adds it to ~/.local/bin. Add this to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

Then restart your terminal or run source ~/.bashrc (or ~/.zshrc).