1. 从零构建 Code Agent 的真实起点为什么“能跑”和“能稳”是两回事很多人第一次接触 Claude Code 这类工具时最直观的感受是“它怎么什么都能干”。但当你真正动手从零构建一个 Code Agent才会发现核心难点从来不是让模型开口说话而是让它稳定地完成“读文件、搜代码、改代码、跑命令”这一整套动作。我试过直接拿一个通用对话模型套上几个工具函数就开跑结果前几轮还挺像样任务一复杂就开始胡言乱语——要么把文件路径写错要么在同一个报错上反复撞墙。这个场景下你需要的是一个可对话、可执行工具、可追溯的本地 Code Agent。它至少要具备四个能力第一能理解自然语言需求并拆解成步骤第二能调用文件系统、搜索、终端等工具去仓库里找证据第三能输出可落地的补丁并安全执行第四能在长对话中保持上下文不腐烂。而这一切的底座是模型调用通道的稳定性。我选择用 TaoToken 作为统一 Key 接入层原因很直接本地开发 Agent 时最烦的就是在多个模型供应商之间来回切换配置。TaoToken 提供统一的 API 入口兼容 OpenAI 风格的 Function Calling 协议这意味着我的 Agent 主循环不需要为每个模型写适配层。你可以在 https://taotoken.net/api 拿到兼容接口配合 https://taotoken.net/api-keys 生成的 Key 就能直接调用。这一章先不急着写代码而是把整个链路的骨架讲清楚。一个 Code Agent 的最小闭环包含五个模块LLM 调用层、工具注册中心、ReAct 主循环、上下文管理器、执行器。LLM 调用层负责把消息和工具 Schema 发给模型工具注册中心维护所有可调用工具的 JSON SchemaReAct 主循环负责“模型输出 tool_calls → 执行工具 → 回填结果 → 继续推理”这个循环上下文管理器负责截断、压缩、分层执行器负责把模型生成的补丁安全落盘。很多教程一上来就让你写几百行代码但真正卡住新手的往往是环境配置和协议对齐。比如 Function Calling 要求模型返回结构化的 tool_calls而不是自由文本。如果你用的是字符串解析那套 ReAct模型多说一句“好的我来帮你”就会导致正则匹配失败。所以从第一天起我就建议你直接走 Function Calling 协议把“模型输出”当成结构化数据来处理而不是当成作文来批改。还有一个容易被忽略的点工具返回结果必须统一格式。如果 Read 工具返回纯文本Grep 工具返回 JSON模型就得花额外精力去“理解”每个工具的输出结构。更好的做法是定义一个标准信封包含 status、data、text、stats 四个字段。模型看到 status 就知道成功还是失败看到 data 就能直接取结构化数据看到 text 就能拿到人类可读的摘要。这个设计在后面做上下文压缩时会省下大量精力。最后说说为什么强调“从零”。因为只有你自己搭一遍才会真正理解 Claude Code 这类产品在工程上做对了什么。它不是模型更聪明而是工具边界更清晰、调用协议更严格、上下文治理更精细。你把这些工程细节补齐哪怕用同一个模型Agent 的稳定性也会有肉眼可见的提升。2. TaoToken 统一 Key 接入前置把模型调用通道先跑通在写 Agent 主循环之前必须先把模型调用通道跑通。这一步看起来简单但实际踩坑的人不少。TaoToken 的接入方式兼容 OpenAI 的 Chat Completions 接口所以你不需要引入额外的 SDK直接用 openai 这个 Python 包就能调用。关键是把 base_url 指向 https://taotoken.net/api而不是默认的 OpenAI 地址。先安装依赖。我建议用虚拟环境避免和系统里的包冲突python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install openai httpx然后配置环境变量。不要把 Key 硬编码在代码里这是基本的安全习惯export TAOTOKEN_API_KEY你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Windows PowerShell换成$env:TAOTOKEN_API_KEY你的Key。配置完成后写一个最小调用脚本验证通道是否通畅import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[{role: user, content: 用一句话说明什么是 Function Calling}], ) print(resp.choices[0].message.content)如果这一步能打印出正常回答说明 Key 和通道都没问题。接下来要验证的是 Function Calling 是否可用。这是 Code Agent 的核心能力必须提前确认。写一个带工具定义的请求tools [ { type: function, function: { name: read_file, description: 读取指定路径的文件内容, parameters: { type: object, properties: { path: {type: string, description: 文件相对路径} }, required: [path], }, }, } ] resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messages[{role: user, content: 帮我读取 README.md}], toolstools, tool_choiceauto, ) msg resp.choices[0].message print(tool_calls:, msg.tool_calls)如果返回的 message 里包含 tool_calls 字段并且 function.name 是 read_file说明 Function Calling 链路正常。这一步非常关键因为后面整个 Agent 主循环都依赖这个协议。如果这里返回的是纯文本而不是 tool_calls说明模型或通道不支持结构化调用需要换模型或检查参数。关于模型选择TaoToken 支持多种模型 ID。对于 Code Agent 场景我建议优先选支持长上下文和 Function Calling 的模型。你可以在 https://taotoken.net/models 查看可用模型列表。实际测试下来Claude 系列在工具调用稳定性上表现不错适合作为主循环的推理模型。还有一个细节超时和重试。本地开发时网络波动很常见建议给 client 配置合理的超时时间并加一层简单的重试逻辑client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], timeout60.0, max_retries2, )这样即使偶发超时Agent 也不会直接崩溃。把这一层封装成一个 LLMClient 类后面主循环里只调用这个类的方法方便统一管理。3. 可复制配置Agent 主循环与工具注册的完整骨架这一章给出可以直接复制的配置和代码骨架。先定义项目结构建议这样组织my_code_agent/ ├── agent/ │ ├── __init__.py │ ├── llm_client.py # 模型调用封装 │ ├── registry.py # 工具注册中心 │ ├── loop.py # ReAct 主循环 │ └── context.py # 上下文管理 ├── tools/ │ ├── __init__.py │ ├── read.py │ ├── grep.py │ └── edit.py ├── config/ │ └── settings.json └── main.py先写工具注册中心。它的职责是维护工具名到函数的映射并自动生成 JSON Schema# agent/registry.py import json from typing import Callable, Any class ToolRegistry: def __init__(self): self._tools: dict[str, dict] {} def register(self, name: str, description: str, parameters: dict, func: Callable): self._tools[name] { schema: { type: function, function: { name: name, description: description, parameters: parameters, }, }, func: func, } def get_schemas(self) - list[dict]: return [t[schema] for t in self._tools.values()] def execute(self, name: str, args: dict) - Any: if name not in self._tools: return {status: error, text: f未知工具: {name}} try: return self._tools[name][func](**args) except Exception as e: return {status: error, text: f工具执行失败: {e}}接着写一个 Read 工具作为示例。注意返回统一信封# tools/read.py import os def read_file(path: str, max_lines: int 500) - dict: if not os.path.exists(path): return {status: error, text: f文件不存在: {path}} with open(path, r, encodingutf-8, errorsignore) as f: lines f.readlines() truncated len(lines) max_lines content .join(lines[:max_lines]) return { status: partial if truncated else success, data: {content: content, total_lines: len(lines)}, text: f读取 {path}共 {len(lines)} 行 (已截断 if truncated else ), }然后在 main.py 里注册工具并启动主循环# main.py import os from openai import OpenAI from agent.registry import ToolRegistry from tools.read import read_file client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) registry ToolRegistry() registry.register( nameread_file, description读取指定路径的文件内容, parameters{ type: object, properties: { path: {type: string, description: 文件相对路径}, max_lines: {type: integer, description: 最大读取行数}, }, required: [path], }, funcread_file, ) def run_agent(user_input: str, max_steps: int 10): messages [ {role: system, content: 你是一个代码助手可以调用工具读取文件。}, {role: user, content: user_input}, ] for step in range(max_steps): resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messagesmessages, toolsregistry.get_schemas(), tool_choiceauto, ) 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 registry.execute(call.function.name, args) messages.append({ role: tool, tool_call_id: call.id, content: json.dumps(result, ensure_asciiFalse), }) return 达到最大步数限制 if __name__ __main__: print(run_agent(读取 README.md 并总结内容))这段代码就是 Agent 的最小闭环。你可以直接复制运行只要环境变量配好就能看到模型调用 read_file 工具并返回结果。注意 messages 里 assistant 消息必须原样 appendtool 消息必须带 tool_call_id这是 Function Calling 协议的硬要求。如果你用的是 Claude Code 类工具做本地开发可能还会涉及 settings.json 配置。比如在项目根目录放一个 config/settings.json{ model: claude-sonnet-4-20250514, base_url: https://taotoken.net/api, max_steps: 20, tool_output_max_lines: 2000, tool_output_max_bytes: 51200 }这个配置文件后面可以扩展成支持 MCP 服务器列表、Skills 目录等。把配置和代码分离改参数时不用动主逻辑。4. 验证请求与成功结果一次端到端工具调用实测配置写完后必须做一次端到端验证。我设计一个最小但完整的测试场景让 Agent 读取当前目录下的一个 Python 文件统计函数数量并输出结果。这个任务需要模型调用 read_file 工具拿到内容后自己分析最后给出答案。准备一个测试文件 demo.pydef foo(): pass def bar(): return 1 class Baz: def method(self): pass然后运行 Agentprint(run_agent(读取 demo.py告诉我里面有几个函数定义))预期流程是这样的第一轮模型返回 tool_calls调用 read_file参数 path 为 demo.py。你的代码执行工具把文件内容回填到 messages。第二轮模型拿到内容后不再调用工具直接输出类似“demo.py 中有 2 个顶层函数定义foo 和 bar另外 Baz 类里有一个 method 方法”的回答。如果这一步成功说明整条链路是通的TaoToken 通道正常、Function Calling 协议正常、工具注册和执行正常、消息回填正常。这是从零构建 Code Agent 的第一个里程碑。接下来验证多步调用。让 Agent 先列目录再读文件print(run_agent(先看看当前目录有哪些文件然后读取 main.py 的前 20 行))这个任务需要模型连续调用两次工具。第一次可能是 list_dir第二次是 read_file。你要观察 messages 数组是否正确累积tool_call_id 是否一一对应。如果模型在第二轮忘记之前的工具结果说明消息回填有问题。实测下来最容易出错的点是 arguments 的 JSON 解析。模型有时会返回带换行或多余空格的 JSON 字符串直接 json.loads 可能失败。建议加一层容错def safe_parse_args(raw: str) - dict: try: return json.loads(raw) except json.JSONDecodeError: # 尝试去掉尾部多余字符 raw raw.strip().rstrip(}) raw } return json.loads(raw)还有一个验证点是工具返回的 status 字段。如果 read_file 返回 partial模型应该知道内容被截断了。你可以在系统提示里加一句“如果工具返回 status 为 partial说明内容被截断必要时可以分段读取。”这样模型的行为会更合理。成功结果的标准是什么不是模型回答得多漂亮而是这三件事同时成立第一工具被正确调用且参数合法第二工具结果被完整回填且 tool_call_id 匹配第三模型基于工具结果给出了符合事实的回答。三者缺一链路就不算通。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth这一章对照真实报错来排查。第一个高频错误是 401 Unauthorized。典型报错信息是Error code: 401 - {error: {message: Invalid API key}}。原因通常是环境变量没生效或者 Key 复制时带了空格。排查步骤先在终端执行echo $TAOTOKEN_API_KEY确认变量存在然后检查代码里读取的变量名是否一致最后确认 base_url 是 https://taotoken.net/api 而不是其他地址。如果用的是 .env 文件记得用 python-dotenv 加载。第二个错误是local proxy failed或连接超时。这类报错通常出现在网络环境不稳定时。排查方向先确认能否直接访问 https://taotoken.net/api可以用 curl 测试curl -X POST https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:hi}]}如果 curl 能通但 Python 不通检查是否有系统级代理设置干扰。另外把 timeout 调大一些本地开发时 60 秒比较稳妥。第三个错误是reading choices或KeyError: choices。这通常是因为返回体不是标准的 Chat Completions 格式或者请求被拦截返回了错误页。排查方法在调用后先打印完整 resp看结构对不对。如果 resp 里没有 choices可能是模型 ID 写错了或者请求体格式有问题。确认 model 字段用的是 TaoToken 支持的模型 ID可以在 https://taotoken.net/models 查。第四个错误是 OAuth 相关报错比如OAuth token expired或invalid_grant。如果你用的是 Claude Code 类客户端可能会遇到 OAuth 认证问题。这时候需要检查客户端的认证配置。对于 Claude Code 接入推荐使用 API Key 方式而不是 OAuth配置三件套Base URL 填 https://taotoken.net/apiAPI Key 填你的 KeyModel ID 填支持的模型。如果你在用 CC Switch 或 Cline MCP同样需要确认这三项配置一致。还有一个隐蔽错误是工具调用死循环。模型反复调用同一个工具每次都返回相同结果。这通常是因为工具返回的 text 里没有明确告诉模型“已经完成”或“没有更多内容”。解决办法是在工具返回里加状态提示比如搜索无结果时返回{status: success, text: 未找到匹配项建议换关键词}而不是空字符串。最后提醒一点如果报错信息里出现tool_call_id mismatch说明你在回填 tool 消息时用的 id 和 assistant 消息里的 id 不一致。检查代码里是否用了call.id而不是自己生成的 id。这个错误在手动拼接 messages 时很常见。6. 语义一致 CTA把统一 Key 接入变成长期可用的开发习惯走到这里你已经有了一个能跑通 Function Calling 的 Code Agent 骨架。但要让它在真实项目里长期可用还需要把模型调用通道固化下来。TaoToken 的统一 Key 接入价值就在这里你不需要在每次换模型时重写调用层只需要改一个 model 字段。对于长期编码和 Agent 开发场景可以考虑 Coding Plan把常用模型和额度统一管理减少反复配置的成本。如果你在排查接入问题时需要对照文档接入文档里有完整的参数说明和示例。验证模型是否可用时可以直接用模型对话做快速测试。而 API Keys 页面则是生成和管理 Key 的入口。这三个入口配合使用基本覆盖了从调试到上线的全流程。回到 Agent 本身下一步可以扩展的方向很多把 Read、Grep、Edit 做成原子工具链加上乐观锁防止并发修改引入统一截断机制把超长工具输出落盘保存用 Summary 压缩旧历史避免长对话上下文腐烂加一层 TraceLogger把每一步 tool_call 和 tool_result 记录下来方便复盘。这些工程细节才是 Code Agent 从“能跑”到“能稳”的关键。我自己的习惯是每加一个新工具就先写一个最小验证脚本确认 Function Calling 链路正常后再集成到主循环。这样出问题时排查范围小不会一上来就面对几百行代码。你也可以把这个习惯保持下去Agent 开发本质上是一个不断缩小不确定性的过程。