deepagents-deep-dive - GitLite

KO | EN

gitlite — search

#nextjs #cross-platform #data-science #proxy #redis #git #monitoring #developer-tools #tensorflow #typescript

deepagents-deep-dive

(★ 9)

A deep dive into advanced features of deep agents

File Explorer

ZIP Download

- researcher.py
- incidents.jsonl
- coffee-chart.png
- deep-agent-delegation.svg
- deep-agent-memory-regions.svg
- deep-agent-voice-flow.svg
- incident-eval-architecture.svg
- incident-eval-experiment.svg
- memory-middleware-flow-oncall.svg
- offloading-results.png
- summarization.png
- - notes.md
- AGENTS.md
- __init__.py
- charts.py
- incident_dataset.py
- pretty.py
- skills.py
- stats.py
- voice.py
.env.example
.gitignore
.python-version
deepagents-async.ipynb
deepagents-basics.ipynb
deepagents-evals-v2.ipynb
deepagents-evals.ipynb
deepagents-interpreters-ptc.ipynb
deepagents-memory-architecture.ipynb
deepagents-sandboxes.ipynb
deepagents-skills.ipynb
deepagents-voice.ipynb
langgraph.json
pyproject.toml
pyrightconfig.json
README.md
uv.lock

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A hands-on tour of [Deep Agents](https://github.com/langchain-ai/deepagents) built as a series of
runnable Jupyter notebooks. Each notebook is self-contained and most close with a recap, so you can
work straight through or jump to the topic you care about.

## Table of Contents

- [Setup](#setup)
  - [Prerequisites](#prerequisites)
  - [Install](#install)
  - [Environment variables](#environment-variables)
- [Notebooks](#notebooks)
  - [Basics](#basics)
  - [Evaluations](#evaluations)
  - [Skills and AGENTS.md](#skills-and-agentsmd)
  - [Memory architecture](#memory-architecture)
  - [Sandboxes](#sandboxes)
  - [Interpreters and programmatic tool calling](#interpreters-and-programmatic-tool-calling)
  - [Async subagents](#async-subagents)
  - [Voice](#voice)
- [Repository layout](#repository-layout)

## Setup

### Prerequisites

- Python 3.13 (see `.python-version`)
- [uv](https://docs.astral.sh/uv/) for dependency management
- `deepagents` >= 0.7 &mdash; task planning became opt-in in 0.7, and the notebooks are
  written against that behaviour

### Install

```bash
uv sync
uv run jupyter notebook
```

This starts the copy of Jupyter installed in the project's `.venv`, so the notebooks automatically
use the same environment as the project dependencies.

### Environment variables

Copy `.env.example` to `.env` and fill in the keys you need:

```bash
cp .env.example .env
```

Every notebook calls `load_dotenv(override=True)`, so `.env` wins over anything already exported in
your shell — edit it mid-session and the change takes effect on the next run.

| Variable | Needed by |
| --- | --- |
| `ANTHROPIC_API_KEY` | All notebooks |
| `LANGSMITH_API_KEY`, `LANGSMITH_TRACING`, `LANGSMITH_PROJECT`, `LANGSMITH_WORKSPACE_ID` | Tracing, evaluations, and the LangSmith sandbox backend |
| `TAVILY_API_KEY` | Web search in the async and voice notebooks |
| `GEMINI_API_KEY` or `GOOGLE_API_KEY` | Voice |
| `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `S3_BUCKET`, `S3_REGION` | The S3 mount section of Sandboxes |
| `OPENAI_API_KEY` | The OpenAI half of the model comparison in Evaluations |

> **Note:** The AWS/S3 variables are only needed for the mount section of the Sandboxes notebook.
> Every other notebook runs without them.

## Notebooks

Suggested order — later notebooks assume the vocabulary of earlier ones.

| # | Notebook | Topic |
| --- | --- | --- |
| 1 | `deepagents-basics.ipynb` | Core anatomy of a deep agent |
| 2 | `deepagents-evals-v2.ipynb` | Offline evaluation with LangSmith |
| 3 | `deepagents-skills.ipynb` | Skills and `AGENTS.md` memory |
| 4 | `deepagents-memory-architecture.ipynb` | Routing memory by scope and owner |
| 5 | `deepagents-sandboxes.ipynb` | Executing real code safely |
| 6 | `deepagents-interpreters-ptc.ipynb` | Programmatic tool calling |
| 7 | `deepagents-async.ipynb` | Background subagents |
| 8 | `deepagents-voice.ipynb` | A realtime voice front end |

### Basics

`deepagents-basics.ipynb`

A deep agent is a regular agent plus subagents, a filesystem, and — since 0.7, only if you ask
for it — a TODO list. Opens on that opt-in: the same agent before and after
`middleware=[TodoListMiddleware()]`, then a plan that actually moves ☐ → ▶ → ☑. Goes on to task
delegation, dictionary vs. compiled subagents, and the backend family — default (thread-scoped
state), `StoreBackend`, `FilesystemBackend`, and `CompositeBackend` — closing on context isolation
and context-management techniques.

### Evaluations

`deepagents-evals-v2.ipynb`

An incident-response supervisor delegates evidence gathering to an investigator subagent. The
investigator writes `/investigation.json`; the supervisor applies response policy and issues a
brief. A code evaluator grades the report, and an LLM judge grades the response. Six paired
incidents run against two model configurations.

### Skills and AGENTS.md

`deepagents-skills.ipynb`

Two opposite ways to give an agent knowledge. **Skills** are folders loaded only when a task matches,
via three levels of progressive disclosure: frontmatter at startup, the `SKILL.md` body on
activation, and `references/` only when the body points at them. **`AGENTS.md`** is memory injected
into every prompt. Built around an on-call assistant that delegates alerts to a triage specialist,
and demonstrates that subagents inherit neither skills nor memory — plus a writable `notes.md` whose
correction survives across threads, processes, and agent objects.

### Memory architecture

`deepagents-memory-architecture.ipynb`

Where Skills covers *what* to give an agent, this covers *where it lives and who owns it*.
One agent, one filesystem, three memory types routed by `CompositeBackend` to different
backends: per-user preferences, an org-wide policy file the agent is blocked from editing,
and per-user skills — with anything unmatched falling through to thread-scoped state. Each
property is proved against the store rather than the model's say-so: Alice and Bob never
see each other's memory, a write to `/policies/` is refused by the harness even when the
prompt does not forbid it, and a preference mentioned in passing survives into a brand-new
thread.

> Note the routing gotcha it documents: `CompositeBackend` **strips** the route prefix
> before handing the key to the backend, so `/memories/preferences.md` is stored under
> `/preferences.md`. Seed the full path and reads miss silently.

### Sandboxes

`deepagents-sandboxes.ipynb`

A sandbox backend gives the agent a real Linux box — filesystem, shell, package installs — behind a
boundary that protects the host, and adds the `execute` tool. A data-analysis agent cleans a
deliberately messy CSV and renders a chart by *actually running code*. The second half mounts an S3
bucket into the sandbox with `mount_config`, using a read-only input prefix and a writable output
prefix, and shows the write-back path: an ordinary shell redirect inside the box lands an object in
S3 with no `put_object` call.

### Interpreters and programmatic tool calling

`deepagents-interpreters-ptc.ipynb`

The same task solved twice — once with direct tool calling, once with programmatic tool calling —
then compared side by side on token count and tool-call volume, with the code the agent wrote shown
in full.

### Async subagents

`deepagents-async.ipynb`

Subagents that run in the background on an Agent Protocol server. Launching returns a task id
immediately so the supervisor stays responsive; five tools manage the lifecycle. Uses the graph in
`async_agents/researcher.py`, served via `langgraph.json`:

```bash
uv run langgraph dev
```

### Voice

`deepagents-voice.ipynb`

A realtime voice layer over a deep agent, driven straight from the `google-genai` Live API with no
web stack. The deep agent is exposed as a single `deep_research` tool that the voice model calls and
narrates. Covers audio plumbing, the realtime loop, and server VAD with barge-in. This is the other
notebook that opts into `TodoListMiddleware`, for the reason the docs recommend it: the activity
panel is a progress UI streaming the coordinator's `todos` straight off agent state.

> **Note:** This notebook needs a working microphone and speaker, and installs `sounddevice`.

## Repository layout

```
├── deepagents-*.ipynb      # the deep-dive notebooks
├── async_agents/           # graph served to the async notebook
│   └── researcher.py
├── data/                   # dataset rows kept out of the notebooks
│   └── incidents.jsonl       # six paired incident examples and tool fixtures
├── oncall_home/            # fixtures for the skills notebook
│   ├── AGENTS.md           #   always-loaded conventions
│   ├── memory/notes.md     #   writable learned preferences
│   └── skills/             #   per-agent skill sources
├── util/                   # notebook helpers (not part of the lesson)
│   ├── pretty.py           #   activity timelines, exchanges, file/tree/store display
│   ├── skills.py           #   skill and memory catalogs
│   ├── stats.py            #   token and tool-call stats
│   ├── charts.py           #   comparison bars
│   ├── voice.py            #   mic and speaker streams
│   └── incident_dataset.py #   validates the evals dataset
├── images/                 # rendered notebook artifacts
└── langgraph.json          # graph config for `langgraph dev`
```

`util/` keeps rendering and dataset checks out of the notebook cells.