1. 从零搭建 AI 智能体为什么你的 Agent 总是跑不通很多人第一次接触 AI 智能体脑子里想的是一套能自己规划、自己调工具、自己反思的系统。但真动手写起来往往卡在最前面一步模型接口调不通。你手里可能有三四个平台的 KeyOpenAI 的、Claude 的、国产模型的每个平台的 SDK 不一样鉴权方式不一样返回格式也不一样。写一个智能体光适配模型接口就花掉两天真正核心的 RAG、Function Calling、MCP 编排反而没时间打磨。我试过最笨的办法给每个模型写一个 adapter 类用 if-else 判断走哪个平台。结果就是代码里到处是平台判断加一个新模型就要改五六个文件。后来换成统一 API 网关的思路所有模型走同一个 Base URL、同一个 Key、同一套 OpenAI 兼容格式智能体代码里只认一个 client切换模型只改一个 Model ID 字符串。这才把精力拉回到架构本身。这篇内容面向的是想从零搭一套可跑通智能体系统的开发者。核心检索词就三个AI 智能体、大模型接入、RAG 与 Function Calling 编排。适合谁适合已经会写 Python、了解基本 HTTP 请求、但还没把智能体链路完整跑通的开发者。我会先讲清楚 9 大核心技术各自解决什么问题再给出一套可复制的统一 API 通道配置最后带你本地验证一条完整的调用链路模型接入 → 工具注册 → Function Calling → 结果回填。9 大核心技术不是并列关系而是有层次的。底层是模型接入和协议层MCP、A2A、AG-UI中间是能力层RAG、Fine-tuning、Function Calling上层是编排层WorkFlow、Agentic AI 多智能体协同。你不需要一次全上但要知道每一层缺了会出什么问题。比如只做 Function Calling 不做 WorkFlow智能体就会在复杂任务里乱跳只做 RAG 不做 MCP工具接入就是硬编码扩展性很差。下面按这个层次展开每一节都尽量给到能直接用的配置和代码。2. TaoToken 统一 API 通道智能体接入的前置配置2.1 为什么智能体架构需要一个统一入口智能体系统和普通 Chatbot 最大的区别是它会在一次任务执行中多次调用模型而且可能调用不同能力的模型。规划阶段用推理强的模型工具参数生成用 Function Calling 稳定的模型最终回答用便宜快速的模型。如果每个模型都单独配 Key、单独写 client代码会迅速膨胀。统一 API 通道解决的就是这个问题一个 Base URL、一个 API Key、一套 OpenAI 兼容协议通过 Model ID 区分不同模型。你的智能体代码里只需要一个OpenAIclient 实例切换模型就是改一个字符串。这对后面做 WorkFlow 编排和多智能体协同特别重要因为编排层不应该关心底层是哪个平台。TaoToken 在这里的角色是提供统一的模型接入通道。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置时直接用这个。2.2 获取 Key 与模型列表进入控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建后复制 Key格式通常是sk-开头。然后在模型列表页确认你要用的 Model ID比如做 Function Calling 就选支持 tools 参数的模型做 RAG 问答就选上下文窗口大的模型。这一步不要跳过。很多人配置完发现 401就是因为 Key 没复制全或者用了错误的 Base URL。记住两个地址的区别网页控制台带 UTMAPI 调用地址不带。2.3 环境变量配置不要把 Key 硬编码在代码里。用环境变量export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-...。配置完可以用echo $TAOTOKEN_API_KEY确认。2.4 智能体项目的依赖安装pip install openai1.30.0 httpx pydantic如果你要跑 RAG再加pip install numpy要跑本地向量检索加pip install faiss-cpu。MCP 相关后面单独说。3. 可复制配置智能体接入 settings 与 Function Calling 注册3.1 统一 client 配置片段新建agent_config.py写入以下配置。这是整个智能体系统的接入基座import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) # 不同任务用不同模型只改这个映射表 MODEL_MAP { planner: claude-3-5-sonnet-20241022, # 规划用推理强的 tool_caller: gpt-4o-mini, # 工具调用用稳定的 summarizer: deepseek-chat, # 总结用便宜的 } def get_model(role: str) - str: return MODEL_MAP.get(role, gpt-4o-mini)这段配置的关键点Base URL 指向https://taotoken.net/api不带任何多余路径。OpenAI SDK 会自动拼接/chat/completions。如果你手动拼 URL很容易多一个斜杠导致 404。3.2 Function Calling 工具注册Function Calling 是智能体“动手”的核心。下面定义一个查天气的工具并注册到请求里import json tools [ { type: function, function: { name: get_current_weather, description: 获取指定城市的实时天气, parameters: { type: object, properties: { location: { type: string, description: 城市名称例如北京, }, unit: { type: string, enum: [celsius, fahrenheit], }, }, required: [location], }, }, } ] def call_model_with_tools(user_input: str): response client.chat.completions.create( modelget_model(tool_caller), messages[{role: user, content: user_input}], toolstools, tool_choiceauto, ) return response注意tool_choiceauto让模型自己决定是否调用工具。如果你强制调用用{type: function, function: {name: get_current_weather}}。3.3 MCP 配置片段TOML 格式MCP 是 2025 年智能体架构里绕不开的协议。它统一了模型和外部工具、数据源的通信标准。下面是一个 MCP Server 的配置示例放在mcp_config.toml[mcp_servers.filesystem] command npx args [-y, modelcontextprotocol/server-filesystem, /Users/yourname/agent_workspace] [mcp_servers.fetch] command uvx args [mcp-server-fetch] [agent] base_url https://taotoken.net/api model claude-3-5-sonnet-20241022这个配置里filesystemserver 让智能体可以读写本地工作目录fetchserver 让它能抓取网页。[agent]段指定模型走统一通道。MCP 的 Host-Client-Server 架构里你的智能体是 Host每个 server 是一个能力单元。3.4 RAG 检索层的最小配置RAG 的核心是把文档转成向量查询时做语义匹配。这里给一个不依赖外部向量数据库的最小实现import numpy as np def simple_rag_retrieve(query: str, docs: list[str], top_k: int 3): # 实际项目用 embedding 模型这里用关键词重叠做演示 scores [] for doc in docs: overlap len(set(query) set(doc)) scores.append(overlap) idx np.argsort(scores)[::-1][:top_k] return [docs[i] for i in idx]生产环境要把这里换成 embedding 向量库但检索逻辑是一样的query 转向量和文档向量算相似度取 top_k 拼进 prompt。4. 验证请求跑通智能体调用链路4.1 第一步验证模型通道先写一个最小请求确认 Key 和 Base URL 正确from agent_config import client, get_model resp client.chat.completions.create( modelget_model(summarizer), messages[{role: user, content: 用一句话解释什么是 AI 智能体}], ) print(resp.choices[0].message.content)如果返回正常文本说明通道通了。如果报 401检查 Key如果报local proxy failed检查 Base URL 是否写成了https://taotoken.net/api/末尾斜杠有时会导致问题去掉。4.2 第二步验证 Function Calling 完整链路这一步要跑通“模型识别需求 → 返回工具调用 → 你执行工具 → 回填结果 → 模型生成最终回答”的完整循环import json def run_agent_loop(user_input: str): messages [{role: user, content: user_input}] response client.chat.completions.create( modelget_model(tool_caller), messagesmessages, toolstools, tool_choiceauto, ) msg response.choices[0].message if msg.tool_calls: for tool_call in msg.tool_calls: fn_name tool_call.function.name args json.loads(tool_call.function.arguments) print(f模型请求调用: {fn_name}, 参数: {args}) # 模拟工具执行 if fn_name get_current_weather: result json.dumps({location: args[location], temp: 23°C, condition: 晴}) else: result json.dumps({error: unknown tool}) messages.append(msg) messages.append({ role: tool, tool_call_id: tool_call.id, content: result, }) final client.chat.completions.create( modelget_model(tool_caller), messagesmessages, ) return final.choices[0].message.content return msg.content print(run_agent_loop(今天北京天气怎么样))预期输出模型先返回一个tool_calls里面包含get_current_weather和{location: 北京}然后你回填结果模型生成类似“北京今天晴23°C”的回答。如果模型直接回答而没有调用工具检查tools参数是否传对以及模型是否支持 Function Calling。4.3 第三步验证 RAG 工具混合链路真实智能体往往需要先检索知识库再决定是否调工具。把 RAG 检索结果拼进 system promptdocs [ 北京今天晴气温 23°C湿度 45%。, 上海今天多云气温 26°C。, 广州今天有雨气温 28°C。, ] def rag_agent(query: str): context simple_rag_retrieve(query, docs) system_prompt f你可以参考以下资料回答\n{chr(10).join(context)} messages [ {role: system, content: system_prompt}, {role: user, content: query}, ] resp client.chat.completions.create( modelget_model(summarizer), messagesmessages, ) return resp.choices[0].message.content print(rag_agent(北京天气如何))这条链路验证的是检索层拿到相关文档 → 拼进上下文 → 模型基于资料回答。如果模型回答里出现了资料中没有的信息说明 RAG 没生效检查 context 是否真的拼进去了。4.4 成功结果对照跑通后你应该看到三个层级的输出纯模型对话返回文本Function Calling 返回工具调用请求和最终回答RAG 返回基于检索资料的回答。这三条链路合起来就是智能体系统的最小可运行骨架。后面加 WorkFlow 编排、多智能体协同、MCP 工具扩展都是在这个骨架上长出来的。5. 常见报错排查401、local proxy failed、reading choices、OAuth5.1 401 Unauthorized最常见。原因通常是 Key 没设置、Key 复制不完整、或者环境变量没生效。排查步骤先echo $TAOTOKEN_API_KEY确认输出再检查代码里是否真的读了环境变量最后确认 Key 没有多余空格。如果用的是.env文件确认加载顺序在 client 初始化之前。5.2 local proxy failed这个报错通常和 Base URL 配置有关。检查base_url是否写成了https://taotoken.net/api不要加/v1或其他路径。OpenAI SDK 会自己拼/chat/completions。另外确认本机没有设置HTTP_PROXY或HTTPS_PROXY环境变量指向一个不可用的地址有的话先unset。5.3 reading choices 相关报错典型报错是TypeError: NoneType object is not subscriptable或KeyError: choices。这说明返回体结构和你预期的不一样。先打印完整 responseresp client.chat.completions.create(...) print(resp.model_dump_json(indent2))如果choices为空可能是模型返回了错误信息但被 SDK 包装了。检查resp.error字段。常见原因是 Model ID 写错或者该模型不支持你传的参数比如传了tools但模型不支持。5.4 OAuth 与鉴权类报错如果你在 MCP 配置里用了需要 OAuth 的远程 server报错通常是OAuth token expired或invalid_client。MCP 的远程 server 鉴权走 OAuth 流程本地 server 一般不需要。排查时先确认 server 是本地命令还是远程 URL。本地命令npx、uvx不走 OAuth远程 URL 需要检查 token 是否过期。Claude Code 接入时如果报 OAuth 错误检查~/.claude/settings.json里的配置{ apiKey: sk-你的Key, baseURL: https://taotoken.net/api, model: claude-3-5-sonnet-20241022 }这三件套Base URL Key Model ID缺一不可。Cline MCP 配置同理在cline_mcp_settings.json里写全这三个字段。Codex 的auth.json也是同样结构。5.5 工具调用参数解析失败报错json.decoder.JSONDecodeError说明模型返回的arguments不是合法 JSON。这种情况通常出现在模型能力不足或 prompt 太模糊时。解决办法在 tool 的 description 里写清楚参数格式或者换一个 Function Calling 更稳定的模型。实测下来gpt-4o-mini和claude-3-5-sonnet在工具参数生成上比较稳。6. 智能体学习路线与统一通道的长期用法9 大核心技术不需要一次全学完。合理的路线是先跑通模型接入和 Function Calling这是最小可用智能体然后加 RAG让智能体能基于私有知识回答接着上 MCP把工具接入标准化最后做 WorkFlow 和多智能体协同处理复杂任务。Fine-tuning 和 A2A、AG-UI 可以按需再深入。统一 API 通道的价值在长期。当你从单模型切换到多模型协作时不需要重写接入层当你从本地脚本迁移到 Coding Plan 或 Agent 平台时Base URL 和 Key 直接复用。如果你要做长期编码类智能体可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。需要管理多个 Key 或查看用量进控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建新 Key 在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各语言 SDK 的完整示例。想直接验证模型对话效果用模型对话页https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Claude Code 接入 Anthropic 兼容通道的配置参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。这个页面给了完整的 settings 片段和前面 §5.4 里的三件套一致。最后给一个实用建议把agent_config.py里的MODEL_MAP当成你智能体的“模型路由表”。规划、工具调用、总结、嵌入各用哪个模型写清楚注释。这样三个月后你回来看代码不用猜当时为什么选这个模型。智能体架构的复杂度不在模型本身而在编排和状态管理。统一通道帮你把接入层的复杂度降到最低剩下的精力留给 RAG 检索质量、工具描述精度和 WorkFlow 的异常处理。这三块才是决定智能体能不能真正干活的关键。