1. 从一次“工具明明注册了却调不到”说起如果你正在用 Deep Agents 搭一个能自己拆任务、调工具、写文件的智能体大概率会在某个时刻卡在同一个地方create_agent和create_deep_agent这两个函数名字太像参数表又都挺长复制示例跑起来之后工具到底有没有被真正注入、子代理有没有被触发心里没底。更麻烦的是当你把MultiServerMCPClient.get_tools拉回来的工具列表直接塞进create_deep_agent有时候能跑有时候静默失败日志里只留下一句“no tool calls”排查起来非常费劲。这篇就按源码调用链把这几件事串起来MultiServerMCPClient.get_tools负责把外部 MCP 服务器的工具“借”进来create_agent是轻量构造器create_deep_agent是带规划、文件系统、子代理的重型构造器。三者不是替代关系而是流水线上的不同工位。同时我会给出一套可以直接复制的config.toml/settings.json骨架以及用 TaoToken 统一 Key 接入的步骤最后给一个验证函数调用是否真正生效的检查动作。适合已经能跑通基础 Agent、但想搞清楚参数差异和 MCP 注入细节的开发者。2. TaoToken 前置把模型入口统一成一个 Key在拆函数之前先把模型入口固定下来。Deep Agents 本身不绑定某一家模型但你在create_deep_agent里写modelclaude-sonnet-4-5-20250929或者modelopenai:gpt-4o的时候底层还是要走一个兼容 OpenAI 协议的端点。TaoToken 在这里的角色就是统一入口一个 Key、一个 Base URL模型名按需切换省得在多个平台之间来回改环境变量。接入动作分三步。第一步去控制台创建一个 API Key地址是https://taotoken.net/api-keys注意这个 deep link 已经带了utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite打开就是 Key 管理页。第二步把 Key 写进环境变量不要硬编码在代码里。第三步把 Base URL 指向https://taotoken.net/api这个地址不加 UTM直接作为base_url使用。export TAOTOKEN_API_KEYsk-你的key export OPENAI_BASE_URLhttps://taotoken.net/api export OPENAI_API_KEY$TAOTOKEN_API_KEY这样设置之后LangChain 的ChatOpenAI和 Deep Agents 内部走的 OpenAI 兼容客户端都会自动读取这两个变量。如果你用的是 Claude 系列模型同样通过这个端点转发模型名写对即可。需要确认模型列表或者临时对话测试可以打开模型对话页https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite先手动发一条消息确认 Key 有效再回到代码里跑 Agent。注意环境变量名用OPENAI_API_KEY是为了兼容 LangChain 默认读取逻辑实际值填 TaoToken 的 Key。不要同时保留其他平台的同名变量否则会互相覆盖。3. 可复制配置config.toml 与 settings.json 骨架Deep Agents 项目里通常会有两层配置一层是项目级的config.toml用来声明 MCP 服务器和默认模型另一层是编辑器或运行时的settings.json用来固定环境变量和启动参数。下面这两份骨架可以直接改路径使用。config.toml负责描述 MCP 服务器连接方式。stdio适合本地起的 Python 脚本服务streamable_http或sse适合远程服务。注意command和args要写绝对路径相对路径在不同工作目录下会找不到文件。[model] default claude-sonnet-4-5-20250929 base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [mcp.servers.math] transport stdio command python args [/abs/path/to/math_server.py] [mcp.servers.search] transport streamable_http url http://localhost:8000/mcp [agent] system_prompt 你是项目经理把复杂任务拆给子代理执行 max_iterations 25settings.json负责把环境变量和运行参数固定下来避免每次开终端都要重新 export。如果你用 VS Code 或类似编辑器可以放在.vscode/settings.json如果是独立运行时放在项目根目录由启动脚本读取。{ env: { TAOTOKEN_API_KEY: sk-你的key, OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: ${TAOTOKEN_API_KEY} }, deepagents: { checkpoint_backend: memory, interrupt_on: { delete_file: { allowed_decisions: [approve, reject] } } } }这两份配置合起来解决一个问题模型入口、MCP 服务器、中断审批策略都不散落在代码里。后面无论你调create_agent还是create_deep_agent都从配置读取改一处即可全局生效。4. 调用链拆解get_tools、create_agent、create_deep_agent 的参数差异4.1 MultiServerMCPClient.get_tools 返回的到底是什么MultiServerMCPClient初始化时接收一个字典key 是服务器别名value 是连接参数。调用get_tools()之后返回的是一个BaseTool列表LangChain 和 Deep Agents 都能直接消费。关键点在于这个列表是异步拉取的如果你在同步函数里直接调用会报错必须放在async def里await。import asyncio from langchain_mcp_adapters.client import MultiServerMCPClient async def load_tools(): client MultiServerMCPClient({ math: { command: python, args: [/abs/path/to/math_server.py], transport: stdio, }, search: { url: http://localhost:8000/mcp, transport: streamable_http, }, }) all_tools await client.get_tools() print([t.name for t in all_tools]) return all_tools tools asyncio.run(load_tools())如果你只想拿某个服务器的工具传server_namemath即可。性能敏感场景可以用client.session(math)手动管理会话生命周期避免每次调用重建连接。这一步的输出是后续两个构造函数的共同输入。4.2 create_agent 的参数面create_agent是轻量构造器核心参数就三个llm、tools、prompt。它适合任务边界清晰、工具调用轮次少的场景。所有工具调用的中间结果都会堆进上下文任务一长 token 消耗会明显上升。from langchain.agents import create_react_agent, AgentExecutor from langchain_openai import ChatOpenAI model ChatOpenAI(modelclaude-sonnet-4-5-20250929) agent create_react_agent(llmmodel, toolstools, promptprompt) executor AgentExecutor(agentagent, toolstools, verboseTrue) executor.invoke({input: 算一下 23 乘以 47})注意create_react_agent和create_openai_tools_agent是两种不同范式前者用 ReAct 提示词模板后者依赖模型的 function calling 能力。选哪个取决于你的模型是否稳定支持工具调用。4.3 create_deep_agent 的参数面与增量能力create_deep_agent在tools之外多了几个关键参数subagents用来挂载子代理interrupt_on用来定义需要人工审批的工具checkpointer用来支持中断恢复。它的内部机制是把大模型当调度器文件系统当工作内存子代理当隔离进程。from deepagents import create_deep_agent from langgraph.checkpoint.memory import MemorySaver research_subagent { name: research-agent, description: 专门负责深度研究的子代理, prompt: 你是个专业研究员会进行深入资料搜集, tools: [internet_search], model: openai:gpt-4o, } agent create_deep_agent( modelclaude-sonnet-4-5-20250929, toolstools, subagents[research_subagent], system_prompt你是项目经理把复杂任务拆给子代理做, interrupt_on{delete_file: {allowed_decisions: [approve, reject]}}, checkpointerMemorySaver(), )参数差异的本质是create_agent只解决“模型 工具”的绑定create_deep_agent额外解决“任务规划 上下文隔离 人工介入”。当你把MultiServerMCPClient.get_tools的结果传给create_deep_agent的tools参数时MCP 工具和本地工具在框架眼里没有区别都是BaseTool所以可以混用。5. 验证请求确认函数调用真的生效写完代码最怕的是“看起来跑了其实工具没被调用”。下面这个检查动作分三层从工具列表到实际调用链都能覆盖。第一层打印工具名和描述确认 MCP 工具已经注入。for t in tools: print(t.name, |, t.description[:60])第二层用astream观察事件流看是否有tool_calls字段出现。如果模型只是普通回复而没有工具调用说明提示词或工具描述不够明确。async for chunk in agent.astream({ messages: [{role: user, content: 帮我查一下 MCP 协议的最新进展}] }): if chunk.get(messages): msg chunk[messages][-1] if getattr(msg, tool_calls, None): print(触发工具调用:, [c[name] for c in msg.tool_calls]) msg.pretty_print()第三层在 MCP 服务器端加一行日志确认请求真的到达了服务。本地stdio服务可以直接在工具函数里print远程服务看访问日志。三层都通过说明从get_tools到create_deep_agent再到实际执行的链路是通的。如果你在验证过程中需要临时切换模型对比效果可以打开模型对话页https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite手动测一条确认模型本身对工具调用的支持程度再回到代码里排查。6. 本篇常见错排查报错一TypeError: object list cant be used in await expression原因是在同步上下文里调用了get_tools()。解决方式是把它包进async def用asyncio.run()或await执行。如果你在 Jupyter 里直接用await client.get_tools()即可。报错二工具列表为空get_tools()返回[]先检查 MCP 服务器的command和args路径是否为绝对路径再确认transport类型和服务器实际协议一致。stdio服务如果启动失败get_tools不会抛异常只会返回空列表。可以在终端手动执行python /abs/path/to/math_server.py看是否正常启动。报错三create_deep_agent报checkpointer is required when interrupt_on is setinterrupt_on依赖检查点来保存中断状态必须同时传checkpointer。用MemorySaver()做本地测试即可生产环境换成持久化后端。报错四子代理没有被触发检查subagents里每个字典是否包含name、description、prompt、tools四个字段。description是主代理决定是否委派任务的依据写得太模糊会导致主代理自己干活而不调用子代理。报错五模型返回 401 或invalid api key确认OPENAI_API_KEY和OPENAI_BASE_URL同时设置且没有其他平台的同名变量覆盖。TaoToken 的 Key 在控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite创建后立即生效如果仍然报错检查是否有多余空格或换行。报错六长任务跑到一半上下文爆炸这是create_agent的固有限制。把构造器换成create_deep_agent让文件系统和子代理分担上下文压力。如果任务涉及多轮工具调用优先用重型构造器。7. 接入文档与 Coding Plan把骨架落到项目里配置骨架和验证动作都跑通之后下一步是把它固化到项目结构里。建议把 MCP 服务器定义、模型入口、中断策略分别放在独立配置文件代码里只做读取和组装。这样换模型或加工具时不需要改业务逻辑。如果你打算长期用 Deep Agents 做编码类或 Agent 类任务可以看一下 Coding Plan 页面https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite里面有针对长周期任务的额度方案。接入细节和参数说明在文档页https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite遇到get_tools或create_deep_agent的参数疑问可以先查那里。控制台入口在https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteKey 管理和用量查看都在里面。最后留一个实操建议每次改完config.toml里的 MCP 服务器配置先单独跑一遍get_tools打印工具名确认注入成功再启动 Agent。这个习惯能省掉大量“Agent 不调工具”的排查时间。
1. 从一次“工具明明注册了却调不到”说起如果你正在用 Deep Agents 搭一个能自己拆任务、调工具、写文件的智能体大概率会在某个时刻卡在同一个地方create_agent和create_deep_agent这两个函数名字太像参数表又都挺长复制示例跑起来之后工具到底有没有被真正注入、子代理有没有被触发心里没底。更麻烦的是当你把MultiServerMCPClient.get_tools拉回来的工具列表直接塞进create_deep_agent有时候能跑有时候静默失败日志里只留下一句“no tool calls”排查起来非常费劲。这篇就按源码调用链把这几件事串起来MultiServerMCPClient.get_tools负责把外部 MCP 服务器的工具“借”进来create_agent是轻量构造器create_deep_agent是带规划、文件系统、子代理的重型构造器。三者不是替代关系而是流水线上的不同工位。同时我会给出一套可以直接复制的config.toml/settings.json骨架以及用 TaoToken 统一 Key 接入的步骤最后给一个验证函数调用是否真正生效的检查动作。适合已经能跑通基础 Agent、但想搞清楚参数差异和 MCP 注入细节的开发者。2. TaoToken 前置把模型入口统一成一个 Key在拆函数之前先把模型入口固定下来。Deep Agents 本身不绑定某一家模型但你在create_deep_agent里写modelclaude-sonnet-4-5-20250929或者modelopenai:gpt-4o的时候底层还是要走一个兼容 OpenAI 协议的端点。TaoToken 在这里的角色就是统一入口一个 Key、一个 Base URL模型名按需切换省得在多个平台之间来回改环境变量。接入动作分三步。第一步去控制台创建一个 API Key地址是https://taotoken.net/api-keys注意这个 deep link 已经带了utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite打开就是 Key 管理页。第二步把 Key 写进环境变量不要硬编码在代码里。第三步把 Base URL 指向https://taotoken.net/api这个地址不加 UTM直接作为base_url使用。export TAOTOKEN_API_KEYsk-你的key export OPENAI_BASE_URLhttps://taotoken.net/api export OPENAI_API_KEY$TAOTOKEN_API_KEY这样设置之后LangChain 的ChatOpenAI和 Deep Agents 内部走的 OpenAI 兼容客户端都会自动读取这两个变量。如果你用的是 Claude 系列模型同样通过这个端点转发模型名写对即可。需要确认模型列表或者临时对话测试可以打开模型对话页https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite先手动发一条消息确认 Key 有效再回到代码里跑 Agent。注意环境变量名用OPENAI_API_KEY是为了兼容 LangChain 默认读取逻辑实际值填 TaoToken 的 Key。不要同时保留其他平台的同名变量否则会互相覆盖。3. 可复制配置config.toml 与 settings.json 骨架Deep Agents 项目里通常会有两层配置一层是项目级的config.toml用来声明 MCP 服务器和默认模型另一层是编辑器或运行时的settings.json用来固定环境变量和启动参数。下面这两份骨架可以直接改路径使用。config.toml负责描述 MCP 服务器连接方式。stdio适合本地起的 Python 脚本服务streamable_http或sse适合远程服务。注意command和args要写绝对路径相对路径在不同工作目录下会找不到文件。[model] default claude-sonnet-4-5-20250929 base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [mcp.servers.math] transport stdio command python args [/abs/path/to/math_server.py] [mcp.servers.search] transport streamable_http url http://localhost:8000/mcp [agent] system_prompt 你是项目经理把复杂任务拆给子代理执行 max_iterations 25settings.json负责把环境变量和运行参数固定下来避免每次开终端都要重新 export。如果你用 VS Code 或类似编辑器可以放在.vscode/settings.json如果是独立运行时放在项目根目录由启动脚本读取。{ env: { TAOTOKEN_API_KEY: sk-你的key, OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: ${TAOTOKEN_API_KEY} }, deepagents: { checkpoint_backend: memory, interrupt_on: { delete_file: { allowed_decisions: [approve, reject] } } } }这两份配置合起来解决一个问题模型入口、MCP 服务器、中断审批策略都不散落在代码里。后面无论你调create_agent还是create_deep_agent都从配置读取改一处即可全局生效。4. 调用链拆解get_tools、create_agent、create_deep_agent 的参数差异4.1 MultiServerMCPClient.get_tools 返回的到底是什么MultiServerMCPClient初始化时接收一个字典key 是服务器别名value 是连接参数。调用get_tools()之后返回的是一个BaseTool列表LangChain 和 Deep Agents 都能直接消费。关键点在于这个列表是异步拉取的如果你在同步函数里直接调用会报错必须放在async def里await。import asyncio from langchain_mcp_adapters.client import MultiServerMCPClient async def load_tools(): client MultiServerMCPClient({ math: { command: python, args: [/abs/path/to/math_server.py], transport: stdio, }, search: { url: http://localhost:8000/mcp, transport: streamable_http, }, }) all_tools await client.get_tools() print([t.name for t in all_tools]) return all_tools tools asyncio.run(load_tools())如果你只想拿某个服务器的工具传server_namemath即可。性能敏感场景可以用client.session(math)手动管理会话生命周期避免每次调用重建连接。这一步的输出是后续两个构造函数的共同输入。4.2 create_agent 的参数面create_agent是轻量构造器核心参数就三个llm、tools、prompt。它适合任务边界清晰、工具调用轮次少的场景。所有工具调用的中间结果都会堆进上下文任务一长 token 消耗会明显上升。from langchain.agents import create_react_agent, AgentExecutor from langchain_openai import ChatOpenAI model ChatOpenAI(modelclaude-sonnet-4-5-20250929) agent create_react_agent(llmmodel, toolstools, promptprompt) executor AgentExecutor(agentagent, toolstools, verboseTrue) executor.invoke({input: 算一下 23 乘以 47})注意create_react_agent和create_openai_tools_agent是两种不同范式前者用 ReAct 提示词模板后者依赖模型的 function calling 能力。选哪个取决于你的模型是否稳定支持工具调用。4.3 create_deep_agent 的参数面与增量能力create_deep_agent在tools之外多了几个关键参数subagents用来挂载子代理interrupt_on用来定义需要人工审批的工具checkpointer用来支持中断恢复。它的内部机制是把大模型当调度器文件系统当工作内存子代理当隔离进程。from deepagents import create_deep_agent from langgraph.checkpoint.memory import MemorySaver research_subagent { name: research-agent, description: 专门负责深度研究的子代理, prompt: 你是个专业研究员会进行深入资料搜集, tools: [internet_search], model: openai:gpt-4o, } agent create_deep_agent( modelclaude-sonnet-4-5-20250929, toolstools, subagents[research_subagent], system_prompt你是项目经理把复杂任务拆给子代理做, interrupt_on{delete_file: {allowed_decisions: [approve, reject]}}, checkpointerMemorySaver(), )参数差异的本质是create_agent只解决“模型 工具”的绑定create_deep_agent额外解决“任务规划 上下文隔离 人工介入”。当你把MultiServerMCPClient.get_tools的结果传给create_deep_agent的tools参数时MCP 工具和本地工具在框架眼里没有区别都是BaseTool所以可以混用。5. 验证请求确认函数调用真的生效写完代码最怕的是“看起来跑了其实工具没被调用”。下面这个检查动作分三层从工具列表到实际调用链都能覆盖。第一层打印工具名和描述确认 MCP 工具已经注入。for t in tools: print(t.name, |, t.description[:60])第二层用astream观察事件流看是否有tool_calls字段出现。如果模型只是普通回复而没有工具调用说明提示词或工具描述不够明确。async for chunk in agent.astream({ messages: [{role: user, content: 帮我查一下 MCP 协议的最新进展}] }): if chunk.get(messages): msg chunk[messages][-1] if getattr(msg, tool_calls, None): print(触发工具调用:, [c[name] for c in msg.tool_calls]) msg.pretty_print()第三层在 MCP 服务器端加一行日志确认请求真的到达了服务。本地stdio服务可以直接在工具函数里print远程服务看访问日志。三层都通过说明从get_tools到create_deep_agent再到实际执行的链路是通的。如果你在验证过程中需要临时切换模型对比效果可以打开模型对话页https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite手动测一条确认模型本身对工具调用的支持程度再回到代码里排查。6. 本篇常见错排查报错一TypeError: object list cant be used in await expression原因是在同步上下文里调用了get_tools()。解决方式是把它包进async def用asyncio.run()或await执行。如果你在 Jupyter 里直接用await client.get_tools()即可。报错二工具列表为空get_tools()返回[]先检查 MCP 服务器的command和args路径是否为绝对路径再确认transport类型和服务器实际协议一致。stdio服务如果启动失败get_tools不会抛异常只会返回空列表。可以在终端手动执行python /abs/path/to/math_server.py看是否正常启动。报错三create_deep_agent报checkpointer is required when interrupt_on is setinterrupt_on依赖检查点来保存中断状态必须同时传checkpointer。用MemorySaver()做本地测试即可生产环境换成持久化后端。报错四子代理没有被触发检查subagents里每个字典是否包含name、description、prompt、tools四个字段。description是主代理决定是否委派任务的依据写得太模糊会导致主代理自己干活而不调用子代理。报错五模型返回 401 或invalid api key确认OPENAI_API_KEY和OPENAI_BASE_URL同时设置且没有其他平台的同名变量覆盖。TaoToken 的 Key 在控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite创建后立即生效如果仍然报错检查是否有多余空格或换行。报错六长任务跑到一半上下文爆炸这是create_agent的固有限制。把构造器换成create_deep_agent让文件系统和子代理分担上下文压力。如果任务涉及多轮工具调用优先用重型构造器。7. 接入文档与 Coding Plan把骨架落到项目里配置骨架和验证动作都跑通之后下一步是把它固化到项目结构里。建议把 MCP 服务器定义、模型入口、中断策略分别放在独立配置文件代码里只做读取和组装。这样换模型或加工具时不需要改业务逻辑。如果你打算长期用 Deep Agents 做编码类或 Agent 类任务可以看一下 Coding Plan 页面https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite里面有针对长周期任务的额度方案。接入细节和参数说明在文档页https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite遇到get_tools或create_deep_agent的参数疑问可以先查那里。控制台入口在https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteKey 管理和用量查看都在里面。最后留一个实操建议每次改完config.toml里的 MCP 服务器配置先单独跑一遍get_tools打印工具名确认注入成功再启动 Agent。这个习惯能省掉大量“Agent 不调工具”的排查时间。
