1. 先把“智能体”这个词拆开看五大件缺一不可很多人把套了个角色提示词的聊天页叫 AI 智能体这其实混淆了「会聊天」和「能办事」。我理解的 AI 智能体是能围绕一个目标自己拆步骤、自己决定调哪个工具、拿到结果后还能判断要不要再来一轮的程序。它至少由五块拼起来多轮对话与记忆、工具使用、Function Calling、MCP、自我规划与反思CoT/ReAct。前两块决定它「像不像人」后三块决定它「能不能把事办成」。这篇不空谈概念直接面向正在搭原型的开发者交付一条能在本地跑通的完整调用链用统一 API 通道拿到模型能力用 Function Calling 让模型「说」出要调什么用 MCP 在工程侧「做」出真实调用再用 ReAct 循环把结果喂回去。中间会给出可复制的settings.json与config.toml骨架以及 MCP 接入和 Function Calling 的验证动作。适合已经会写一点 Python、但被各家模型接口和工具适配折腾过的人。先说清楚一个容易混的点Function Calling 和 MCP 不是替代关系。Function Calling 是大模型返回「我要调用 search_web参数是 query 和 limit」这种结构化指令的能力是「说」MCP 是工程侧统一执行工具调用的协议是「做」。模型不会 Function Calling它连 MCP 工具都点不动只有 Function Calling 没有 MCP你就得为每个工具手写适配。两者配合才是省事的关键。2. 前置准备用 TaoToken 统一 API 通道收口模型调用搭智能体最烦的不是写循环是每换一个模型就改一遍 base_url、key 和参数格式。我的做法是先用一个统一 API 通道把模型调用收口业务代码只认一个入口。TaoToken 在这里扮演的就是这个通道角色官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM。它兼容 OpenAI 风格的接口所以 Function Calling 的tools字段能直接透传省掉一层转换。你需要先拿到 key。进控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 然后在 API Keys 页面生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。生成后复制那串sk-开头的字符串只显示一次丢了就重建。想先确认模型通不通可以直接在模型对话页试一句https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。注意key 不要写进会提交到 git 的文件。用环境变量或本地.env并且把.env加进.gitignore。我见过有人把 key 硬编码进settings.json推到公开仓库几分钟就被扫走。环境上Python 3.10 即可装两个包openai用于走兼容接口mcp用于接 MCP Server。命令如下python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install openai mcp python-dotenv3. 可复制配置settings.json 与 config.toml 骨架配置分两层一层是模型通道一层是 MCP 工具。模型通道我用settings.json存非敏感项key 走环境变量MCP 用config.toml声明要挂载哪些 Server。这样换模型只动 json加工具只动 toml。先看settings.json{ model_provider: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, default_model: gpt-4o-mini, timeout_seconds: 60, max_retries: 2 }, agent: { max_react_steps: 6, enable_function_calling: true, enable_mcp: true, memory_window: 8 } }base_url指向统一通道api_key_env说明 key 从环境变量读不落盘。max_react_steps是 ReAct 循环上限防止模型在「思考-行动」里打转烧 token。memory_window控制只带最近 8 轮对话避免上下文无限膨胀。再看config.toml声明一个文件系统 MCP Server 和一个搜索类 Server[ mcp_servers.filesystem ] command npx args [-y, modelcontextprotocol/server-filesystem, ./workspace] enabled true [ mcp_servers.search ] command npx args [-y, modelcontextprotocol/server-brave-search] env { BRAVE_API_KEY ${BRAVE_API_KEY} } enabled false [ mcp_client ] call_timeout_seconds 30 tool_refresh_interval 300commandargs是启动 MCP Server 的方式enabled控制开关。tool_refresh_interval表示每 300 秒重新拉一次工具列表适合工具会动态增减的场景。把 key 用${VAR}引用运行时从环境注入。设置环境变量export TAOTOKEN_API_KEYsk-你的key export BRAVE_API_KEY你的搜索key4. 跑通调用链Function Calling 验证 MCP 接入 ReAct 循环配置就位后先单独验证 Function Calling确认模型真的会「说」出工具调用而不是把 JSON 当普通文本吐出来。下面这段最小代码定义了一个get_weather工具走统一通道请求import os, json from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY], ) tools [{ type: function, function: { name: get_weather, description: 查询指定城市的当前天气, parameters: { type: object, properties: { city: {type: string, description: 城市名如 杭州} }, required: [city] } } }] resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 杭州现在天气怎么样}], toolstools, tool_choiceauto, ) msg resp.choices[0].message print(finish_reason:, resp.choices[0].finish_reason) print(tool_calls:, msg.tool_calls)跑通后你会看到finish_reason是tool_callsmsg.tool_calls里带着get_weather和{city: 杭州}。这一步成功说明通道和 Function Calling 都通了。如果finish_reason是stop且内容是一段解释文字多半是模型没被正确引导检查tools结构是否完整。接着接 MCP。用官方客户端连上config.toml里声明的 Server把工具列表拉出来再和 Function Calling 的tools合并import asyncio, json from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def load_mcp_tools(): params StdioServerParameters( commandnpx, args[-y, modelcontextprotocol/server-filesystem, ./workspace], ) async with stdio_client(params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() listed await session.list_tools() return [ { type: function, function: { name: t.name, description: t.description, parameters: t.inputSchema, }, } for t in listed.tools ] mcp_tools asyncio.run(load_mcp_tools()) print(MCP 工具数:, len(mcp_tools))list_tools()返回的inputSchema本身就是 JSON Schema能直接塞进 Function Calling 的parameters这就是 MCP 省事的地方——工具描述不用你手写。合并后把tools传给模型模型「说」要调哪个工程侧就用session.call_tool(name, arguments)去「做」。最后是 ReAct 循环把「思考-行动-观察」串起来。核心逻辑是请求模型 → 若有tool_calls就执行 → 把工具结果作为role: tool的消息追加 → 再请求模型直到没有工具调用或达到max_react_stepsasync def react_loop(session, user_input, tools, max_steps6): messages [{role: user, content: user_input}] for step in range(max_steps): resp client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolstools ) msg resp.choices[0].message messages.append(msg) if not msg.tool_calls: return msg.content for call in msg.tool_calls: args json.loads(call.function.arguments) result await session.call_tool(call.function.name, args) messages.append({ role: tool, tool_call_id: call.id, content: str(result.content), }) return 达到最大步数未收敛这段就是 ReAct 的工程化落地thought藏在模型的推理里action是tool_callsobservation是role: tool的回填。CoT 则体现在提示词里你可以在 system 消息加一句「先分步思考再决定是否调用工具」让模型把拆解过程显式化。5. 本篇常见错排查报错一401 Unauthorized或invalid api key。先确认环境变量真的注入了echo $TAOTOKEN_API_KEY看有没有值。常见坑是.env写了但没load_dotenv()或者 key 前后带了空格和引号。另外确认base_url结尾没有多余的/v1统一通道用https://taotoken.net/api即可。报错二finish_reason一直是stop模型不调工具。检查tools里parameters是否是合法 JSON Schemarequired字段名和properties是否对得上。描述写得太模糊也会导致模型不调把description写具体比如「查询指定城市的当前天气输入城市中文名」。报错三MCP Server 起不来npx报找不到包。确认本机 Node.js 版本在 18 以上npx -y的-y不能省否则会卡在交互确认。路径参数./workspace要真实存在否则文件系统 Server 会直接退出。报错四ReAct 循环停不下来一直调工具。大概率是工具返回内容为空或格式异常模型拿不到有效观察就反复重试。给max_react_steps设个硬上限同时在工具执行处加异常捕获把错误信息也作为role: tool回填让模型知道「这条路走不通」。报错五上下文超长。记忆窗口别只增不减按memory_window截断历史工具返回的大段内容先做摘要再回填。我试过把整个文件内容塞回去两轮就爆了。6. 把通道、工具、循环固定成模板后面只换零件搭智能体原型最耗时的从来不是算法是接口适配和工具对接。把模型调用收口到统一 API 通道把工具接入收口到 MCP把决策循环固定成 ReAct 模板之后你要做的就只是换模型、加工具、调提示词。Function Calling 负责让模型「说」MCP 负责让工程「做」CoT 和 ReAct 负责让整个过程有规划、能反思这五块拼齐一个能办事的智能体才算立住。如果你要长期跑编码类或 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 。Claude Code 相关的接入配置参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。先把上面那条最小调用链跑通再往上叠工具比一上来就搭大框架稳得多。