以编程方式使用文档

Deep Agents Code (dcode) 是一个基于 Deep Agents SDK. 构建的开源编程代理。它可与任何大型语言模型配合使用，并支持在会话中切换提供商或模型。 持久记忆在对话间携带上下文，可自定义技能塑造其行为，审批控制则对代码执行进行把关。

快速入门

Install and launch

        curl -LsSf https://langch.in/dcode | bash

Add provider credentials

Deep Agents Code 可与任何工具调用 LLM 配合使用。OpenAI、Anthropic 和 Google 开箱即用。

使用 /auth 命令连接提供商。请参阅 提供商 获取完整列表和凭据详情。

Choose a model (optional)

运行 /model 在会话中打开交互式切换器，或使用启动 --model:

        dcode --model anthropic:claude-opus-4-8
        dcode --model openai:gpt-5.5
        dcode --model fireworks:accounts/fireworks/models/deepseek-v4-pro
        dcode --model baseten:moonshotai/Kimi-K2.7-Code

请参阅 模型提供商 获取完整提供商列表、开放权重选项和凭据详情。

Give the agent a task

        Create a Python script that prints "Hello, World!"

代理会解释查询并通过差异对比提出修改建议供您审批，然后再修改文件。如有需要，它可以运行 shell 命令来测试代码、查阅文档或搜索网络获取最新信息。

Enable tracing (optional)

要在 LangSmith 中记录代理操作、工具调用和决策，请将以下内容添加到 ~/.deepagents/.env 或在 shell 中导出变量：

        LANGSMITH_TRACING=true
        LANGSMITH_API_KEY=lsv2_...
        LANGSMITH_PROJECT=optional-project-name  # Specify a project name or default to "deepagents-code"

更多详情和使用方法，请参阅 使用 LangSmith 进行追踪.

功能

Deep Agents Code 具有以下内置功能：

  • * **文件操作** - 读取、写入和编辑磁盘上的文件。
  • * **Shell 执行** - 执行命令以运行测试、构建项目、管理依赖项和与版本控制交互。
  • * **远程沙箱** - 远程运行代理工具，而非在本地机器上运行。
  • * **网络搜索** - 搜索网络获取最新信息和文档。需要 Tavily API 密钥.
  • * **任务规划与跟踪** - 将复杂任务分解为离散的步骤并跟踪进度。
  • * **子代理** - 将工作委托给特定任务的子代理。
  • * **记忆存储与检索** - 跨会话存储和检索信息，使智能体能够记住项目约定和学习到的模式。
  • * **上下文压缩与卸载** - 总结较早的对话消息并将其原文卸载到存储中。
  • * **Human-in-the-loop** - 敏感工具操作需要人工审批。
  • * **技能** - 通过自定义专业知识和指令扩展智能体能力。
  • * **MCP 工具** - 从加载外部工具 模型上下文协议 servers.
  • * **追踪** - 在 LangSmith 中追踪智能体操作以实现可观测性和调试。

Full list of built-in tools

内置工具

智能体附带了以下内置工具，无需配置即可使用：

工具描述人工介入
ls列出文件和目录-
read_file读取文件内容；返回图像、音频、视频和 PDF 的多模态块-
write_file创建或覆盖文件必需<sup>1</sup>
edit_file对现有文件进行定向编辑必需<sup>1</sup>
glob查找匹配模式的文件-
grep跨文件搜索文本模式-
execute在本地或远程沙箱中执行 shell 命令 执行 shell 命令必需<sup>1</sup>
web_search使用 Tavily 搜索网络（参见 启用网络搜索）必需<sup>1</sup>
fetch_url获取并转换网页为 markdown必需<sup>1</sup>
task将工作委托给 子智能体 以并行执行<sup>3</sup>必需<sup>1</sup>
ask_user向用户提出自由形式或多项选择题-
compact_conversation总结较早的消息，将原文卸载到后端存储，并在上下文中用摘要替换混合<sup>2</sup>
write_todos创建和管理复杂工作的任务列表-
get_current_thread_id返回 LangSmith 或 MCP 工具的当前线程 ID-

<sup>1</sup>：潜在破坏性操作需要在执行前获得用户批准。要跳过人工审批，您可以切换自动批准（shift+tab）或使用以下选项启动：

    dcode --auto-approve
    # shorter alias:
    dcode -y

<sup>2</sup>：深度智能体代码在 token 使用量超过模型感知阈值时自动在后台卸载对话。卸载通过 LLM 总结较早的消息，并将原文弹出到存储（/conversation_history/{thread_id}.md），在上下文中用摘要替换。智能体在需要时仍可以从卸载的文件中检索完整历史。 compact_conversation 工具允许智能体（或您）按需触发卸载。当作为工具调用时，它默认需要用户批准。

3：当通过 `[async_subagents]` 部分在 `config.toml` （见 [异步子代理](/oss/javascript/deepagents/async-subagents.html)），可使用额外的工具： `start_async_task`, `update_async_task`和 `cancel_async_task` （均需审批），以及 `check_async_task` 和 `list_async_tasks`.

命令参考

# Use a specific agent configuration
dcode --agent mybot

# Use a specific model (provider:model format or auto-detect)
dcode --model anthropic:claude-opus-4-8
dcode --model gpt-5.5

# Auto-approve tool usage (skip human-in-the-loop prompts)
dcode -y

# list directory contents, then summarize directory as first prompt—the command runs first, then the prompt is submitted
# the prompt does NOT have access to the command output
dcode --startup-cmd "ls -la" -m "Summarize what's in this directory"

# Non-interactive with startup command: show git status before the task runs
# the task does NOT have access to the command output
dcode --startup-cmd "git diff --stat" -n "Review these changes"

Command-line options

选项描述
-a, --agent NAME使用指定的代理并使用独立内存。覆盖 [agents].recent in config.toml。默认值： agent （如果设置了 [agents].recent ，则为最近使用的代理）
-M, --model MODEL使用指定的模型（provider:model)
--model-params JSON要以 JSON 字符串形式传递给模型的额外 kwargs（例如， '{"temperature": 0.7}')
--max-retries N覆盖临时模型错误的最大重试次数
--default-model [MODEL]设置 默认模型 （省略 MODEL 以查看当前默认值）
--clear-default-model清除 默认模型
-r, --resume [ID]恢复会话： -r 使用最近一次， -r 使用指定线程
-m, --message TEXT会话启动时自动提交的初始提示（交互模式）
--skill NAME启动时调用技能
--startup-cmd CMD启动时运行的 shell 命令，在首次提示之前。输出显示在记录中供你参考，但 **不会** 添加到代理的消息历史记录中。如需将命令输出传递给代理，请改用 stdin 管道（例如， `git diff \
-n, --non-interactive TEXT以非交互方式运行单个任务并退出。除非设置 --shell-allow-list ，否则禁用 shell
--max-turns N限制非交互模式中的代理轮数。超过时以代码 124 退出。需要 -n 或管道 stdin。请参阅 使用 --max-turns
--timeout SECONDS非交互模式的硬性时钟超时。超过时以代码 124 退出。需要 -n 或管道 stdin。请参阅 使用 --timeout
-q, --quiet管道传输的纯净输出——仅代理的响应输出到 stdout。需要 -n 或管道 stdin
--no-stream缓冲完整响应并一次性写入 stdout，而不是流式传输。需要 -n 或管道 stdin
--stdin明确从 stdin 读取输入，而不是自动检测。当 stdin 不可用或为 TTY 时会明确报错
-y, --auto-approve自动批准所有工具调用而不提示（禁用人工介入）。在交互会话中可用 Shift+Tab 切换
-S, --shell-allow-list LIST要自动批准的逗号分隔的 shell 命令， 'recommended' 使用安全默认值， 'all' 允许任何命令。适用于 -n 和非交互模式
--json从管理子命令发出机器可读的 JSON（agents, threads, skills, update）。输出信封： {"schema_version": 1, "command": "...", "data": ...}
--sandbox TYPE用于代码执行的远程沙箱： none （默认）， langsmith, agentcore, daytona, modal, runloop, e2b。包含 LangSmith；AgentCore、Daytona、Modal 和 Runloop 需要额外包；E2B 需要 langchain-e2b 作为包安装
--sandbox-id ID复用现有沙箱（跳过创建和清理）
--sandbox-snapshot-name NAME要使用或创建的沙箱快照名称（仅限 LangSmith）
--sandbox-setup PATH沙箱创建后要运行的设置脚本路径
--mcp-config PATH添加显式 MCP 配置作为最高优先级源（与自动发现的配置合并）
--no-mcp禁用所有 MCP 工具加载
--trust-project-mcp信任项目级 MCP 配置中的 stdio 服务器（跳过批准提示）
--interpreter在主代理上启用 JS 解释器（js_eval）中间件。仅本地模式；需要 quickjs 可选额外包
--interpreter-tools VALUE的 PTC 白名单或逗号分隔的工具名称列表。默认：无 PTC（纯 REPL）
--profile-override JSON覆盖模型配置字段为 JSON 字符串（例如， '{"max_input_tokens": 4096}'）。在配置文件配置覆盖之上合并
--acp通过 stdio 作为 ACP 服务器运行，而非启动交互式 UI
--update检查并安装更新，然后退出
--auto-update开启或关闭自动更新，然后退出
--install NAME安装可选额外包（例如 quickjs, daytona, fireworks），然后退出。添加 --package 将 NAME 视为通过 uv --with 安装的自定义提供商包，而非额外包（参见 自定义提供商），以及 --yes 跳过确认提示
-v, --version显示版本
-h, --help显示帮助

CLI commands

命令描述
dcode help显示帮助
dcode agents list列出所有代理（别名： ls)
dcode agents reset --agent NAME清除代理内存并重置为默认值。支持 --dry-run
dcode agents reset --agent NAME --target SOURCE从另一个代理复制内存
dcode update检查并安装 Deep Agents Code 更新
dcode skills list [--project]列出所有技能（别名： ls)
dcode skills create NAME [--project]使用模板创建新技能 SKILL.md。幂等——重新创建现有技能会打印信息消息而非错误
dcode skills info NAME [--project]显示技能详细信息
dcode skills delete NAME [--project] [-f]删除技能及其内容。支持 --dry-run
dcode threads list [--agent NAME] [--limit N]列出所有会话（别名： ls）。默认限制：20。 -n 是 --limit的短标志。附加标志： --sort {created,updated}, --branch TEXT （按 git 分支过滤）， --cwd [PATH] （按工作目录过滤；裸标志使用当前目录）， -v/--verbose （显示所有列，包括分支、创建时间和初始提示）， -r/--relative （相对时间戳）
dcode threads delete ID删除会话。支持 --dry-run
dcode mcp login NAME [--mcp-config PATH]为标记的 MCP 服务器运行 OAuth 登录流程 auth: "oauth"。参见 MCP 工具
dcode mcp config显示 MCP 配置发现路径
dcode config show显示每个配置选项的有效值及其解析来源。参见 检查配置
dcode config list列出所有可用配置选项及其类型、默认值和可设置位置（别名： ls)
dcode config get KEY显示一个选项的有效值和来源（例如 interpreter.memory_limit_mb)
dcode config path显示配置文件位置及每个文件是否存在

所有管理子命令支持 --json 以获取机器可读的输出。参见 命令行选项 了解更多详情。

破坏性命令（agents reset, skills delete, threads delete）支持 --dry-run 以在不进行更改的情况下预览会发生什么。在 JSON 模式下， --dry-run 返回相同的信封，其中包含 dry_run: true field.

配置

完整的参考信息——包括 config.toml 架构、提供商参数、配置文件覆盖和钩子配置——请参见 配置.

Deep Agents Code 将所有配置存储在 ~/.deepagents/下。在该目录中，每个代理都有自己的子目录（默认： agent):

路径用途
~/.deepagents/config.toml模型和代理默认值、提供商设置、构造函数参数、配置文件覆盖、主题、更新设置
~/.deepagents/.env全局 API 密钥和密钥。参见 配置
~/.deepagents/hooks.json生命周期事件钩子 (session start/end, task complete, etc.)
~/.deepagents/<agent_name>/每个代理的内存、技能和对话线程
.deepagents/ （项目根目录）项目特定的内存和技能，在 git 仓库内运行时加载

交互模式

像在聊天界面中一样自然地输入。 代理使用其内置工具、技能和内存来帮助你完成任务。

Slash commands

在 Deep Agents Code 会话中使用以下命令：

- /model - 切换模型或打开交互式模型选择器。 - /agents - 在不重新启动的情况下热切换预配置的代理。参见 命令参考 了解更多详情 - /auth - 管理模型提供商和服务的已存储 API 密钥（如 Tavily 网络搜索）。参见 提供商凭证 了解更多详情 - /remember [context] - 回顾对话并更新内存和技能。可选择传递额外的上下文 - /skill:<name> [args] - 按名称直接调用技能。该技能的 SKILL.md 指令会连同你提供的任何参数一起注入到提示中 - /skill-creator [task] - 创建有效代理技能的指南 - /offload （别名 /compact) - 通过将消息卸载到存储并带有摘要占位符来释放上下文窗口空间。如有需要，代理可以从卸载的文件中检索完整历史记录 - /tokens - 显示当前上下文窗口的 token 使用细分 - /clear - 清除对话历史并开始新对话 - /copy - 将最新助手消息复制到剪贴板 - /threads - 浏览并恢复之前的对话 - /mcp [login <server> | reconnect] - 显示活动的 MCP 服务器和工具 login <server> 为服务器运行 OAuth 流程 reconnect 加载延迟登录 - /notifications - 配置启动警告偏好设置 - /reload - 重新读取 .env 文件、刷新配置并重新发现技能而无需重启。对话状态会被保留。参见 DEEPAGENTS_CODE_ 前缀 了解覆盖行为 - /theme - 打开交互式主题选择器以切换颜色主题。可用内置主题以及任何 用户自定义主题 - /update - 检查并内联安装 Deep Agents Code 更新。检测您的安装方式（uv、Homebrew、pip）并运行相应的升级命令 - /auto-update - 切换自动更新开关 - /install - 安装可选的额外组件（例如， quickjs, daytona, fireworks) - /trace - 在 LangSmith 中打开当前对话（需要 LANGSMITH_API_KEY) - /editor - 在外部编辑器中打开当前提示词（$VISUAL / $EDITOR）。参见 外部编辑器 - /timestamps - 切换消息时间戳页脚 - /changelog - 在浏览器中打开 Deep Agents Code 更新日志 - /docs - 在浏览器中打开文档 - /feedback - 打开 GitHub 问题页面以提交错误报告或功能请求 - /version - 显示已安装的 deepagents-code 和 SDK 版本 - /help - 显示帮助和可用命令 - /quit - 退出应用程序

Shell commands

输入 ! 进入 shell 模式，然后输入您的命令

        git status
        npm test
        ls -la

Keyboard shortcuts

常规

| 快捷键 | 操作 | |-|-| | Enter | 提交提示词 | | Shift+Enter, Ctrl+J, Alt+Enter, or Ctrl+Enter | 插入换行 | | @filename | 自动补全文件并注入内容 | | Shift+Tab or Ctrl+T | 切换自动批准 | | Ctrl+X | 在外部编辑器中打开提示词 | | Ctrl+N | 查看待处理通知 | | Ctrl+O | Expand/collapse the most recent tool output | | Escape | 中断当前操作 | | Ctrl+C | 中断或退出 | | Ctrl+D | 退出 |

提示词中的文本编辑

聊天输入使用标准的 readline 风格绑定：

| 快捷键 | 操作 | |-|-| | Ctrl+A or Home | 将光标移动到行首 | | Ctrl+E or End | 将光标移动到行尾 | | Ctrl+U | 从光标处删除到行首 | | Ctrl+K | 从光标处删除到行尾 | | Ctrl+W or Ctrl+Backspace | 删除左侧单词 | | Ctrl+Left / Ctrl+Right | Move cursor one word left/right |

非交互模式和管道传输

使用 -n 运行单个任务而不启动交互式 UI：

dcode -n "Write a Python script that prints hello world"

每次非交互运行都会启动一个新线程——对话历史记录不会在调用之间保留。基于文件的状态（内存、技能、配置）会被保留。

你也可以通过 stdin 管道输入。当输入被管道传输时，Deep Agents Code 会自动以非交互方式运行：

echo "Explain this code" | dcode
cat error.log | dcode -n "What's causing this error?"
git diff | dcode -n "Review these changes"
git diff | dcode --skill code-review -n 'summarize changes'

当将管道输入与 -n or -m结合时，管道内容会先显示，然后是你传递给该标志的文本。

在非交互模式下，Shell 执行默认被禁用。使用 -S/--shell-allow-list 来启用特定命令（例如， -S "pytest,git,make"), recommended 获取安全默认值，或 all 允许任意命令。

Cap turn count

Long-running or misbehaving agents in CI/CD pipelines can loop indefinitely. --max-turns N 为操作员提供硬上限，而无需接触 SDK 内部结构：

        dcode -n "fix the failing tests" --max-turns 10

N 必须为正整数，并覆盖内部安全默认值（否则会限制失控循环）。当超过预算时以代码 124 退出（与 GNU timeout匹配），以便 CI 可以区分预算超支和通用故障。需要 -n 或管道式 stdin；否则以代码 2 退出。

有关基于时间的限制（而非或除了轮次限制），请参见 使用 --timeout.

Cap wall-clock time

--timeout SECONDS 对非交互运行强制执行硬性挂钟时间限制。它补充了 --max-turns （轮次计数）限制与基于时间的预算——无论哪个限制先达到都会取消代理。

        # Fail fast in CI if the task takes more than 2 minutes
        dcode -n "run the test suite and summarise failures" --timeout 120

        # Combine with --max-turns—whichever limit is hit first stops the agent
        dcode -n "refactor auth module" --timeout 300 --max-turns 20

到期时代理被取消，进程以代码 124 退出，这是 --max-turns使用的相同代码，以便 CI 统一处理这两种预算超支情况。需要 -n 或管道式 stdin；否则以代码 2 退出。

Clean output and buffering

使用 -q 获取适合管道传输到其他命令的干净输出，以及 --no-stream 在写入 stdout 之前缓冲完整响应（而非流式传输）：

        dcode -n "Generate a .gitignore for Python" -q > .gitignore
        dcode -n "List dependencies" -q --no-stream | sort

在非交互模式下，代理被指示做出合理假设并自主继续，而不是提出澄清问题。它还倾向于使用非交互式命令变体（例如， npm init -y, apt-get install -y).

Shell execution examples

        # Allow specific commands (validated against the list)
        dcode -n "Run the tests and fix failures" -S "pytest,git,make"

        # Use the curated safe-command list
        dcode -n "Build the project" -S recommended

        # Allow any shell command
        dcode -n "Fix the build" -S all

使用 LangSmith 追踪

启用 LangSmith 追踪以在 LangSmith 项目中查看代理操作、工具调用和决策。

将您的追踪密钥添加到 ~/.deepagents/.env ，以便在每个会话中启用追踪，无需每次 shell 导出：

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=optional-project-name  # Specify a project name or default to "deepagents-code"

要为特定项目覆盖，请将相同的密钥添加到 .env 中的项目目录。请参阅 环境变量 了解完整的加载顺序。

如果愿意，您也可以将这些设置为 shell 环境变量。Shell 导出始终优先于 .env 值，因此这是临时覆盖或测试的好选择：

Separate agent traces from app traces

Deep Agents Code 可以生成两种类型的 LangSmith 追踪：

  • - Agent traces 是 Deep Agents Code 自身的模型调用、工具调用、编排和中间件。
  • - Shell-command traces 是 Deep Agents Code 在 shell 中为您运行的代码所发出的追踪，如测试、脚本或本地 LangGraph 应用。

要将 Deep Agents Code 自身的追踪发送到专用项目，请设置 DEEPAGENTS_CODE_LANGSMITH_PROJECT:

    # Example value; use any LangSmith project name you want.
    DEEPAGENTS_CODE_LANGSMITH_PROJECT=deepagents-code

然后为您的应用追踪配置 LANGSMITH_PROJECT ：

    LANGSMITH_PROJECT=customer-support-agent

例如，假设您让 Deep Agents Code 调试一个失败的 LangGraph 测试：

    uv run pytest tests/test_escalation_flow.py

如果该测试使用启用了 LangSmith 追踪的应用运行，那些应用追踪由 shell 进程创建并发送到 customer-support-agent。Deep Agents Code 自身的推理和工具使用追踪发送到 deepagents-code.

您也可以使用 DEEPAGENTS_CODE_ 前缀将 LangSmith 凭据限定为 Deep Agents Code 专用。 (e.g., DEEPAGENTS_CODE_LANGSMITH_API_KEY).

Dual-write traces to a second project

要将代理追踪镜像到第二个 LangSmith 项目，请设置 DEEPAGENTS_CODE_LANGSMITH_REPLICA_PROJECTS。这对于将相同追踪同时发送到个人项目和共享团队项目很有用。

    DEEPAGENTS_CODE_LANGSMITH_REPLICA_PROJECTS=team-shared

设置后且追踪处于活跃状态时，每次代理运行都会写入主项目（DEEPAGENTS_CODE_LANGSMITH_PROJECT, or deepagents-code 默认为此）和您在此命名的项目。如果不设置该变量，则照常写入单个项目。

配置后，Deep Agents Code 会显示一个状态行，其中包含指向 LangSmith 项目的链接。在支持的终端中，点击链接可直接打开。您也可以使用 /trace 来打印 URL 并在浏览器中打开。

✓ LangSmith tracing: 'my-project'