langchain-ai/deepagents
1
0
Fork 0
mirror of https://github.com/langchain-ai/deepagents.git synced 2026-07-22 09:45:24 -04:00
Code Issues 169 Packages Projects Releases 16 Wiki Activity

docs(cli): enhance README with comprehensive documentation

Browse Source 
Resolved all TODO(Claude) comments by adding:
- Clear quickstart with pip/uv installation instructions
- Comprehensive built-in tools table with HITL explanation
- CLI help command and configuration options
- Agent management commands (list, create, reset)
- Memory system documentation (agent.md files and project memory)
- Skills system architecture with progressive disclosure pattern
- Links to implementation in agent_memory.py
This commit is contained in:
Lance Martin
2025-11-20 12:12:54 -08:00
parent 05ae461d76
commit 192e7d5582
2 changed files with 215 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+1
View File
@@ -8,6 +8,7 @@ Agents can increasingly tackle long-horizon tasks, [with agent task length doubl
- **[Documentation](https://docs.langchain.com/oss/python/deepagents/overview)** - Full overview and API reference
- **[Quickstarts Repo](https://github.com/langchain-ai/deepagents-quickstarts)** - Examples and use-cases
- **[CLI](libs/deepagents-cli/)** - Interactive command-line interface with skills, memory, and HITL workflows
## 🚀 Quickstart
libs/deepagents-cli/README.md
+214 -61
View File
@@ -1,120 +1,252 @@
# deepagents cli
# 🚀🧠 Deep Agents
This is the CLI for deepagents
The [deepagents](https://github.com/langchain-ai/deepagents) CLI is an open source coding assistant that runs in your terminal, similar to Claude Code.
## Memory & Configuration Structure
**Key Features:**
- **Built-in Tools**: File operations (read, write, edit, glob, grep), shell commands, web search, and subagent delegation
- **Customizable Skills**: Add domain-specific capabilities through a progressive disclosure skill system
- **Persistent Memory**: Agent remembers your preferences, coding style, and project context across sessions
- **Project-Aware**: Automatically detects project roots and loads project-specific configurations
The CLI uses a dual-scope memory system with both **global** (per-agent) and **project-specific** configuration:
<img src="cli-banner.jpg" alt="deep agent" width="100%"/>
### Global Configuration
## 🚀 Quickstart
`deepagents-cli` is a Python package that can be installed via pip or uv.
**Install via pip:**
```bash
pip install deepagents-cli
```
**Or using uv (recommended):**
```bash
# Create a virtual environment
uv venv
# Install the package
uv pip install deepagents-cli
```
**Run the agent in your terminal:**
```bash
deepagents
```
**Get help:**
```bash
deepagents help
```
**Common options:**
```bash
# Use a specific agent configuration
deepagents --agent mybot
# Auto-approve tool usage (skip human-in-the-loop prompts)
deepagents --auto-approve
# Execute code in a remote sandbox
deepagents --sandbox modal # or runloop, daytona
deepagents --sandbox-id dbx_123 # reuse existing sandbox
```
Type naturally as you would in a chat interface. The agent will use its built-in tools, skills, and memory to help you with tasks.
## Built-in Tools
The agent comes with the following built-in tools (always available without configuration):
| Tool | Description |
|------|-------------|
| `ls` | List files and directories |
| `read_file` | Read contents of a file |
| `write_file` | Create or overwrite a file |
| `edit_file` | Make targeted edits to existing files |
| `glob` | Find files matching a pattern (e.g., `**/*.py`) |
| `grep` | Search for text patterns across files |
| `shell` | Execute shell commands (local mode) |
| `execute` | Execute commands in remote sandbox (sandbox mode) |
| `web_search` | Search the web using Tavily API |
| `fetch_url` | Fetch and convert web pages to markdown |
| `task` | Delegate work to subagents for parallel execution |
| `write_todos` | Create and manage task lists for complex work |
> [!WARNING]
> **Human-in-the-Loop (HITL) Approval Required**
>
> Potentially destructive operations require user approval before execution:
> - **File operations**: `write_file`, `edit_file`
> - **Command execution**: `shell`, `execute`
> - **External requests**: `web_search`, `fetch_url`
> - **Delegation**: `task` (subagents)
>
> Each operation will prompt for approval showing the action details. Use `--auto-approve` to skip prompts:
> ```bash
> deepagents --auto-approve
> ```
## Agent Configuration
Each agent has its own configuration directory at `~/.deepagents/<agent_name>/`, with default `agent`.
```bash
# List all configured agents
deepagents list
# Create a new agent
deepagents create <agent_name>
```
## Customization
There are two primary ways to customize any agent: **memory** and **skills**.
Each agent has its own global configuration directory at `~/.deepagents/<agent_name>/`:
```
~/.deepagents/<agent_name>/
├── agent.md # Auto-loaded global personality/style
├── skills/ # Auto-loaded agent-specific skills
│ ├── web-research/
│ │ └── SKILL.md
│ └── langgraph-docs/
│ └── SKILL.md
└── skills/ # Auto-loaded agent-specific skills
├── web-research/
│ └── SKILL.md
└── langgraph-docs/
└── SKILL.md
```
- **agent.md**: Defines your agent's personality, style, and general instructions (applies to all projects)
- **skills/**: Reusable capabilities that can be invoked across any project
### Project-Specific Configuration
Projects can override or extend the global configuration with project-specific instructions:
Projects can extend the global configuration with project-specific instructions and skills:
```
my-project/
├── .git/
└── .deepagents/
└── agent.md
├── agent.md # Project-specific instructions
└── skills/ # Project-specific skills
└── custom-tool/
└── SKILL.md
```
The CLI automatically detects project roots (via `.git`) and loads project-specific `agent.md` from `[project-root]/.deepagents/agent.md`.
The CLI automatically detects project roots (via `.git`) and loads:
- Project-specific `agent.md` from `[project-root]/.deepagents/agent.md`
- Project-specific skills from `[project-root]/.deepagents/skills/`
Both global and project agent.md files are loaded together, allowing you to:
Both global and project configurations are loaded together, allowing you to:
- Keep general coding style/preferences in global agent.md
- Add project-specific context, conventions, or guidelines in project agent.md
- Share project-specific skills with your team (committed to version control)
- Override global skills with project-specific versions (when skill names match)
### How the System Prompt is Constructed
### agent.md files
The CLI uses middleware to dynamically construct the system prompt on each model call:
`agent.md` files provide persistent memory that is always loaded at session start. Both global and project-level `agent.md` files are loaded together and injected into the system prompt.
1. **AgentMemoryMiddleware** (runs first):
- **Prepends** the contents of both agent.md files:
```xml
<user_memory>[~/.deepagents/{agent}/agent.md content]</user_memory>
<project_memory>[{project}/.deepagents/agent.md content]</project_memory>
```
- **Appends** memory management instructions (how to read/write memory files, decision framework)
**Global `agent.md`** (`~/.deepagents/agent/agent.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
2. **SkillsMiddleware** (runs second):
- **Appends** list of available skills (name + description only, not full SKILL.md content)
- **Appends** progressive disclosure instructions (how to read full SKILL.md when needed)
**Project `agent.md`** (`.deepagents/agent.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
3. **Base System Prompt**:
- Current working directory info
- Skills directory location
- Human-in-the-loop guidance
**How it works (AgentMemoryMiddleware):**
- Loads both files at startup and injects into system prompt as `<user_memory>` and `<project_memory>`
- Appends [memory management instructions](deepagents_cli/agent_memory.py#L44-L158) on when/how to update memory files
**Final prompt structure:**
```
<user_memory>...</user_memory>
<project_memory>...</project_memory>
**When the agent updates memory:**
- IMMEDIATELY when you describe how it should behave
- IMMEDIATELY when you give feedback on its work
- When you explicitly ask it to remember something
- When patterns or preferences emerge from your interactions
[Base system prompt]
The agent uses `edit_file` to update memories when learning preferences or receiving feedback.
[Memory management instructions with project-scoped paths]
### Project memory files
[Skills list + progressive disclosure instructions]
Beyond `agent.md`, you can create additional memory files in `.deepagents/` for structured project knowledge. These work similarly to [Anthropic's Memory Tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool). The agent receives [detailed instructions](deepagents_cli/agent_memory.py#L123-L158) on when to read and update these files.
**How it works:**
1. Create markdown files in `[project-root]/.deepagents/` (e.g., `api-design.md`, `architecture.md`, `deployment.md`)
2. The agent checks these files when relevant to a task (not auto-loaded into every prompt)
3. The agent uses `write_file` or `edit_file` to create/update memory files when learning project patterns
**Example workflow:**
```bash
# Agent discovers deployment pattern and saves it
.deepagents/
├── agent.md # Always loaded (personality + conventions)
├── architecture.md # Loaded on-demand (system design)
└── deployment.md # Loaded on-demand (deploy procedures)
```
This approach ensures that agent.md contents are always loaded, while skills use progressive disclosure (metadata shown, full instructions read on-demand).
**When the agent reads memory files:**
- At the start of new sessions (checks what files exist)
- Before answering questions about project-specific topics
- When you reference past work or patterns
- When performing tasks that match saved knowledge domains
## Skills
**Benefits:**
- **Persistent learning**: Agent remembers project patterns across sessions
- **Team collaboration**: Share project knowledge through version control
- **Contextual retrieval**: Load only relevant memory when needed (reduces token usage)
- **Structured knowledge**: Organize information by domain (APIs, architecture, deployment, etc.)
Skills are reusable agent capabilities that can be loaded into the CLI. Each agent has its own skills directory at `~/.deepagents/{AGENT_NAME}/skills/`.
### Skills
For the default agent (named `agent`), skills are stored in `~/.deepagents/agent/skills/`.
### Example Skills
Example skills are provided in the `examples/skills/` directory:
Skills are reusable agent capabilities that provide specialized workflows and domain knowledge. Example skills are provided in the `examples/skills/` directory:
- **web-research** - Structured web research workflow with planning, parallel delegation, and synthesis
- **langgraph-docs** - LangGraph documentation lookup and guidance
To use an example skill with the default agent, copy it to your agent's skills directory:
To use an example skill globally with the default agent, just copy them to the agent's skills global or project-level skills directory:
```bash
mkdir -p ~/.deepagents/agent/skills
cp -r examples/skills/web-research ~/.deepagents/agent/skills/
```
For a custom agent, replace `agent` with your agent name:
To manage skills:
```bash
mkdir -p ~/.deepagents/my-agent/skills
cp -r examples/skills/web-research ~/.deepagents/my-agent/skills/
```
### Managing Skills
```bash
# List available skills
# List all skills (global + project)
deepagents skills list
# Create a new skill from template
# List only project skills
deepagents skills list --project
# Create a new global skill from template
deepagents skills create my-skill
# Create a new project skill
deepagents skills create my-tool --project
# View detailed information about a skill
deepagents skills info web-research
# View info for a project skill only
deepagents skills info my-tool --project
```
To use skills (e.g., the langgraph-docs skill), just type a request relevant to a skill and the skill will be used automatically.
```bash
$ deepagents
$ "create a agent.py script that implements a LangGraph agent"
```
Skills follow Anthropic's [progressive disclosure pattern](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) - the agent knows skills exist but only reads full instructions when needed.
1. **At startup** - SkillsMiddleware scans `~/.deepagents/agent/skills/` and `.deepagents/skills/` directories
2. **Parse metadata** - Extracts YAML frontmatter (name + description) from each `SKILL.md` file
3. **Inject into prompt** - Adds skill list with descriptions to system prompt: "Available Skills: web-research - Use for web research tasks..."
4. **Progressive loading** - Agent reads full `SKILL.md` content with `read_file` only when a task matches the skill's description
5. **Execute workflow** - Agent follows the step-by-step instructions in the skill file
## Development
### Running Tests
@@ -126,3 +258,24 @@ uv sync --all-groups
make test
```
### Running During Development
```bash
# From libs/deepagents-cli directory
uv run deepagents
# Or install in editable mode
uv pip install -e .
deepagents
```
### Modifying the CLI
- **UI changes** → Edit `ui.py` or `input.py`
- **Add new tools** → Edit `tools.py`
- **Change execution flow** → Edit `execution.py`
- **Add commands** → Edit `commands.py`
- **Agent configuration** → Edit `agent.py`
- **Skills system** → Edit `skills/` modules
- **Constants/colors** → Edit `config.py`