1. Agent 项目从零跑通一个可观测智能体工作流到底长什么样Agent 这个词这两年出现频率极高但很多人第一次接触时容易把它和「聊天机器人」混为一谈。简单说Agent 是一个能自己决定下一步做什么的程序它接收目标拆解任务选择工具执行动作观察结果再决定继续还是收尾。聊天机器人只负责「回一句话」Agent 负责「把一件事办完」。适合谁适合已经会写基础后端接口、想把手里的模型调用从「一问一答」升级成「多步协作」的开发者也适合想给团队搭一套可复用智能体骨架的技术负责人。我打算用一个最小可观测工作流把这条链路走通目录结构、依赖清单、统一 Key 配置、三步验证动作全部给到可复制级别。所谓「可观测」不是让你上全套监控大盘而是每一步的输入、输出、耗时、工具调用记录都能落盘、能回放。没有可观测性的 Agent 项目出问题时你只能盯着一个「没返回」干瞪眼。先明确这个最小工作流的定位。它包含四个核心模块规划器Planner、执行器Executor、工具注册表Tool Registry、轨迹记录器Tracer。规划器负责把用户目标拆成步骤执行器负责逐步调用模型和工具工具注册表管理可用能力轨迹记录器把每步的请求与响应写进日志。四者串起来就是一个能跑、能看、能查的 Agent 骨架。技术选型上我用 Python 3.11 FastAPI 做服务层用 OpenAI 兼容的 SDK 发起模型调用工具层先内置两个最朴素的函数一个计算器、一个当前时间查询。别小看这两个它们足以验证「模型决定调用工具 → 程序执行 → 结果回填 → 模型继续推理」这条完整回路。等你把这条回路跑顺再换成搜索、文件操作、数据库查询只是替换工具实现而已。目录结构建议这样组织后面所有配置都基于这个结构agent-demo/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI 入口 │ ├── config.py # 读取环境变量 │ ├── planner.py # 规划器 │ ├── executor.py # 执行器 │ ├── tracer.py # 轨迹记录 │ └── tools/ │ ├── __init__.py │ ├── registry.py # 工具注册表 │ ├── calculator.py │ └── clock.py ├── logs/ │ └── trace.jsonl # 轨迹落盘 ├── requirements.txt └── .env依赖清单保持精简避免一上来就被版本冲突劝退fastapi0.115.0 uvicorn[standard]0.30.6 openai1.51.0 python-dotenv1.0.1 pydantic2.9.2这里有个关键点模型调用统一走一个 Base URL 一个 Key 一个 Model ID 的组合。把这三样抽到.env里后面无论换模型还是换接入点都只改配置不改代码。这也是我后面要重点讲的统一 Key 接入思路。可观测性从第一天就要做。轨迹记录器用 JSONL 格式追加写入每行一条事件包含时间戳、事件类型、步骤序号、输入、输出、耗时。JSONL 的好处是既能人眼直接看也能被脚本逐行解析做统计。很多人项目跑通了才想起来加日志结果发现关键路径上根本没埋点只能推倒重来。这个骨架跑通后你能拿它做什么可以接一个搜索工具做成资料整理助手可以接文件读写做成代码助手也可以接数据库查询做成内部数据问答。核心链路不变变的只是工具集和提示词。所以别急着堆功能先把这条最小回路和它的可观测能力打磨扎实。2. TaoToken 统一 Key 接入Agent 项目多模型调用的配置前置Agent 项目有个绕不开的现实你往往不止用一个模型。规划阶段可能想用推理强的工具调用阶段可能想用响应快的做结构化输出时又可能换一个更稳的。如果每个模型都单独申请 Key、单独记 Base URL配置会迅速失控。统一 Key 接入的价值就在这里一个 Key、一个 Base URL通过 Model ID 区分不同模型配置面收敛到一处。TaoToken 的接入方式就是标准的 OpenAI 兼容协议。你拿到 Key 之后把 Base URL 指向https://taotoken.net/api然后用 OpenAI SDK 正常调用即可。注意这里写的是 API 地址不带任何多余参数。官网入口是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content需要看文档或管理 Key 时从那里进。先说 Key 怎么拿。进入控制台后创建 API Key复制出来只显示一次务必立刻存进密码管理器或.env。我见过太多人把 Key 贴在代码里提交到仓库第二天就收到异常调用告警。正确做法是本地.env存 Key.gitignore把.env排除掉。.env内容长这样TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODEL_IDgpt-4o-mini注意 Model ID 这一项它决定了你这次调用走哪个模型。不同模型对工具调用的支持程度不一样做 Agent 时优先选支持 function calling 的模型。如果你不确定某个 Model ID 是否可用最直接的办法是去模型对话页面手动发一条消息验证确认能通再写进配置。配置读取层用python-dotenv加载封装成一个Settings对象避免在业务代码里到处os.getenv# app/config.py import os from dotenv import load_dotenv load_dotenv() class Settings: api_key: str os.getenv(TAOTOKEN_API_KEY, ) base_url: str os.getenv(TAOTOKEN_BASE_URL, https://taotoken.net/api) model_id: str os.getenv(TAOTOKEN_MODEL_ID, gpt-4o-mini) def validate(self) - None: if not self.api_key: raise ValueError(TAOTOKEN_API_KEY 未配置请检查 .env 文件) settings Settings()这里有个容易踩的坑Base URL 结尾不要多加/v1或斜杠。OpenAI SDK 会自己在后面拼路径你多写一段就会变成/api/v1/chat/completions之外的错误路径直接 404。我试过在 Base URL 后面手滑加了斜杠报错信息是路径找不到排查了十几分钟才反应过来。客户端初始化也集中在一处方便统一加超时和重试# app/planner.py 顶部 from openai import OpenAI from app.config import settings client OpenAI( api_keysettings.api_key, base_urlsettings.base_url, timeout60.0, )把 client 做成模块级单例避免每次请求都新建连接。Agent 一次任务可能发起十几次模型调用连接复用能省下可观的握手开销。关于 Coding Plan如果你打算长期做 Agent 开发、频繁调试多步工作流按量计费有时候不好预估成本可以了解一下 Coding Plan 这类面向持续编码场景的方案。入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite。它更适合「每天都在跑 Agent 调试」的节奏而不是偶尔调一次。配置这一层做完你的项目就具备了「换模型只改一行」的能力。这对 Agent 项目尤其重要因为不同阶段对模型的要求差异很大能快速切换意味着你能快速做对比实验。别把模型名硬编码在业务逻辑里那是最常见的返工来源。3. 可复制配置片段settings.json 与工具注册表落地这一节给可直接复制的配置片段。先说明一点不同工具链读取配置的路径和字段名不一样下面给的是通用结构你按自己实际使用的工具调整字段名但 Base URL、Key、Model ID 这三件套的对应关系不要变。如果你用的是支持settings.json的编辑器类工具配置片段如下{ models: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, modelId: gpt-4o-mini, timeoutMs: 60000 }, agent: { maxSteps: 8, traceFile: logs/trace.jsonl, enableToolCalling: true } }注意apiKey用的是环境变量占位符不要把真实 Key 写进这个文件。如果你的工具不支持占位符就在启动脚本里先导出环境变量再启动。如果你用的是 TOML 风格的配置等价写法[models] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model_id gpt-4o-mini timeout_ms 60000 [agent] max_steps 8 trace_file logs/trace.jsonl enable_tool_calling true三件套对应关系再强调一遍Base URL 填https://taotoken.net/apiKey 填你创建的那串Model ID 填你要用的模型标识。这三样必须同时正确缺一个都会失败。只填 Key 不填 Base URLSDK 会走默认官方地址只填 Base URL 不填 Key直接 401。接下来是工具注册表。Agent 能不能调用工具取决于你给模型暴露了哪些函数定义。注册表的设计目标是「加工具不改执行器」# app/tools/registry.py from typing import Callable, Any class ToolRegistry: def __init__(self) - None: self._tools: dict[str, dict[str, Any]] {} def register(self, name: str, description: str, parameters: dict, func: Callable) - None: self._tools[name] { schema: { type: function, function: { name: name, description: description, parameters: parameters, }, }, func: func, } def schemas(self) - list[dict]: return [t[schema] for t in self._tools.values()] def call(self, name: str, arguments: dict) - Any: if name not in self._tools: raise KeyError(f未注册的工具: {name}) return self._tools[name][func](**arguments) registry ToolRegistry()注册两个示例工具# app/tools/calculator.py def calculate(expression: str) - str: allowed set(0123456789-*/(). ) if not set(expression) allowed: return 表达式包含不允许的字符 try: return str(eval(expression, {__builtins__: {}}, {})) except Exception as exc: return f计算失败: {exc} # app/tools/clock.py from datetime import datetime def now() - str: return datetime.now().strftime(%Y-%m-%d %H:%M:%S)注册动作放在app/tools/__init__.py里统一执行from app.tools.registry import registry from app.tools.calculator import calculate from app.tools.clock import now registry.register( namecalculate, description计算数学表达式输入为纯数字和运算符组成的字符串, parameters{ type: object, properties: { expression: {type: string, description: 如 (128)*3} }, required: [expression], }, funccalculate, ) registry.register( namenow, description获取当前本地时间无需参数, parameters{type: object, properties: {}}, funcnow, )这里有个细节值得说工具描述要写得让模型能判断「什么时候该用」。描述太模糊模型要么不用要么乱用。比如calculate的描述里明确写了「输入为纯数字和运算符组成的字符串」模型就知道传参格式。工具调用失败的一大半原因是描述没写清楚导致模型传错参数结构。轨迹记录器也一并给到# app/tracer.py import json import time from pathlib import Path TRACE_PATH Path(logs/trace.jsonl) TRACE_PATH.parent.mkdir(parentsTrue, exist_okTrue) def trace(event: str, step: int, payload: dict) - None: record { ts: time.time(), event: event, step: step, payload: payload, } with TRACE_PATH.open(a, encodingutf-8) as f: f.write(json.dumps(record, ensure_asciiFalse) \n)配置和注册表都落地后你的项目骨架就具备了「可配置、可扩展、可追踪」三个属性。下一步就是把它跑起来验证。4. 三步验证本地启动、单步调用、日志回放配置写完不代表能跑。我习惯用三步验证法确认骨架可用每一步都有明确的成功标准避免「看起来启动了但实际没通」。第一步本地启动服务。入口文件# app/main.py from fastapi import FastAPI from pydantic import BaseModel from app.config import settings from app.executor import run_agent app FastAPI() class TaskRequest(BaseModel): goal: str app.on_event(startup) def startup() - None: settings.validate() app.post(/agent/run) def run(req: TaskRequest): result run_agent(req.goal) return {result: result}启动命令uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload成功标准终端出现Application startup complete且没有抛TAOTOKEN_API_KEY 未配置。如果启动就报 Key 缺失说明.env没被加载检查文件是否在项目根目录、load_dotenv()是否在读取配置前执行。第二步单步调用。先用一个不需要工具的问题验证模型通路curl -X POST http://127.0.0.1:8000/agent/run \ -H Content-Type: application/json \ -d {goal: 用一句话解释什么是智能体}成功标准返回 JSON 里有result字段内容是模型生成的解释。如果这里报 401说明 Key 无效或没带上如果报连接错误检查 Base URL 是否写成了https://taotoken.net/api。再用一个需要工具的问题验证工具调用回路curl -X POST http://127.0.0.1:8000/agent/run \ -H Content-Type: application/json \ -d {goal: 帮我算一下 (12872)*3 等于多少并告诉我现在几点}成功标准返回结果里既有正确数值 600也有当前时间。这说明模型成功触发了calculate和now两个工具执行器把结果回填后又让模型做了总结。这一步是整个 Agent 骨架的核心验证能过就说明「规划—调用—回填—再推理」的回路是通的。第三步日志回放。打开logs/trace.jsonl你应该能看到类似这样的记录{ts: 1730000000.1, event: llm_request, step: 1, payload: {model: gpt-4o-mini, messages: 2}} {ts: 1730000000.8, event: tool_call, step: 1, payload: {name: calculate, arguments: {expression: (12872)*3}}} {ts: 1730000000.9, event: tool_result, step: 1, payload: {result: 600}} {ts: 1730000001.5, event: llm_response, step: 2, payload: {finish_reason: stop}}成功标准每条事件都有时间戳和步骤号工具调用的入参和返回值都能对上。回放时你可以用脚本按step分组算出每一步耗时找出瓶颈在哪。比如llm_request到llm_response之间隔了 3 秒那这步就是慢在模型推理如果tool_call到tool_result隔了很久那是你的工具实现慢。这三步做完你手里就有了一个可观测的最小 Agent 工作流。它不花哨但每个环节都能验证、能定位。后面加工具、换模型、调提示词都在这套骨架上迭代不会失控。5. 常见报错排查401、local proxy failed、reading choices、OAuthAgent 项目跑不起来八成是下面这几类错误。我按实际遇到的频率排一下每条给出定位思路。401 Unauthorized。这是最高频的。原因通常有三个Key 没配置、Key 配错、Key 没被正确读取。排查顺序是先确认.env里TAOTOKEN_API_KEY有值再确认settings.validate()在启动时执行了最后确认请求头里确实带了Authorization: Bearer sk-xxx。如果用的是编辑器类工具检查它的配置文件里apiKey字段是否指向了正确的环境变量。401 不会骗人就是认证没过别往别处想。local proxy failed。这个报错通常出现在你本地设置了网络代理但代理进程没启动或端口不对。SDK 尝试走代理连不上就抛这个。排查方法是检查环境变量HTTP_PROXY/HTTPS_PROXY是否指向了一个不存在的端口。如果你不需要代理把这两个变量清掉再试。注意这里说的是本地开发环境的网络配置问题和接入点本身无关清掉错误配置即可。reading choices 相关报错。典型信息是KeyError: choices或reading choices。这说明返回的 JSON 结构里没有choices字段通常是响应体根本不是预期的模型返回格式。常见原因Base URL 写错导致请求打到了别的路径返回了一个 HTML 错误页或者 Model ID 填了一个不存在的模型服务端返回了错误对象。排查方法是把原始响应打印出来看别只看异常信息。我习惯在客户端外面包一层把response.model_dump()打出来一眼就能看出返回了什么。OAuth 相关报错。如果你用的是某些需要 OAuth 授权的工具报错可能提示 token 过期或授权失败。这类问题通常和 Key 认证是两套机制别混在一起排查。先确认你用的是 API Key 模式还是 OAuth 模式两者配置位置不同。Agent 项目里我建议统一用 API Key链路更短、更好排查。还有一类不报错但结果不对的情况模型不调用工具直接编了个答案。这通常是工具描述不够清晰或者提示词里没强调「需要计算时必须调用工具」。解决办法是在系统提示里明确写「涉及数值计算必须调用 calculate 工具不要自行估算」。模型很听话你说清楚它就用。排查的核心原则是先看原始响应再看异常信息。异常信息往往是 SDK 包装过的原始响应才是一手证据。把response.model_dump()或response.text打出来大部分问题当场就能定位。6. 继续往下走把骨架变成你自己的 Agent到这里你已经有了一个能跑、能看、能查的 Agent 骨架。接下来怎么长取决于你的场景。想验证模型能力可以去模型对话页面手动试几个 Model ID看哪个在工具调用上更稳想长期做编码类 AgentCoding Plan 那条路径更适合高频调试的节奏需要查接入细节和字段说明接入文档里有完整参数表。给你几个我踩过坑后总结的实用建议。第一工具数量别一上来就堆到十几个模型在工具多的时候选择准确率会下降先三五个打磨好再加。第二轨迹日志一定要在开发阶段就开别等出问题才加那时候你连复现都难。第三Model ID 和提示词都做成可配置Agent 调优本质上是反复做对比实验配置化能让你一次改一个变量。第四maxSteps一定要设上限否则模型可能陷入循环调用烧钱又烧时间。最后说个心态问题。Agent 项目最容易让人焦虑的地方是「它有时候对有时候不对」。这不是你的代码有问题而是模型本身有不确定性。可观测性的意义就在于当它不对的时候你能从轨迹里看出是哪一步偏了是规划错了、工具选错了、还是参数传错了。有了这个能力调优就从玄学变成了工程。骨架已经在你手里了剩下的就是接上你真正需要的工具然后让它跑起来。