# Claude Managed Agents cookbooks

Claude Managed Agents is Anthropic's hosted runtime for stateful, tool-using
agents. You define an agent and a sandboxed environment once, then run
them in sessions that persist files, tool state, and conversation
across turns. These tutorials show it end to end.

## MongoDB on Managed Agents

Want to give an agent a real database — for retrieval, graph traversal, and as
its system of record?
**[`CMA_with_mongodb_atlas.ipynb`](CMA_with_mongodb_atlas.ipynb)**
is the consolidated cookbook: three ways to connect MongoDB to a CMA agent (and
where the credential lives on each path), the four retrieval patterns
(vector / full-text / hybrid / graph) as liftable building blocks, and an
end-to-end human-in-the-loop fraud-review agent with Atlas as the system of
record and audit backbone.

## Applied cookbooks

- **[data_analyst_agent.ipynb](data_analyst_agent.ipynb)** builds an
  analyst that turns a CSV into a narrative HTML report using pandas
  and plotly. You'll configure an environment and agent, mount a
  dataset, stream the run, and retrieve the generated artifacts.
- **[slack_data_bot.ipynb](slack_data_bot.ipynb)** wraps that agent in
  a Slack bot. Mention it with a CSV to get the report in-thread;
  replies continue the same session.
- **[sre_incident_responder.ipynb](sre_incident_responder.ipynb)** puts
  Managed Agents on the on-call path: a pager alert starts a session,
  the agent investigates and opens a PR, then pauses for human
  approval before merging. You'll wire the alert webhook, attach a
  Skill and custom tools, and review the full run in the Console.

## Guided tutorials

End-to-end tutorials that teach the Managed Agents API surface
through realistic workflows. There's no strict reading order,
but `CMA_iterate_fix_failing_tests.ipynb` is a good entry point,
it introduces every API shape the others build on.

| Notebook | What it teaches |
| --- | --- |
| [`CMA_iterate_fix_failing_tests.ipynb`](CMA_iterate_fix_failing_tests.ipynb) | Do → observe → fix loop on a failing test suite. The entry-point notebook: introduces agent / environment / session, file mounts, and the streaming event loop through the lens of getting a buggy package to green. |
| [`CMA_orchestrate_issue_to_pr.ipynb`](CMA_orchestrate_issue_to_pr.ipynb) | Issue → fix → PR → CI → review → merge through a mock `gh` CLI. Multi-turn steering, mid-chain recovery from a CI failure and a review comment. Sidebar shows how to swap the file mount for a `github_repository` resource against a real repo. |
| [`CMA_explore_unfamiliar_codebase.ipynb`](CMA_explore_unfamiliar_codebase.ipynb) | Grounding in an unfamiliar codebase, with a planted stale-doc trap. Sidebar shows how to add resources to a running session via `sessions.resources.add`. |
| [`CMA_gate_human_in_the_loop.ipynb`](CMA_gate_human_in_the_loop.ipynb) | Human-in-the-loop expense approval via custom-tool `decide()` / `escalate()`. Covers the custom-tool round-trip pattern, the `requires_action` idle bounce, and parallel-tool-call dedupe. |
| [`CMA_with_mongodb_atlas.ipynb`](CMA_with_mongodb_atlas.ipynb) | **MongoDB Atlas** end to end: three connection paths (host-side custom tool, self-hosted sandbox, self-hosted MCP), the four retrieval patterns (vector / full-text / RRF hybrid / `$graphLookup`), and a human-in-the-loop fraud-review agent that records decisions and an append-only audit trail in the same cluster. Pauses on risky cases via the `requires_action` gate; shows an auto-resolving gate for CI and the webhook handoff for production. |
| [`CMA_prompt_versioning_and_rollback.ipynb`](CMA_prompt_versioning_and_rollback.ipynb) | Server-side prompt versioning: create v1, evaluate against a labelled test set, ship v2, detect a regression, roll back by pinning sessions to version 1. Covers `agents.update`, version pinning on `sessions.create`, and where the review gate moves when prompts are not code. |
| [`CMA_operate_in_production.ipynb`](CMA_operate_in_production.ipynb) | Production setup: MCP toolsets, vaults for per-end-user credentials, the `session.status_idled` webhook pattern for HITL without long-lived connections, and the resource lifecycle CRUD verbs. |
| [`CMA_remember_user_preferences.ipynb`](CMA_remember_user_preferences.ipynb) | Memory stores: a shopping agent that learns a customer's preferences in one session and recalls them in the next. Covers `memory_stores.create`, the `resources` attachment with per-attachment `instructions`, inspecting and seeding memories from your own application, and combining a per-customer read-write store with a brand-wide read-only store. |
| [`CMA_coordinate_specialist_team.ipynb`](CMA_coordinate_specialist_team.ipynb) | Heterogeneous team via the `multiagent` coordinator config: a coordinator runs three specialists (web-search researcher, file-reading librarian, rules-based pricer) with scoped toolsets to assemble a sales proposal. Covers the `multiagent` field, the `thread_created` / `thread_message_received` event types, and why per-role tool scoping matters. |
| [`CMA_watch_subagents_live.ipynb`](CMA_watch_subagents_live.ipynb) | A curriculum-planning team you can watch in real time. Covers per-thread `event_deltas` so subagent text streams live, `initial_events` on session create, per-agent model `effort` as a cost lever, and versionless `agents.update`. Builds on the coordinate-specialist-team shapes. |
| [`CMA_plan_big_execute_small.ipynb`](CMA_plan_big_execute_small.ipynb) | Coordinator-pattern economics: a frontier coordinator delegates the token-heavy web reading to cheap parallel workers, measured against a rigor-matched solo-frontier control with per-thread cost metering. |
| [`CMA_verify_with_outcome_grader.ipynb`](CMA_verify_with_outcome_grader.ipynb) | Build a grade-and-revise loop with Outcomes: a writer drafts a cited research brief, a stateless grader fetches every URL and checks every quote against a rubric, and feedback drives revisions until the brief passes. Covers `user.define_outcome`, the `span.outcome_evaluation_*` events, and how to write a rubric the grader can act on. |

The streaming event loop is walked through line by line in the
iterate notebook and then factored into
`utilities.stream_until_end_turn` so the other notebooks can
import it instead of repeating the `match ev.type:` block. The
gate notebook and the MongoDB cookbook are the exceptions: they keep
the loop inline because custom-tool agents need to handle
`requires_action` idle bounces in addition to `end_turn`, which
the helper doesn't cover.

## Getting started

Set `ANTHROPIC_API_KEY` in your environment, then open
`data_analyst_agent.ipynb` in Jupyter and run the cells top to
bottom. Each notebook installs its own dependencies and prompts
for any credentials it needs. The orchestrate-to-PR sidebar in
`CMA_orchestrate_issue_to_pr.ipynb` and the vault-backed MCP
example in `CMA_operate_in_production.ipynb` additionally need
`GITHUB_TOKEN` set (a fine-grained PAT with public-repo read is
enough). The MongoDB cookbook in
`CMA_with_mongodb_atlas.ipynb` additionally
needs `MONGO_URI` set to an Atlas SRV connection string (an M0
free cluster works); a provider key — `MDB_ATLAS_API_KEY` or
`VOYAGE_API_KEY` — is optional and only enables the
live-embedding and reranker paths.

All cookbook fixture data — input CSVs and supporting assets for
the applied cookbooks, plus the planted-trap fixtures the guided
tutorials read from — lives under `example_data/`. See
[`example_data/OVERVIEW.md`](example_data/OVERVIEW.md) for the
directory map.