1. 从“会聊天”到“会干活”Agent 开发入门到底在学什么很多人第一次接触 Agent 开发脑子里其实只有一个模糊印象不就是让大模型自己调工具、自己干活吗但真动手写的时候问题立刻冒出来——它为什么知道该调哪个工具它怎么记住上一轮说过的话任务拆到一半卡住了怎么办这些疑问背后其实对应的是 Agent 的十个核心概念。把这十个概念串起来你才算真正跨过了 Agent 开发入门的门槛。这篇内容聚焦一件事把抽象概念落到可运行的最小 Agent 示例上。我会用统一的 Key 和 API 通道在本地跑通一个能规划、能调工具、能记住上下文的 Agent然后逐项检查每个概念是否真的生效。你不需要先啃完论文跟着配置和代码走一遍概念自然就对应上了。适合谁看如果你已经会调用大模型 API但没写过 Agent 循环或者用过 Claude Code 这类工具却说不清它内部怎么“思考”再或者想自己搭一个能查天气、能读写文件的小助手这篇就是为你准备的。核心检索词就三个Agent、开发、核心概念——我们边跑边理解。先明确一个前提Agent 不是某个具体框架而是一种运行模式。它的最小骨架就是“感知 → 思考 → 行动 → 观察”的循环。你后面看到的所有高级能力规划、记忆、多 Agent 协作都是在这个循环上叠加出来的。所以第一步我们先把循环跑起来再谈其他。2. 用 TaoToken 统一 Key 打通 Agent 的模型调用通道写 Agent 最烦的一件事是模型调用通道不统一。今天试这个模型明天换那个接口Key 散落在各个环境变量里调试的时候光找配置就耗掉一半精力。我的做法是用一个统一的 API 通道把模型调用固定下来Agent 代码里只认一个 Base URL 和一个 Key换模型只改一个 Model ID。这里我用 TaoToken 来做这件事。它的 API 地址是 https://taotoken.net/api兼容常见的 OpenAI 风格调用方式所以你在 Agent 代码里用 openai 这个 SDK 就能直接连。对 Agent 开发入门来说这一点很关键——你不需要为每个模型写一套适配层统一通道能让你的循环逻辑保持干净。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来。注意这个 Key 只显示一次先存到安全的地方。然后我们把它写进环境变量不要硬编码在代码里。在项目根目录建一个.env文件TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用 Python装两个包pip install openai python-dotenv然后在代码里这样初始化客户端import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) MODEL_ID claude-sonnet-4-5-20250929 # 按需替换这里有个细节Base URL 结尾不要带/v1SDK 会自己拼路径。如果你写成https://taotoken.net/api/v1请求会变成/api/v1/v1/chat/completions直接 404。这个坑我踩过排查了半天。统一通道的好处在你写 Agent 循环时会特别明显。因为 Agent 一次任务可能要调用模型十几次每次的请求格式都一样只是消息历史在变。如果通道不统一你会在不同模型的参数差异上浪费大量时间。现在你只需要关心消息怎么组织、工具怎么描述、循环怎么退出。另外提醒一句Key 不要提交到 Git。把.env加进.gitignore团队协作时用环境变量注入。Agent 项目里经常会有多个工具和子进程Key 泄露的风险比普通脚本高这点要养成习惯。3. 可复制的 Agent 最小配置Base URL、Key 与 Model ID 三件套概念要落地得先有一个能跑的最小 Agent。我们不追求功能多只追求把核心循环、工具调用、记忆这三件事跑通。下面这份配置你可以直接复制改掉 Key 就能用。先看目录结构mini-agent/ ├── .env ├── agent.py └── tools.py.env就是上一步那两行。tools.py里定义两个最简单的工具一个查时间一个算加法。工具描述要写清楚因为模型靠描述决定调哪个。# tools.py import datetime def get_current_time(city: str) - str: 获取指定城市的当前时间。当用户询问时间相关问题时使用。 now datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S) return f{city} 当前时间{now} def add_numbers(a: float, b: float) - str: 计算两个数字的和。当用户需要做加法运算时使用。 return f{a} {b} {a b} TOOL_MAP { get_current_time: get_current_time, add_numbers: add_numbers, } TOOLS_SCHEMA [ { type: function, function: { name: get_current_time, description: 获取指定城市的当前时间。当用户询问时间相关问题时使用。, parameters: { type: object, properties: { city: {type: string, description: 城市名称} }, required: [city], }, }, }, { type: function, function: { name: add_numbers, description: 计算两个数字的和。当用户需要做加法运算时使用。, parameters: { type: object, properties: { a: {type: number, description: 第一个数字}, b: {type: number, description: 第二个数字}, }, required: [a, b], }, }, }, ]注意工具描述里的“当用户……时使用”。这不是写给人看的注释是写给模型看的触发条件。描述越具体模型选错工具的概率越低。我试过把描述写成“处理数据”结果模型在需要算加法时去调了时间工具因为它觉得“处理”也能涵盖。然后是主循环agent.py# agent.py import json import os from dotenv import load_dotenv from openai import OpenAI from tools import TOOL_MAP, TOOLS_SCHEMA load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) MODEL_ID claude-sonnet-4-5-20250929 def run_agent(user_input: str, max_turns: int 5): messages [ {role: system, content: 你是一个会使用工具的助手。需要时调用工具不要凭空猜测。}, {role: user, content: user_input}, ] for turn in range(max_turns): response client.chat.completions.create( modelMODEL_ID, messagesmessages, toolsTOOLS_SCHEMA, tool_choiceauto, ) msg response.choices[0].message messages.append(msg) if not msg.tool_calls: print(f[最终回答] {msg.content}) return msg.content for tool_call in msg.tool_calls: name tool_call.function.name args json.loads(tool_call.function.arguments) print(f[调用工具] {name} 参数{args}) result TOOL_MAP[name](**args) print(f[工具结果] {result}) messages.append({ role: tool, tool_call_id: tool_call.id, content: str(result), }) print([警告] 达到最大轮次强制结束) return None if __name__ __main__: run_agent(现在上海几点顺便帮我算一下 128 加 256 等于多少)这份配置里Base URL、Key、Model ID 三件套齐全。你把它保存下来python agent.py就能跑。跑通之后我们再逐项验证概念。4. 跑通第一个 Agent 并逐项验证十个核心概念是否生效现在运行python agent.py你会看到类似这样的输出[调用工具] get_current_time 参数{city: 上海} [工具结果] 上海 当前时间2026-01-15 14:32:07 [调用工具] add_numbers 参数{a: 128, b: 256} [工具结果] 128 256 384 [最终回答] 上海现在是 2026-01-15 14:32:07128 加 256 等于 384。一次任务里模型先调时间工具再调加法工具最后汇总回答。这个过程里十个核心概念其实都在悄悄起作用。我们逐项对照。核心循环Perceive 是用户输入Think 是模型决定调哪个工具Act 是执行工具Observe 是工具结果回填到 messages。循环在for turn in range(max_turns)里转了两圈才结束。你可以把max_turns改成 1会看到它只调一个工具就被强制结束——这就是循环边界的作用。工具调用模型输出的tool_calls就是 Function Calling。它自己不执行只是表达“我要调 get_current_time参数是上海”。真正执行的是TOOL_MAP[name](**args)。MCP 在这个最小例子里没出现但你可以理解为如果工具变多就需要一个协议来管理工具从哪来、怎么连那就是 MCP 要解决的问题。规划与任务分解用户一句话里有两个需求模型自动拆成两步先时间后加法。它没有一次性把两个工具都调了而是按顺序来。这就是最朴素的规划。你可以试着问“先算 11再告诉我北京几点最后把两个结果拼起来”观察它怎么排顺序。记忆系统messages列表就是短期记忆。工具结果被 append 进去模型下一轮能看到。如果你把messages清空再问同样的问题它就不知道之前算过什么。长期记忆需要你额外写文件比如把用户偏好存到MEMORY.md下次启动时读进来。上下文窗口管理这个例子里消息很短看不出压力。但如果你把max_turns调到 20再让它反复读大文件就会遇到上下文超限。策略是按需加载——只把相关工具结果放进 messages不要把所有历史都塞进去。ReAct 范式模型在调工具前其实内部有 Thought只是这个例子里没显式打印。你可以在 system prompt 里加一句“每次调用工具前先用一句话说明你的理由”然后打印msg.content就能看到它的推理过程。多 Agent 协作最小例子里只有一个 Agent。要验证多 Agent你可以起两个进程一个负责查时间一个负责算数用主进程调度。但入门阶段先不用急单 Agent 跑顺了再扩展。错误处理把add_numbers的参数故意传成字符串看模型怎么反应。它可能会重试也可能直接报错。你可以在工具函数里加 try/except返回错误信息给模型让它自己纠正。安全与对齐这个例子里工具都是只读的没有风险。如果你加一个“删除文件”工具就应该在描述里写“调用前必须确认”并在代码里加确认逻辑。四层防御里人类确认是最后一道。编排框架选型现在你是用原生 SDK 手写循环。等任务复杂了可以考虑 LangGraph 这类框架。但入门阶段手写一遍能让你真正理解每个环节后面用框架时才知道它在帮你做什么。跑完这一遍十个概念就不再是名词而是你代码里能指认出来的具体位置。5. 常见报错排查401、local proxy failed 与 reading choices 怎么解Agent 开发入门阶段报错比概念更劝退。下面这几个是我和身边人最常遇到的对照着排查能省不少时间。401 Unauthorized最常见的原因是 Key 没读到。先确认.env文件在项目根目录且load_dotenv()在OpenAI()之前调用。然后打印一下os.getenv(TAOTOKEN_API_KEY)看是不是 None。如果 Key 读到了还报 401检查 Key 有没有多余空格或者是不是已经失效。还有一种情况Base URL 写成了https://taotoken.net/api/带尾斜杠某些 SDK 会拼出双斜杠导致鉴权失败去掉尾斜杠即可。local proxy failed / connection error这个报错通常出现在网络层。先确认你的 Base URL 是https://taotoken.net/api不要写成其他地址。然后在终端里用 curl 直接测一下curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-5-20250929,messages:[{role:user,content:hi}]}如果 curl 通而 Python 不通那是 SDK 或环境变量的问题如果 curl 也不通检查本机网络设置。注意不要在任何配置里写代理地址Agent 项目里混入代理配置会让排查变得非常混乱。reading choices 报错 / choices 为空这个报错说明请求发出去了但返回结构里没有choices。常见原因有三个。一是 Model ID 写错了比如把claude-sonnet-4-5-20250929拼成了别的服务端返回错误信息而不是正常补全。二是请求体里messages格式不对比如 role 写成了assistant但 content 是空。三是触发了内容过滤返回了一个没有 choices 的结构。排查方法把response整个打印出来看response.error里有没有信息。OAuth 相关报错如果你在 Claude Code 或类似工具里看到 OAuth 报错通常是因为工具尝试用账号登录而不是 API Key。在 Agent 代码里我们用的是 API Key 模式不会走 OAuth。如果你在配置 Claude Code 时遇到检查它的 settings 里是不是把认证方式设成了 API KeyBase URL 填https://taotoken.net/apiKey 填你创建的 KeyModel ID 填对应模型。工具调用参数解析失败如果json.loads(tool_call.function.arguments)报错说明模型返回的参数不是合法 JSON。这通常是因为工具描述里的 parameters schema 写得不严谨。检查required字段和properties是否对应类型是否写对。另外有些模型在参数里会带注释导致 JSON 解析失败可以在解析前做一次清洗。循环不退出如果 Agent 一直调工具不返回最终回答先看max_turns是不是设太大了。然后检查工具结果是不是让模型误以为任务没完成。比如时间工具返回了结果但模型觉得还需要再确认一次。可以在 system prompt 里加一句“拿到工具结果后如果信息足够直接给出最终回答”。6. 把概念变成手感下一步用统一 Key 继续练跑通最小示例之后你对 Agent 开发入门的十个核心概念已经有了手感。接下来最有效的练习是每次只改一个变量观察行为变化。比如把工具描述改模糊看模型选错工具把max_turns改成 1看循环怎么被截断把 messages 清空看记忆怎么丢失。这种对照实验比读十篇文章都管用。如果你想把模型调用通道固定下来继续用 TaoToken 的 API 就行Base URL 还是https://taotoken.net/apiKey 在 https://taotoken.net/api-keys 创建。想直接对话验证模型行为可以打开 https://taotoken.net/model-chat 试几句。如果你打算长期写 Agent、跑编码类任务可以看看 Coding Planhttps://taotoken.net/coding-plan 它更适合高频调用场景。接入文档在 https://taotoken.net/doc 配置细节都在里面。最后留一个练习给最小 Agent 加一个“写文件”工具但要求它在调用前先输出一句确认语。观察模型会不会遵守这个约束如果不遵守你打算在哪一层拦截。这个练习会把你对安全与对齐的理解从概念推到代码。 做 Agent 开发入门必懂的 10 个 Agent 核心概念：用 TaoToken 统一 Key 跑通第一个 Agent 示例
1. 从“会聊天”到“会干活”Agent 开发入门到底在学什么很多人第一次接触 Agent 开发脑子里其实只有一个模糊印象不就是让大模型自己调工具、自己干活吗但真动手写的时候问题立刻冒出来——它为什么知道该调哪个工具它怎么记住上一轮说过的话任务拆到一半卡住了怎么办这些疑问背后其实对应的是 Agent 的十个核心概念。把这十个概念串起来你才算真正跨过了 Agent 开发入门的门槛。这篇内容聚焦一件事把抽象概念落到可运行的最小 Agent 示例上。我会用统一的 Key 和 API 通道在本地跑通一个能规划、能调工具、能记住上下文的 Agent然后逐项检查每个概念是否真的生效。你不需要先啃完论文跟着配置和代码走一遍概念自然就对应上了。适合谁看如果你已经会调用大模型 API但没写过 Agent 循环或者用过 Claude Code 这类工具却说不清它内部怎么“思考”再或者想自己搭一个能查天气、能读写文件的小助手这篇就是为你准备的。核心检索词就三个Agent、开发、核心概念——我们边跑边理解。先明确一个前提Agent 不是某个具体框架而是一种运行模式。它的最小骨架就是“感知 → 思考 → 行动 → 观察”的循环。你后面看到的所有高级能力规划、记忆、多 Agent 协作都是在这个循环上叠加出来的。所以第一步我们先把循环跑起来再谈其他。2. 用 TaoToken 统一 Key 打通 Agent 的模型调用通道写 Agent 最烦的一件事是模型调用通道不统一。今天试这个模型明天换那个接口Key 散落在各个环境变量里调试的时候光找配置就耗掉一半精力。我的做法是用一个统一的 API 通道把模型调用固定下来Agent 代码里只认一个 Base URL 和一个 Key换模型只改一个 Model ID。这里我用 TaoToken 来做这件事。它的 API 地址是 https://taotoken.net/api兼容常见的 OpenAI 风格调用方式所以你在 Agent 代码里用 openai 这个 SDK 就能直接连。对 Agent 开发入门来说这一点很关键——你不需要为每个模型写一套适配层统一通道能让你的循环逻辑保持干净。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来。注意这个 Key 只显示一次先存到安全的地方。然后我们把它写进环境变量不要硬编码在代码里。在项目根目录建一个.env文件TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用 Python装两个包pip install openai python-dotenv然后在代码里这样初始化客户端import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) MODEL_ID claude-sonnet-4-5-20250929 # 按需替换这里有个细节Base URL 结尾不要带/v1SDK 会自己拼路径。如果你写成https://taotoken.net/api/v1请求会变成/api/v1/v1/chat/completions直接 404。这个坑我踩过排查了半天。统一通道的好处在你写 Agent 循环时会特别明显。因为 Agent 一次任务可能要调用模型十几次每次的请求格式都一样只是消息历史在变。如果通道不统一你会在不同模型的参数差异上浪费大量时间。现在你只需要关心消息怎么组织、工具怎么描述、循环怎么退出。另外提醒一句Key 不要提交到 Git。把.env加进.gitignore团队协作时用环境变量注入。Agent 项目里经常会有多个工具和子进程Key 泄露的风险比普通脚本高这点要养成习惯。3. 可复制的 Agent 最小配置Base URL、Key 与 Model ID 三件套概念要落地得先有一个能跑的最小 Agent。我们不追求功能多只追求把核心循环、工具调用、记忆这三件事跑通。下面这份配置你可以直接复制改掉 Key 就能用。先看目录结构mini-agent/ ├── .env ├── agent.py └── tools.py.env就是上一步那两行。tools.py里定义两个最简单的工具一个查时间一个算加法。工具描述要写清楚因为模型靠描述决定调哪个。# tools.py import datetime def get_current_time(city: str) - str: 获取指定城市的当前时间。当用户询问时间相关问题时使用。 now datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S) return f{city} 当前时间{now} def add_numbers(a: float, b: float) - str: 计算两个数字的和。当用户需要做加法运算时使用。 return f{a} {b} {a b} TOOL_MAP { get_current_time: get_current_time, add_numbers: add_numbers, } TOOLS_SCHEMA [ { type: function, function: { name: get_current_time, description: 获取指定城市的当前时间。当用户询问时间相关问题时使用。, parameters: { type: object, properties: { city: {type: string, description: 城市名称} }, required: [city], }, }, }, { type: function, function: { name: add_numbers, description: 计算两个数字的和。当用户需要做加法运算时使用。, parameters: { type: object, properties: { a: {type: number, description: 第一个数字}, b: {type: number, description: 第二个数字}, }, required: [a, b], }, }, }, ]注意工具描述里的“当用户……时使用”。这不是写给人看的注释是写给模型看的触发条件。描述越具体模型选错工具的概率越低。我试过把描述写成“处理数据”结果模型在需要算加法时去调了时间工具因为它觉得“处理”也能涵盖。然后是主循环agent.py# agent.py import json import os from dotenv import load_dotenv from openai import OpenAI from tools import TOOL_MAP, TOOLS_SCHEMA load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) MODEL_ID claude-sonnet-4-5-20250929 def run_agent(user_input: str, max_turns: int 5): messages [ {role: system, content: 你是一个会使用工具的助手。需要时调用工具不要凭空猜测。}, {role: user, content: user_input}, ] for turn in range(max_turns): response client.chat.completions.create( modelMODEL_ID, messagesmessages, toolsTOOLS_SCHEMA, tool_choiceauto, ) msg response.choices[0].message messages.append(msg) if not msg.tool_calls: print(f[最终回答] {msg.content}) return msg.content for tool_call in msg.tool_calls: name tool_call.function.name args json.loads(tool_call.function.arguments) print(f[调用工具] {name} 参数{args}) result TOOL_MAP[name](**args) print(f[工具结果] {result}) messages.append({ role: tool, tool_call_id: tool_call.id, content: str(result), }) print([警告] 达到最大轮次强制结束) return None if __name__ __main__: run_agent(现在上海几点顺便帮我算一下 128 加 256 等于多少)这份配置里Base URL、Key、Model ID 三件套齐全。你把它保存下来python agent.py就能跑。跑通之后我们再逐项验证概念。4. 跑通第一个 Agent 并逐项验证十个核心概念是否生效现在运行python agent.py你会看到类似这样的输出[调用工具] get_current_time 参数{city: 上海} [工具结果] 上海 当前时间2026-01-15 14:32:07 [调用工具] add_numbers 参数{a: 128, b: 256} [工具结果] 128 256 384 [最终回答] 上海现在是 2026-01-15 14:32:07128 加 256 等于 384。一次任务里模型先调时间工具再调加法工具最后汇总回答。这个过程里十个核心概念其实都在悄悄起作用。我们逐项对照。核心循环Perceive 是用户输入Think 是模型决定调哪个工具Act 是执行工具Observe 是工具结果回填到 messages。循环在for turn in range(max_turns)里转了两圈才结束。你可以把max_turns改成 1会看到它只调一个工具就被强制结束——这就是循环边界的作用。工具调用模型输出的tool_calls就是 Function Calling。它自己不执行只是表达“我要调 get_current_time参数是上海”。真正执行的是TOOL_MAP[name](**args)。MCP 在这个最小例子里没出现但你可以理解为如果工具变多就需要一个协议来管理工具从哪来、怎么连那就是 MCP 要解决的问题。规划与任务分解用户一句话里有两个需求模型自动拆成两步先时间后加法。它没有一次性把两个工具都调了而是按顺序来。这就是最朴素的规划。你可以试着问“先算 11再告诉我北京几点最后把两个结果拼起来”观察它怎么排顺序。记忆系统messages列表就是短期记忆。工具结果被 append 进去模型下一轮能看到。如果你把messages清空再问同样的问题它就不知道之前算过什么。长期记忆需要你额外写文件比如把用户偏好存到MEMORY.md下次启动时读进来。上下文窗口管理这个例子里消息很短看不出压力。但如果你把max_turns调到 20再让它反复读大文件就会遇到上下文超限。策略是按需加载——只把相关工具结果放进 messages不要把所有历史都塞进去。ReAct 范式模型在调工具前其实内部有 Thought只是这个例子里没显式打印。你可以在 system prompt 里加一句“每次调用工具前先用一句话说明你的理由”然后打印msg.content就能看到它的推理过程。多 Agent 协作最小例子里只有一个 Agent。要验证多 Agent你可以起两个进程一个负责查时间一个负责算数用主进程调度。但入门阶段先不用急单 Agent 跑顺了再扩展。错误处理把add_numbers的参数故意传成字符串看模型怎么反应。它可能会重试也可能直接报错。你可以在工具函数里加 try/except返回错误信息给模型让它自己纠正。安全与对齐这个例子里工具都是只读的没有风险。如果你加一个“删除文件”工具就应该在描述里写“调用前必须确认”并在代码里加确认逻辑。四层防御里人类确认是最后一道。编排框架选型现在你是用原生 SDK 手写循环。等任务复杂了可以考虑 LangGraph 这类框架。但入门阶段手写一遍能让你真正理解每个环节后面用框架时才知道它在帮你做什么。跑完这一遍十个概念就不再是名词而是你代码里能指认出来的具体位置。5. 常见报错排查401、local proxy failed 与 reading choices 怎么解Agent 开发入门阶段报错比概念更劝退。下面这几个是我和身边人最常遇到的对照着排查能省不少时间。401 Unauthorized最常见的原因是 Key 没读到。先确认.env文件在项目根目录且load_dotenv()在OpenAI()之前调用。然后打印一下os.getenv(TAOTOKEN_API_KEY)看是不是 None。如果 Key 读到了还报 401检查 Key 有没有多余空格或者是不是已经失效。还有一种情况Base URL 写成了https://taotoken.net/api/带尾斜杠某些 SDK 会拼出双斜杠导致鉴权失败去掉尾斜杠即可。local proxy failed / connection error这个报错通常出现在网络层。先确认你的 Base URL 是https://taotoken.net/api不要写成其他地址。然后在终端里用 curl 直接测一下curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-5-20250929,messages:[{role:user,content:hi}]}如果 curl 通而 Python 不通那是 SDK 或环境变量的问题如果 curl 也不通检查本机网络设置。注意不要在任何配置里写代理地址Agent 项目里混入代理配置会让排查变得非常混乱。reading choices 报错 / choices 为空这个报错说明请求发出去了但返回结构里没有choices。常见原因有三个。一是 Model ID 写错了比如把claude-sonnet-4-5-20250929拼成了别的服务端返回错误信息而不是正常补全。二是请求体里messages格式不对比如 role 写成了assistant但 content 是空。三是触发了内容过滤返回了一个没有 choices 的结构。排查方法把response整个打印出来看response.error里有没有信息。OAuth 相关报错如果你在 Claude Code 或类似工具里看到 OAuth 报错通常是因为工具尝试用账号登录而不是 API Key。在 Agent 代码里我们用的是 API Key 模式不会走 OAuth。如果你在配置 Claude Code 时遇到检查它的 settings 里是不是把认证方式设成了 API KeyBase URL 填https://taotoken.net/apiKey 填你创建的 KeyModel ID 填对应模型。工具调用参数解析失败如果json.loads(tool_call.function.arguments)报错说明模型返回的参数不是合法 JSON。这通常是因为工具描述里的 parameters schema 写得不严谨。检查required字段和properties是否对应类型是否写对。另外有些模型在参数里会带注释导致 JSON 解析失败可以在解析前做一次清洗。循环不退出如果 Agent 一直调工具不返回最终回答先看max_turns是不是设太大了。然后检查工具结果是不是让模型误以为任务没完成。比如时间工具返回了结果但模型觉得还需要再确认一次。可以在 system prompt 里加一句“拿到工具结果后如果信息足够直接给出最终回答”。6. 把概念变成手感下一步用统一 Key 继续练跑通最小示例之后你对 Agent 开发入门的十个核心概念已经有了手感。接下来最有效的练习是每次只改一个变量观察行为变化。比如把工具描述改模糊看模型选错工具把max_turns改成 1看循环怎么被截断把 messages 清空看记忆怎么丢失。这种对照实验比读十篇文章都管用。如果你想把模型调用通道固定下来继续用 TaoToken 的 API 就行Base URL 还是https://taotoken.net/apiKey 在 https://taotoken.net/api-keys 创建。想直接对话验证模型行为可以打开 https://taotoken.net/model-chat 试几句。如果你打算长期写 Agent、跑编码类任务可以看看 Coding Planhttps://taotoken.net/coding-plan 它更适合高频调用场景。接入文档在 https://taotoken.net/doc 配置细节都在里面。最后留一个练习给最小 Agent 加一个“写文件”工具但要求它在调用前先输出一句确认语。观察模型会不会遵守这个约束如果不遵守你打算在哪一层拦截。这个练习会把你对安全与对齐的理解从概念推到代码。