/AGENTS.md` — loaded every session.
* **Project**: `.deepagents/AGENTS.md` in any git project root — loaded when the CLI is run from within that project.
Both files are appended to the system prompt at startup. Use `/remember` to explicitly prompt the agent to update its memory and skills from the current conversation.
The agent may also read its memory files when answering project-specific questions or when you reference past work or patterns.
The agent will update `AGENTS.md` as you provide information on how it should behave, feedback on its work, or instructions to remember something.
It will also update its memory if it identifies patterns or preferences from your interactions.
To add more structured project knowledge in additional memory files, add them in `.deepagents/` and reference them in the `AGENTS.md` file.
You must reference additional files in the `AGENTS.md` file for the agent to be aware of them.
The additional files will not be read on startup but the agent can reference and update them when needed.
**Global `AGENTS.md`** (`~/.deepagents/agent/AGENTS.md`)
* Your personality, style, and universal coding preferences
* General tone and communication style
* Universal coding preferences (formatting, type hints, etc.)
* Tool usage patterns that apply everywhere
* Workflows and methodologies that don't change per-project
**Project `AGENTS.md`** (`.deepagents/AGENTS.md` in project root)
* Project-specific context and conventions
* Project architecture and design patterns
* Coding conventions specific to this codebase
* Testing strategies and deployment processes
* Team guidelines and project structure
## Use skills
Skills are reusable agent capabilities that provide specialized workflows and domain knowledge.
You can use [skills](/oss/python/deepagents/skills) to provide your deep agent with new capabilities and expertise.
Deep agent skills follow the [Agent Skills standard](https://agentskills.io/).
Once you have added skills your deep agent will automatically make use of them and update them as you use the agent and provide it with additional information.
Use `/remember` to explicitly prompt the agent to update skills and memory from the current conversation.
1. Create a skill:
```bash theme={null}
# User skill (stored in ~/.deepagents//skills/)
deepagents skills create test-skill
# Project skill (stored in .deepagents/skills/)
deepagents skills create test-skill --project
```
This generates:
```plaintext theme={null}
skills/
└── test-skill
└── SKILL.md
```
2. Open the generated `SKILL.md` and edit the file to include your instructions.
3. Optionally add additional scripts or other resources to the `test-skill` folder. For more information, see [Examples](/oss/python/deepagents/skills#example).
You can also copy existing skills directly to the agent's folder:
```bash theme={null}
mkdir -p ~/.deepagents//skills
cp -r examples/skills/web-research ~/.deepagents//skills/
```
You can use tools like Vercel's [Skills CLI](https://github.com/vercel-labs/skills) to install community [Agent Skills](https://agentskills.io/) in your environment and make them available to your deep agents:
```bash theme={null}
# Install a skill globally
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a deepagents -g -y
# List installed skills
npx skills ls -a deepagents -g
```
Global installs (`-g`) symlink skills into `~/.deepagents/agent/skills/` — the default agent's user-level skills directory. Project-level installs (omit `-g`) place skills in `.deepagents/skills/` relative to the current directory, making them available to any agent running in that project regardless of agent name.
Global installs target the default `agent` directory only. If you use a custom-named agent, either use project-level installs or manually symlink the skill into `~/.deepagents/{your-agent}/skills/`.
At startup, the CLI discovers skills from both Deep Agents and shared alias directories:
```text theme={null}
`~/.deepagents//skills/`
`~/.agents/skills/`
`.deepagents/skills/`
`.agents/skills/`.
```
When duplicate skill names exist, later-precedence directories override earlier ones (see [App data](/oss/python/deepagents/data-locations#skills)).
For project-specific skills, the project's root folder must have a `.git` folder.
When you start the CLI from anywhere within the project's folder, the CLI will find the project's root folder by checking for a containing `.git` folder.
For each skill, the CLI reads the name and the description from the `SKILL.md` file's frontmatter.
As you use the CLI, if a task matches the skill's description, the agent will read the skill file and follow its instructions.
```bash theme={null}
# List all user skills
deepagents skills list
# List project skills
deepagents skills list --project
# Get detailed info about a specific skill
deepagents skills info test-skill
deepagents skills info test-skill --project
```
## Custom subagents
Define custom [subagents](/oss/python/deepagents/subagents) as markdown files so the CLI agent can delegate specialized tasks to them. Each subagent lives in its own folder with an `AGENTS.md` file:
```text theme={null}
.deepagents/agents/{subagent-name}/AGENTS.md # Project-level
~/.deepagents/{agent}/agents/{subagent-name}/AGENTS.md # User-level
```
Project subagents override user subagents with the same name (see [precedence rules](/oss/python/deepagents/data-locations#subagents)).
The frontmatter requires `name` and `description` (same as the [SubAgent dictionary spec](/oss/python/deepagents/subagents#subagent-dictionary-based)). The markdown body becomes the subagent's `system_prompt`. In addition to the base spec, `AGENTS.md` files support an optional `model` frontmatter field that overrides the main agent's model for this subagent. Uses the `provider:model-name` format (e.g., `anthropic:claude-haiku-4-5-20251001`, `openai:gpt-4o`). Omit to inherit the main agent's model.
Other SubAgent fields (`tools`, `middleware`, `interrupt_on`, `skills`) are not configurable via `AGENTS.md` frontmatter — custom subagents defined this way inherit the main agent's tools. Use the SDK directly for full control.
Subagent `AGENTS.md` files use YAML frontmatter followed by a markdown body:
```markdown theme={null}
---
name: researcher
description: Research topics on the web before writing content
model: anthropic:claude-haiku-4-5-20251001
---
You are a research assistant with access to web search.
## Your Process
1. Search for relevant information
2. Summarize findings clearly
```
Use a cheaper, faster model for simple delegation tasks while keeping the main agent on a more capable model:
```markdown theme={null}
---
name: general-purpose
description: General-purpose agent for research and multi-step tasks
model: anthropic:claude-haiku-4-5-20251001
---
You are a general-purpose assistant. Complete the task efficiently and return a concise summary.
```
This overrides the built-in general-purpose subagent, routing all delegated tasks to a cheaper model. See [Override the general-purpose subagent](/oss/python/deepagents/subagents#override-the-general-purpose-subagent) for more.
## Use MCP tools
Extend the CLI with tools from external [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) servers. Place a `.mcp.json` at your project root and the CLI discovers it automatically. See the [MCP tools guide](/oss/python/deepagents/cli/mcp-tools) for configuration format, auto-discovery, and troubleshooting.
## Use remote sandboxes
The CLI uses the [sandbox as tool](/oss/python/deepagents/sandboxes#sandbox-as-tool-pattern) pattern: the CLI process (LLM loop, memory, tool dispatch) runs on your machine, but agent tool calls (`read_file`, `write_file`, `execute`, etc.) target the remote sandbox, not your local filesystem. To get files into the sandbox, use a [setup script](#setup-scripts) or the provider's file transfer APIs (see [Working with files](/oss/python/deepagents/sandboxes#working-with-files)).
For a deeper look at sandbox architecture, integration patterns, and security best practices, see [Sandboxes](/oss/python/deepagents/sandboxes).
LangSmith sandbox support is included with the CLI by default. Modal, Daytona, and Runloop require installing extras.
Included by default when installing `deepagents-cli`. No extra installation needed.
```bash theme={null}
uv tool upgrade deepagents-cli --with langchain-daytona
```
```bash theme={null}
uv tool upgrade deepagents-cli --with langchain-runloop
```
```bash theme={null}
uv tool upgrade deepagents-cli --with langchain-modal
```
```bash theme={null}
export LANGSMITH_API_KEY="your-key"
```
```bash theme={null}
export DAYTONA_API_KEY="your-key"
```
```bash theme={null}
export RUNLOOP_API_KEY="your-key"
```
```bash theme={null}
modal setup
```
```bash theme={null}
deepagents --sandbox langsmith
```
```bash theme={null}
deepagents --sandbox daytona
```
```bash theme={null}
deepagents --sandbox runloop
```
```bash theme={null}
deepagents --sandbox modal
```
| Flag | Description |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `--sandbox TYPE` | Sandbox provider to use: `langsmith`, `modal`, `daytona`, or `runloop` (default: `none`) |
| `--sandbox-id ID` | Reuse an existing sandbox by ID instead of creating a new one. Skips creation and cleanup. Refer to your sandbox documentation for more |
| `--sandbox-setup PATH` | Path to a setup script to run inside the sandbox upon creation |
Examples:
```bash theme={null}
# Create a new Daytona sandbox
deepagents --sandbox daytona
# Reuse an existing sandbox (skips creation and cleanup)
deepagents --sandbox runloop --sandbox-id dbx_abc123
# Run a setup script after sandbox creation
deepagents --sandbox modal --sandbox-setup ./setup.sh
```
Use `--sandbox-setup` to run a shell script inside the sandbox after creation. This is useful for cloning repos, installing dependencies, and configuring environment variables.
```bash title="setup.sh" theme={null}
#!/bin/bash
set -e
# Clone repository using GitHub token
git clone https://x-access-token:${GITHUB_TOKEN}@github.com/username/repo.git $HOME/workspace
cd $HOME/workspace
# Make environment variables persistent
cat >> ~/.bashrc <<'EOF'
export GITHUB_TOKEN="${GITHUB_TOKEN}"
export OPENAI_API_KEY="${OPENAI_API_KEY}"
cd $HOME/workspace
EOF
source ~/.bashrc
```
The CLI expands `${VAR}` references in setup scripts using your local environment variables. Store secrets in a local `.env` file for the setup script to access.
Sandboxes isolate code execution, but agents remain vulnerable to prompt injection with untrusted inputs. Use human-in-the-loop approval, short-lived secrets, and trusted setup scripts only. See [Security considerations](/oss/python/deepagents/sandboxes#security-considerations) for details.
## Tracing with LangSmith
Enable LangSmith tracing to see agent operations in a LangSmith project:
1. Enable LangSmith tracing:
```bash theme={null}
export LANGCHAIN_TRACING=true
export LANGCHAIN_API_KEY="your-api-key"
```
2. Configure agent tracing for deep agent operations such as tool calls and agent decisions:
```bash theme={null}
export DEEPAGENTS_LANGSMITH_PROJECT="my-deep-agent-execution"
```
3. If you are building a LangChain app with Deep Agents, and want to separate agent traces from your app's traces, also configure `LANGSMITH_PROJECT`:
```bash theme={null}
export LANGSMITH_PROJECT="my-app-calls-to-langchain"
```
When configured, the CLI displays:
```sh theme={null}
✓ LangSmith tracing: 'my-project'
```
## Command reference
```bash theme={null}
# Use a specific agent configuration
deepagents --agent mybot
# Use a specific model (provider:model format or auto-detect)
deepagents --model anthropic:claude-sonnet-4-5
deepagents --model gpt-4o
# Auto-approve tool usage (skip human-in-the-loop prompts)
deepagents -y
```
| Option | Description |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-a`, `--agent NAME` | Use named agent with separate memory (default: `agent`) |
| `-M`, `--model MODEL` | Use a specific model (`provider:model`) |
| `--model-params JSON` | Extra kwargs to pass to the model as a JSON string (e.g., `'{"temperature": 0.7}'`) |
| `--default-model [MODEL]` | Set the default model |
| `--clear-default-model` | Clear the default model |
| `-r`, `--resume [ID]` | Resume a session: `-r` for most recent, `-r ` for a specific thread |
| `-m`, `--message TEXT` | Initial prompt to auto-submit when the session starts (interactive mode) |
| `-n`, `--non-interactive TEXT` | Run a single task non-interactively and exit. Shell is disabled unless `--shell-allow-list` is set |
| `-q`, `--quiet` | Clean output for piping—only the agent's response goes to stdout. Requires `-n` or piped stdin |
| `--no-stream` | Buffer the full response and write to stdout at once instead of streaming. Requires `-n` or piped stdin |
| `-y`, `--auto-approve` | Auto-approve all tool calls without prompting (disables human-in-the-loop). Toggle with `Shift+Tab` during an interactive session |
| `-S`, `--shell-allow-list LIST` | Comma-separated shell commands to auto-approve, `'recommended'` for safe defaults, or `'all'` to allow any command. Applies to both `-n` and interactive modes |
| `--json` | Emit machine-readable JSON from management subcommands (`list`, `reset`, `threads`, `skills`). Output envelope: `{"schema_version": 1, "command": "...", "data": ...}` |
| `--sandbox TYPE` | Remote sandbox for code execution: `none` (default), `langsmith`, `modal`, `daytona`, `runloop`. LangSmith is included; Modal/Daytona/Runloop require extras |
| `--sandbox-id ID` | Reuse an existing sandbox (skips creation and cleanup) |
| `--sandbox-setup PATH` | Path to setup script to run in sandbox after creation |
| `--mcp-config PATH` | Add an explicit MCP config as the highest-precedence source (merged with auto-discovered configs) |
| `--no-mcp` | Disable all MCP tool loading |
| `--trust-project-mcp` | Trust project-level MCP configs with stdio servers (skip approval prompt) |
| `-v`, `--version` | Display version |
| `-h`, `--help` | Show help |
| Command | Description |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deepagents help` | Show help |
| `deepagents list` | List all agents |
| `deepagents reset --agent NAME` | Clear agent memory and reset to default |
| `deepagents reset --agent NAME --target SOURCE` | Copy memory from another agent |
| `deepagents skills list [--project]` | List all skills (alias: `ls`) |
| `deepagents skills create NAME [--project]` | Create a new skill with template `SKILL.md` |
| `deepagents skills info NAME [--project]` | Show detailed information about a skill |
| `deepagents skills delete NAME [--project] [-f]` | Delete a skill and its contents |
| `deepagents threads list [--agent NAME] [--limit N]` | List sessions (alias: `ls`). Default limit: 20. `-n` is a short flag for `--limit`. Additional flags: `--sort {created,updated}`, `--branch TEXT` (filter by git branch), `-v`/`--verbose` (show all columns including branch, created time, and initial prompt), `-r`/`--relative` (relative timestamps) |
| `deepagents threads delete ID` | Delete a session |
All management subcommands support `--json` for machine-readable output. See [command-line options](#command-line-options) for details.
***
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/cli/overview.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
The Deep Agents CLI has the following built-in capabilities:
*