uv tool install deepagents-cli
deepagentsUsing an LLM to call tools in a loop is the simplest form of an agent. This architecture, however, can yield agents that are "shallow" and fail to plan and act over longer, more complex tasks.
Applications like "Deep Research", "Manus", and "Claude Code" have gotten around this limitation by implementing a combination of four things: a planning tool, sub agents, access to a file system, and a detailed prompt.
deepagents is a Python package that implements these in a general purpose way so that you can easily create a Deep Agent for your application. For a full overview and quickstart of Deep Agents, the best resource is our docs.
Acknowledgements: This project was primarily inspired by Claude Code, and initially was largely an attempt to see what made Claude Code general purpose, and make it even more so.
See our Releases and Versioning policies.
As an open-source project in a rapidly developing field, we are extremely open to contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation.
For detailed information on how to contribute, see the Contributing Guide.
Data used to render HITL previews.
Line and byte level metrics for a file operation.
Track a single filesystem tool call.
Collect file operation metrics during a CLI interaction.
Thread metadata returned by list_threads.
Metadata for a custom subagent loaded from filesystem.
Adapter for rendering agent output to Textual widgets.
Raised when model configuration or creation fails.
A model specification in provider:model format.
Configuration for a model provider.
Parsed model configuration from config.toml.
Represents a pasted image with its base64 encoding.
Raised when the HITL interrupt loop exceeds _MAX_HITL_ITERATIONS rounds.
Mutable state accumulated while iterating over the agent stream.
State for local context middleware.
Inject local context (git state, project structure, etc.) into the system prompt.
Track pasted images in the current conversation.
Character set mode for TUI display.
Character glyphs for TUI display.
Global settings and environment detection for deepagents-cli.
Mutable session state shared across the app, adapter, and agent.
Result of creating a chat model, bundling the model with its metadata.
Represents a queued user message awaiting processing.
Token tracker that updates the status bar.
Session state for the Textual app.
Main Textual application for deepagents-cli.
Result from running the Textual application.
LangSmith backend implementation conforming to SandboxBackendProtocol.
LangSmith sandbox provider implementation.
Base error for sandbox provider operations.
Raised when the requested sandbox cannot be found.
Interface for creating and deleting sandbox backends.
Modal backend implementation conforming to SandboxBackendProtocol.
Modal sandbox provider implementation.
Backend that operates on files in a Runloop devbox.
Runloop sandbox provider implementation.
Daytona backend implementation conforming to SandboxBackendProtocol.
Daytona sandbox provider implementation.
Base renderer for tool approval widgets.
Renderer for write_file tool - shows full file content.
Renderer for edit_file tool - shows unified diff.
Animated spinner using charset-appropriate frames.
Animated loading indicator with status text and elapsed time.
Base class for tool approval widgets.
Generic approval widget for unknown tools.
Approval widget for write_file - shows file content with syntax highlighting.
Approval widget for edit_file - shows clean diff with colors.
A clickable completion option in the autocomplete popup.
Message sent when a completion option is clicked.
Popup widget that displays completion suggestions as clickable options.
Message sent when a completion option is clicked.
TextArea subclass with custom key handling for chat input.
Message sent when text is submitted.
Request previous history entry.
Request next history entry.
Message sent when paste payload resolves to file paths.
Chat input widget with prompt, multi-line text, autocomplete, and history.
Message sent when input is submitted.
Message sent when input mode changes.
Status bar showing mode, auto-approve status, and working directory.
Result of handling a key event in the completion system.
Protocol for views that can display completion suggestions.
Protocol for completion controllers.
Controller for / slash command completion.
Controller for @ file completion with fuzzy matching from project root.
Manages multiple completion controllers, delegating to the active one.
Types of messages in the chat.
Status of a tool call.
In-memory message data for virtualization.
Manages message data and widget window for virtualization.
Manages command history with file persistence.
Result of formatting tool output for display.
Widget displaying a user message.
Widget displaying a queued (pending) user message in grey.
Widget displaying an assistant message with markdown support.
Widget displaying a tool call with collapsible output.
Widget displaying a diff with syntax highlighting.
Widget displaying an error message.
Widget displaying an app message.
Widget for displaying a unified diff with syntax highlighting.
A clickable model option in the selector.
Message sent when a model option is clicked.
Full-screen modal for model selection.
Approval menu using standard Textual patterns.
Message sent when user makes a decision.
Welcome banner displayed at startup.
A clickable thread option in the selector.
Message sent when a thread option is clicked.
Modal dialog for browsing and resuming threads.
Extended skill metadata for CLI display, adds source tracking.
Find the project root by looking for .git directory.
Find project-specific agent.md file(s).
List all available agents.
Reset an agent to default or copy from another agent.
Get the base system prompt for the agent.
Create a CLI-configured agent with flexible options.
Compute a unified diff between before and after content.
Convert a virtual/relative path to a physical filesystem path.
Format a path for display.
Collect summary info and diff for HITL approvals.
Format ISO timestamp for display (e.g., 'Dec 30, 6:10pm').
Get path to global database.
Generate a new 8-char hex thread ID.
List threads from checkpoints table.
Get most recent thread_id, optionally filtered by agent.
Get agent_name for a thread.
Check if a thread exists in checkpoints.
Find threads whose IDs start with the given prefix.
Delete thread checkpoints.
Get AsyncSqliteSaver for the global database.
Read the thread listing limit from DA_CLI_RECENT_THREADS.
CLI handler for deepagents threads list.
CLI handler for: deepagents threads delete.
List subagents from user and/or project directories.
Execute a task with output directed to Textual UI.
Reset module-level caches so the next call recomputes from scratch.
Get available models dynamically from installed LangChain provider packages.
Check if credentials are available for a provider.
Return the env var name that holds credentials for a provider.
Update the default model in config file.
Remove the default model from the config file.
Check if a warning key is suppressed in the config file.
Add a warning key to the suppression list in the config file.
Update the recently used model in config file.
Check if CLI optional dependencies are installed.
Check for recommended external tools and return missing tool names.
Format a missing-tool warning for the TUI toast.
Format a missing-tool warning for non-interactive Rich console output.
Parse command line arguments.
Run the Textual CLI interface (async version).
Read piped stdin and merge it into the parsed CLI arguments.
Entry point for console script.
Attempt to read an image from the system clipboard.
Read and encode an image file from disk.
Encode image bytes to base64 string.
Create multimodal message content with text and images.
Run a single task non-interactively and exit.
Copy selected text from app widgets to clipboard.
Concatenate all section functions into the full detection script.
Extract @file mentions and return the text with resolved file paths.
Parse a paste payload that may contain dragged-and-dropped file paths.
Build a parent parser whose -h invokes help_fn.
Show top-level help information for the deepagents CLI.
Show help information for the list subcommand.
Show help information for the reset subcommand.
Show help information for the skills subcommand.
Show help information for the skills list subcommand.
Show help information for the skills create subcommand.
Show help information for the skills info subcommand.
Show help information for the skills delete subcommand.
Show help information for the threads subcommand.
Show help information for the threads delete subcommand.
Show help information for the threads list subcommand.
Truncate a string value if it exceeds max_length.
Format tool calls for display with tool-specific smart formatting.
Convert ToolMessage content into a printable string.
Get the glyph set for the current charset mode.
Reset the glyphs cache (for testing).
Get the appropriate banner for the current charset mode.
Parse shell allow-list from string.
Check if a command contains dangerous shell patterns.
Check if a shell command is in the allow-list.
Resolve the LangSmith project name if tracing is configured.
Fetch the LangSmith project URL via the LangSmith client.
Build a full LangSmith thread URL if tracing is configured.
Reset the LangSmith URL cache (for testing).
Get the default coding agent instructions.
Auto-detect provider from model name.
Create a chat model.
Validate that the model has required capabilities for deepagents.
Run the Textual application.
Make HTTP requests to APIs and web services.
Search the web using Tavily for current information and documentation.
Fetch content from a URL and convert HTML to markdown format.
Create or connect to a sandbox of the specified provider.
Get the default working directory for a given sandbox provider.
Get the renderer for a tool by name.
Format a unified diff with line numbers and colors.
Open the URL from a Rich link style on click, if present.
Setup the skills subcommand parser with all its subcommands.
Execute skills subcommands based on parsed arguments.
List skills from built-in, user, and/or project directories.