拓冰网站定制 
1. 从零搭建 AI Agent 到底难在哪一个最小闭环的真实场景很多人第一次听到「AI Agent」这个词脑子里浮现的是能自己上网、自己写代码、自己订机票的科幻助手。但真动手时卡住的地方往往特别朴素LLM 的 Key 怎么配、工具怎么注册、模型怎么知道该调用哪个函数、调用完结果怎么回填给模型。这几个环节任何一个没打通Agent 就退化成「你问一句它答一句」的普通聊天。我先把概念说清楚。AI Agent 的最小闭环本质就是三件事一个能理解自然语言的 LLM、一组能被 LLM 调用的工具、一个负责「模型说要调工具 → 执行工具 → 把结果喂回模型」的主循环。普通聊天是「你问一句它答一句」Agent 是「你给一个目标它自己拆解任务、调用工具、执行步骤、给你结果」。比如你问「帮我规划明天去北京出差的行程」Agent 会自己查天气、查高铁、查酒店最后生成完整方案。适合读这篇的人有三类想理解 Agent 底层原理但不想被框架绕晕的开发者、手里有 Python 基础想快速跑通一个 demo 的人、以及准备后续接入 MCP 工具生态但还没搭好地基的人。这篇不讲抽象架构直接给可复制的依赖清单、Agent 主循环代码、统一 Key 通道配置示例以及一条 curl 验证请求。跑通之后你再往上叠 MCP 工具、多 Server 组合、生产级部署地基都是稳的。技术栈上2026 年搭建 Agent 的核心事实标准已经是 MCP 协议Model Context Protocol由 Anthropic 提出、后移交 Linux Foundation 管理。它采用 Client-Server 结构MCP Server 提供具体工具查天气、搜文件、调 APIMCP Client 就是 Agent 本体负责调度 LLM 并调用 Server 的工具。理解这个结构后面写代码会顺很多。2. TaoToken 统一 Key 接入为什么 Agent 项目适合用它做 LLM 通道写 Agent 最烦的一件事是模型通道换来换去。今天用 A 家的模型明天想试 B 家的Key 格式、Base URL、参数命名全不一样代码里到处是硬编码。更麻烦的是Agent 主循环里模型调用是高频操作一旦通道不稳定整个循环就卡死。TaoToken 在这里扮演的角色是「统一 Key 统一 API 通道」。你只需要一套 Key、一个 Base URL就能通过 OpenAI 兼容接口调用不同模型。对 Agent 项目来说这意味着主循环代码里的AsyncOpenAI(api_key..., base_url...)只需要改两个变量就能切换底层模型不用动业务逻辑。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。API 地址是 https://taotoken.net/api 注意这个不带 UTM 参数直接用于代码里的 base_url。具体操作路径分三步。第一步去控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在 API Keys 页面生成一个 Key复制保存好后面代码里要用。第二步确认你要用的模型 ID可以在模型对话页面先手动试一下地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 选一个模型发条消息确认能正常返回。第三步把 Key 和 Base URL 填进 Agent 代码。这里有个关键点Agent 主循环里模型要支持 function calling工具调用不是所有模型都支持。选模型时优先选明确支持工具调用的否则tools参数传进去会被忽略Agent 就退化成普通聊天了。如果你打算长期跑编码类或 Agent 类任务可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合高频、长时间的调用场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有完整的参数说明和示例。API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 泄露了可以在这里吊销重建。需要强调的是TaoToken 是合规的 API 通道服务不是让你绕过什么限制的工具。它的价值在于统一接口、简化多模型切换让 Agent 开发者把精力放在工具注册和主循环逻辑上而不是天天折腾各家 SDK 的差异。3. 可复制配置依赖清单、Agent 主循环代码与统一 Key 参数这一节是全文最核心的部分所有代码都可以直接复制运行。先给依赖清单再给 Agent 主循环最后给统一 Key 的配置片段。环境要求 Python 3.10 以上先确认版本python --version安装核心依赖pip install openai pip install mcp pip install httpxopenai用于调用 LLMTaoToken 走 OpenAI 兼容接口mcp是 MCP 协议 SDKhttpx用于工具内部的 HTTP 请求。接下来是 Agent 主循环。这段代码是整个 Agent 的心脏逻辑是用户输入 → 调 LLM → 检查是否要调工具 → 执行工具 → 把结果回填 → 再调 LLM → 直到模型给出最终答案。# agent.py AI Agent 核心连接 LLM MCP 工具 import asyncio import json from openai import AsyncOpenAI from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client class SimpleAgent: 一个极简的 AI Agent def __init__(self, api_key: str, base_url: str, model: str): self.client AsyncOpenAI(api_keyapi_key, base_urlbase_url) self.model model self.mcp_session None self.tools [] self.tool_handlers {} async def connect_mcp_server(self, command: str, args: list[str]): 连接 MCP Server 并拉取工具列表 server_params StdioServerParameters(commandcommand, argsargs) read_stream, write_stream await stdio_client(server_params).__aenter__() self.mcp_session await ClientSession(read_stream, write_stream).__aenter__() await self.mcp_session.initialize() response await self.mcp_session.list_tools() self.tools [{ type: function, function: { name: tool.name, description: tool.description, parameters: tool.input_schema } } for tool in response.tools] self.tool_handlers {tool.name: tool for tool in response.tools} async def run(self, user_message: str, max_turns: int 10) - str: Agent 主循环 messages [{role: user, content: user_message}] for turn in range(max_turns): response await self.client.chat.completions.create( modelself.model, messagesmessages, toolsself.tools if self.tools else None, tool_choiceauto ) message response.choices[0].message messages.append(message) if not message.tool_calls: return message.content for tool_call in message.tool_calls: tool_name tool_call.function.name tool_args json.loads(tool_call.function.arguments) print(f\n调用工具: {tool_name}({tool_args})) result await self.mcp_session.call_tool(tool_name, tool_args) result_text result.content[0].text if result.content else messages.append({ role: tool, tool_call_id: tool_call.id, content: result_text }) print(f工具返回: {result_text[:100]}...) return Agent 已达到最大执行轮次。 async def main(): agent SimpleAgent( api_key你的 TaoToken Key, base_urlhttps://taotoken.net/api, model你的模型 ID ) await agent.connect_mcp_server(commandpython, args[weather_server.py]) result await agent.run(我明天要去北京出差帮我查一下北京天气怎么样) print(f\n Agent 回答 \n{result}) if __name__ __main__: asyncio.run(main())统一 Key 的配置如果你习惯用配置文件管理可以写一个settings.json{ llm: { base_url: https://taotoken.net/api, api_key: sk-你的TaoTokenKey, model_id: 你的模型ID, timeout: 60 }, agent: { max_turns: 10, tool_choice: auto } }如果你用 TOML 风格比如某些框架的配置等价写法[llm] base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model_id 你的模型ID timeout 60 [agent] max_turns 10 tool_choice auto三件套必须齐全Base URL 是https://taotoken.net/apiKey 是你在控制台生成的Model ID 是你要调用的具体模型。缺任何一个请求都会失败。如果你用 Claude Code 或类似工具配置项名称可能不同但本质都是这三样。4. 验证请求一条 curl 确认链路可用再跑 Agent在跑完整 Agent 之前先用一条 curl 确认 TaoToken 通道是通的。这一步能帮你排除掉 90% 的「Key 没配对」问题。curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoTokenKey \ -d { model: 你的模型ID, messages: [ {role: user, content: 只回复两个字通了} ] }预期返回是一个标准 OpenAI 格式的 JSON结构大致如下{ id: chatcmpl-xxxxx, object: chat.completion, created: 1730000000, model: 你的模型ID, choices: [ { index: 0, message: { role: assistant, content: 通了 }, finish_reason: stop } ], usage: { prompt_tokens: 12, completion_tokens: 2, total_tokens: 14 } }看到choices[0].message.content有内容说明 Key、Base URL、模型 ID 三件套都对了。如果返回 401说明 Key 有问题如果返回 404多半是 Base URL 或路径写错了如果返回模型不存在检查 Model ID。curl 通了之后再跑 Agent。但 Agent 还需要一个 MCP Server 提供工具否则它没有工具可调就只是普通聊天。下面给一个最小的 MCP Server提供「查天气」和「算日期差」两个工具# weather_server.py 最小 MCP Server提供天气查询和日期计算工具 import asyncio import json from datetime import datetime from mcp.server import Server, stdio_server from mcp.types import Tool, TextContent server Server(my_tools) server.list_tools() async def list_tools() - list[Tool]: return [ Tool( nameget_weather, description查询指定城市的当前天气, input_schema{ type: object, properties: { city: {type: string, description: 城市名称如 北京、上海} }, required: [city] } ), Tool( namecalculate_days, description计算从今天到指定日期的天数差, input_schema{ type: object, properties: { target_date: {type: string, description: 目标日期格式 YYYY-MM-DD} }, required: [target_date] } ), ] server.call_tool() async def call_tool(name: str, arguments: dict) - list[TextContent]: if name get_weather: city arguments[city] weather_data { 北京: {temp: 28°C, condition: 晴, humidity: 45%}, 上海: {temp: 26°C, condition: 多云, humidity: 60%}, 深圳: {temp: 30°C, condition: 阵雨, humidity: 75%}, } result weather_data.get(city, {temp: N/A, condition: 未知}) return [TextContent(typetext, textjson.dumps(result, ensure_asciiFalse))] elif name calculate_days: target datetime.strptime(arguments[target_date], %Y-%m-%d) today datetime.now() delta (target - today).days return [TextContent( typetext, textjson.dumps({ days_difference: delta, today: today.strftime(%Y-%m-%d), target: arguments[target_date] }, ensure_asciiFalse) )] raise ValueError(f未知工具: {name}) async def main(): async with stdio_server() as (read_stream, write_stream): await server.run(read_stream, write_stream, server.create_initialization_options()) if __name__ __main__: asyncio.run(main())先单独跑一下 Server 确认不报错python weather_server.py它会保持运行等待 Client 通过标准输入输出通信。然后另开一个终端跑 Agentpython agent.py跑通后你会看到类似这样的输出调用工具: calculate_days({target_date: 2026-06-07}) 工具返回: {days_difference: 2, today: 2026-06-05, target: 2026-06-07} 调用工具: get_weather({city: 北京}) 工具返回: {temp: 28°C, condition: 晴, humidity: 45%} Agent 回答 明天6月7日北京天气晴好气温28°C湿度45%非常适合出行。 建议带一件薄外套早晚可能略有温差。看到 Agent 自己拆解了「明天」这个相对日期、先算日期差、再查天气、最后汇总回答说明整个闭环通了。这就是一个可用的 AI Agent 最小形态。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth跑 Agent 的过程中报错基本集中在几个固定位置。这一节按真实报错逐个拆。401 Unauthorized。这是最常见的。原因通常是 Key 没填对、Key 前后有空格、或者 Key 已经被吊销。排查方法先用第 4 节的 curl 单独测 Key如果 curl 也 401就是 Key 本身的问题去 API Keys 页面重新生成一个。注意代码里api_key不要带Bearer前缀SDK 会自己加。local proxy failed / connection refused。这个报错说明请求根本没发出去通常是 Base URL 写错了或者本地网络环境有问题。检查base_url是不是https://taotoken.net/api注意结尾不要多加/v1SDK 会自己拼路径具体以接入文档为准。如果本地有奇怪的网络配置先确认能正常访问外网。Error reading choices / choices is undefined。这个报错说明请求发出去了但返回的 JSON 结构里没有choices字段。常见原因有两个一是模型 ID 写错了服务端返回的是错误信息而不是正常响应二是模型不支持工具调用传了tools参数后返回了非预期结构。排查方法把tools参数去掉只发一条普通消息看能不能正常返回。如果普通消息能返回、带 tools 就报错说明该模型不支持 function calling换一个支持的模型。OAuth / authentication failed。如果你用的是 Claude Code 或类似工具可能会遇到 OAuth 相关的报错。这类工具通常有自己的认证流程配置时要确保 Base URL、Key、Model ID 三件套都填对。以 Claude Code 为例配置项一般在 settings 文件里Base URL 填https://taotoken.net/apiKey 填你的 TaoToken KeyModel ID 填你要用的模型。如果出现 OAuth 报错先检查是不是把 Key 填到了错误的字段或者工具本身在尝试走它自己的登录流程。工具调用死循环。Agent 一直调同一个工具、停不下来。这通常是工具描述description写得太模糊模型不知道该调哪个或者工具返回的结果让模型误以为任务没完成。解决办法把每个工具的 description 写清楚明确「什么时候该用这个工具」同时在主循环里设max_turns防止无限循环。MCP Server 启动失败。connect_mcp_server报错通常是command或args写错了。比如commandpython但系统里只有python3或者args里的文件路径不对。排查方法先在终端手动跑一遍python weather_server.py确认能启动再填进代码。工具返回结果为空。result.content[0].text报索引错误说明工具返回的 content 是空的。检查 MCP Server 里call_tool的返回值确保每个分支都返回了TextContent。这些报错覆盖了 90% 的初次搭建问题。遇到其他报错先看报错发生在哪一步是 curl 阶段、Agent 启动阶段、还是工具调用阶段。定位到阶段问题范围就缩小了一大半。6. 跑通之后往哪走从单工具到多 MCP Server 组合最小闭环跑通后Agent 的扩展方向很清晰挂载更多 MCP Server组合不同能力。一个 Agent 可以同时连接多个 Server比如天气、搜索、文件操作、数据库查询工具列表合并后一起传给 LLM。async def connect_multiple_servers(agent): 连接多个 MCP Server组合不同能力 servers [ (python, [weather_server.py]), (python, [search_server.py]), (python, [file_server.py]), ] all_tools [] all_handlers {} for command, args in servers: try: server_params StdioServerParameters(commandcommand, argsargs) read, write await stdio_client(server_params).__aenter__() session await ClientSession(read, write).__aenter__() await session.initialize() response await session.list_tools() for tool in response.tools: all_tools.append({ type: function, function: { name: tool.name, description: tool.description, parameters: tool.input_schema } }) all_handlers[tool.name] (session, tool) print(f已连接: { .join(args)}) except Exception as e: print(f连接失败 {args}: {e}) agent.tools all_tools agent.tool_handlers all_handlers几个实战建议。工具描述要写好LLM 靠 description 判断何时调用哪个工具描述越清楚Agent 越聪明。工具调用要设超时避免某个工具卡死整个 Agent。MCP Server 应该有独立的权限控制不能直接暴露给用户。工具最好幂等多次调用同一参数结果一致。日志要全记录每次工具调用的入参和出参方便排查。如果你用 HarmonyOS 开发官方提供了 Agent Framework KitAPI 11可以把 Agent 内嵌到 ArkTS 页面里。核心是FunctionComponent和AgentController先检查环境是否支持再挂载组件错误处理要区分错误类型给用户友好提示。从最小闭环到生产级 Agent中间隔的是工具生态、错误处理、权限控制、可观测性。但地基就是这篇里的三件事统一 Key 通道、Agent 主循环、MCP 工具注册。这三样跑通了后面都是在这个骨架上加肉。建议你先用这篇的代码跑通 demo确认 curl 返回正常、Agent 能调用工具、结果能汇总再根据实际需求扩展工具。 搭建一个 AI Agent：从零到可用的极简教程（TaoToken 统一 Key 接入篇）
1. 从零搭建 AI Agent 到底难在哪一个最小闭环的真实场景很多人第一次听到「AI Agent」这个词脑子里浮现的是能自己上网、自己写代码、自己订机票的科幻助手。但真动手时卡住的地方往往特别朴素LLM 的 Key 怎么配、工具怎么注册、模型怎么知道该调用哪个函数、调用完结果怎么回填给模型。这几个环节任何一个没打通Agent 就退化成「你问一句它答一句」的普通聊天。我先把概念说清楚。AI Agent 的最小闭环本质就是三件事一个能理解自然语言的 LLM、一组能被 LLM 调用的工具、一个负责「模型说要调工具 → 执行工具 → 把结果喂回模型」的主循环。普通聊天是「你问一句它答一句」Agent 是「你给一个目标它自己拆解任务、调用工具、执行步骤、给你结果」。比如你问「帮我规划明天去北京出差的行程」Agent 会自己查天气、查高铁、查酒店最后生成完整方案。适合读这篇的人有三类想理解 Agent 底层原理但不想被框架绕晕的开发者、手里有 Python 基础想快速跑通一个 demo 的人、以及准备后续接入 MCP 工具生态但还没搭好地基的人。这篇不讲抽象架构直接给可复制的依赖清单、Agent 主循环代码、统一 Key 通道配置示例以及一条 curl 验证请求。跑通之后你再往上叠 MCP 工具、多 Server 组合、生产级部署地基都是稳的。技术栈上2026 年搭建 Agent 的核心事实标准已经是 MCP 协议Model Context Protocol由 Anthropic 提出、后移交 Linux Foundation 管理。它采用 Client-Server 结构MCP Server 提供具体工具查天气、搜文件、调 APIMCP Client 就是 Agent 本体负责调度 LLM 并调用 Server 的工具。理解这个结构后面写代码会顺很多。2. TaoToken 统一 Key 接入为什么 Agent 项目适合用它做 LLM 通道写 Agent 最烦的一件事是模型通道换来换去。今天用 A 家的模型明天想试 B 家的Key 格式、Base URL、参数命名全不一样代码里到处是硬编码。更麻烦的是Agent 主循环里模型调用是高频操作一旦通道不稳定整个循环就卡死。TaoToken 在这里扮演的角色是「统一 Key 统一 API 通道」。你只需要一套 Key、一个 Base URL就能通过 OpenAI 兼容接口调用不同模型。对 Agent 项目来说这意味着主循环代码里的AsyncOpenAI(api_key..., base_url...)只需要改两个变量就能切换底层模型不用动业务逻辑。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。API 地址是 https://taotoken.net/api 注意这个不带 UTM 参数直接用于代码里的 base_url。具体操作路径分三步。第一步去控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在 API Keys 页面生成一个 Key复制保存好后面代码里要用。第二步确认你要用的模型 ID可以在模型对话页面先手动试一下地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 选一个模型发条消息确认能正常返回。第三步把 Key 和 Base URL 填进 Agent 代码。这里有个关键点Agent 主循环里模型要支持 function calling工具调用不是所有模型都支持。选模型时优先选明确支持工具调用的否则tools参数传进去会被忽略Agent 就退化成普通聊天了。如果你打算长期跑编码类或 Agent 类任务可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合高频、长时间的调用场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有完整的参数说明和示例。API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 泄露了可以在这里吊销重建。需要强调的是TaoToken 是合规的 API 通道服务不是让你绕过什么限制的工具。它的价值在于统一接口、简化多模型切换让 Agent 开发者把精力放在工具注册和主循环逻辑上而不是天天折腾各家 SDK 的差异。3. 可复制配置依赖清单、Agent 主循环代码与统一 Key 参数这一节是全文最核心的部分所有代码都可以直接复制运行。先给依赖清单再给 Agent 主循环最后给统一 Key 的配置片段。环境要求 Python 3.10 以上先确认版本python --version安装核心依赖pip install openai pip install mcp pip install httpxopenai用于调用 LLMTaoToken 走 OpenAI 兼容接口mcp是 MCP 协议 SDKhttpx用于工具内部的 HTTP 请求。接下来是 Agent 主循环。这段代码是整个 Agent 的心脏逻辑是用户输入 → 调 LLM → 检查是否要调工具 → 执行工具 → 把结果回填 → 再调 LLM → 直到模型给出最终答案。# agent.py AI Agent 核心连接 LLM MCP 工具 import asyncio import json from openai import AsyncOpenAI from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client class SimpleAgent: 一个极简的 AI Agent def __init__(self, api_key: str, base_url: str, model: str): self.client AsyncOpenAI(api_keyapi_key, base_urlbase_url) self.model model self.mcp_session None self.tools [] self.tool_handlers {} async def connect_mcp_server(self, command: str, args: list[str]): 连接 MCP Server 并拉取工具列表 server_params StdioServerParameters(commandcommand, argsargs) read_stream, write_stream await stdio_client(server_params).__aenter__() self.mcp_session await ClientSession(read_stream, write_stream).__aenter__() await self.mcp_session.initialize() response await self.mcp_session.list_tools() self.tools [{ type: function, function: { name: tool.name, description: tool.description, parameters: tool.input_schema } } for tool in response.tools] self.tool_handlers {tool.name: tool for tool in response.tools} async def run(self, user_message: str, max_turns: int 10) - str: Agent 主循环 messages [{role: user, content: user_message}] for turn in range(max_turns): response await self.client.chat.completions.create( modelself.model, messagesmessages, toolsself.tools if self.tools else None, tool_choiceauto ) message response.choices[0].message messages.append(message) if not message.tool_calls: return message.content for tool_call in message.tool_calls: tool_name tool_call.function.name tool_args json.loads(tool_call.function.arguments) print(f\n调用工具: {tool_name}({tool_args})) result await self.mcp_session.call_tool(tool_name, tool_args) result_text result.content[0].text if result.content else messages.append({ role: tool, tool_call_id: tool_call.id, content: result_text }) print(f工具返回: {result_text[:100]}...) return Agent 已达到最大执行轮次。 async def main(): agent SimpleAgent( api_key你的 TaoToken Key, base_urlhttps://taotoken.net/api, model你的模型 ID ) await agent.connect_mcp_server(commandpython, args[weather_server.py]) result await agent.run(我明天要去北京出差帮我查一下北京天气怎么样) print(f\n Agent 回答 \n{result}) if __name__ __main__: asyncio.run(main())统一 Key 的配置如果你习惯用配置文件管理可以写一个settings.json{ llm: { base_url: https://taotoken.net/api, api_key: sk-你的TaoTokenKey, model_id: 你的模型ID, timeout: 60 }, agent: { max_turns: 10, tool_choice: auto } }如果你用 TOML 风格比如某些框架的配置等价写法[llm] base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model_id 你的模型ID timeout 60 [agent] max_turns 10 tool_choice auto三件套必须齐全Base URL 是https://taotoken.net/apiKey 是你在控制台生成的Model ID 是你要调用的具体模型。缺任何一个请求都会失败。如果你用 Claude Code 或类似工具配置项名称可能不同但本质都是这三样。4. 验证请求一条 curl 确认链路可用再跑 Agent在跑完整 Agent 之前先用一条 curl 确认 TaoToken 通道是通的。这一步能帮你排除掉 90% 的「Key 没配对」问题。curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoTokenKey \ -d { model: 你的模型ID, messages: [ {role: user, content: 只回复两个字通了} ] }预期返回是一个标准 OpenAI 格式的 JSON结构大致如下{ id: chatcmpl-xxxxx, object: chat.completion, created: 1730000000, model: 你的模型ID, choices: [ { index: 0, message: { role: assistant, content: 通了 }, finish_reason: stop } ], usage: { prompt_tokens: 12, completion_tokens: 2, total_tokens: 14 } }看到choices[0].message.content有内容说明 Key、Base URL、模型 ID 三件套都对了。如果返回 401说明 Key 有问题如果返回 404多半是 Base URL 或路径写错了如果返回模型不存在检查 Model ID。curl 通了之后再跑 Agent。但 Agent 还需要一个 MCP Server 提供工具否则它没有工具可调就只是普通聊天。下面给一个最小的 MCP Server提供「查天气」和「算日期差」两个工具# weather_server.py 最小 MCP Server提供天气查询和日期计算工具 import asyncio import json from datetime import datetime from mcp.server import Server, stdio_server from mcp.types import Tool, TextContent server Server(my_tools) server.list_tools() async def list_tools() - list[Tool]: return [ Tool( nameget_weather, description查询指定城市的当前天气, input_schema{ type: object, properties: { city: {type: string, description: 城市名称如 北京、上海} }, required: [city] } ), Tool( namecalculate_days, description计算从今天到指定日期的天数差, input_schema{ type: object, properties: { target_date: {type: string, description: 目标日期格式 YYYY-MM-DD} }, required: [target_date] } ), ] server.call_tool() async def call_tool(name: str, arguments: dict) - list[TextContent]: if name get_weather: city arguments[city] weather_data { 北京: {temp: 28°C, condition: 晴, humidity: 45%}, 上海: {temp: 26°C, condition: 多云, humidity: 60%}, 深圳: {temp: 30°C, condition: 阵雨, humidity: 75%}, } result weather_data.get(city, {temp: N/A, condition: 未知}) return [TextContent(typetext, textjson.dumps(result, ensure_asciiFalse))] elif name calculate_days: target datetime.strptime(arguments[target_date], %Y-%m-%d) today datetime.now() delta (target - today).days return [TextContent( typetext, textjson.dumps({ days_difference: delta, today: today.strftime(%Y-%m-%d), target: arguments[target_date] }, ensure_asciiFalse) )] raise ValueError(f未知工具: {name}) async def main(): async with stdio_server() as (read_stream, write_stream): await server.run(read_stream, write_stream, server.create_initialization_options()) if __name__ __main__: asyncio.run(main())先单独跑一下 Server 确认不报错python weather_server.py它会保持运行等待 Client 通过标准输入输出通信。然后另开一个终端跑 Agentpython agent.py跑通后你会看到类似这样的输出调用工具: calculate_days({target_date: 2026-06-07}) 工具返回: {days_difference: 2, today: 2026-06-05, target: 2026-06-07} 调用工具: get_weather({city: 北京}) 工具返回: {temp: 28°C, condition: 晴, humidity: 45%} Agent 回答 明天6月7日北京天气晴好气温28°C湿度45%非常适合出行。 建议带一件薄外套早晚可能略有温差。看到 Agent 自己拆解了「明天」这个相对日期、先算日期差、再查天气、最后汇总回答说明整个闭环通了。这就是一个可用的 AI Agent 最小形态。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth跑 Agent 的过程中报错基本集中在几个固定位置。这一节按真实报错逐个拆。401 Unauthorized。这是最常见的。原因通常是 Key 没填对、Key 前后有空格、或者 Key 已经被吊销。排查方法先用第 4 节的 curl 单独测 Key如果 curl 也 401就是 Key 本身的问题去 API Keys 页面重新生成一个。注意代码里api_key不要带Bearer前缀SDK 会自己加。local proxy failed / connection refused。这个报错说明请求根本没发出去通常是 Base URL 写错了或者本地网络环境有问题。检查base_url是不是https://taotoken.net/api注意结尾不要多加/v1SDK 会自己拼路径具体以接入文档为准。如果本地有奇怪的网络配置先确认能正常访问外网。Error reading choices / choices is undefined。这个报错说明请求发出去了但返回的 JSON 结构里没有choices字段。常见原因有两个一是模型 ID 写错了服务端返回的是错误信息而不是正常响应二是模型不支持工具调用传了tools参数后返回了非预期结构。排查方法把tools参数去掉只发一条普通消息看能不能正常返回。如果普通消息能返回、带 tools 就报错说明该模型不支持 function calling换一个支持的模型。OAuth / authentication failed。如果你用的是 Claude Code 或类似工具可能会遇到 OAuth 相关的报错。这类工具通常有自己的认证流程配置时要确保 Base URL、Key、Model ID 三件套都填对。以 Claude Code 为例配置项一般在 settings 文件里Base URL 填https://taotoken.net/apiKey 填你的 TaoToken KeyModel ID 填你要用的模型。如果出现 OAuth 报错先检查是不是把 Key 填到了错误的字段或者工具本身在尝试走它自己的登录流程。工具调用死循环。Agent 一直调同一个工具、停不下来。这通常是工具描述description写得太模糊模型不知道该调哪个或者工具返回的结果让模型误以为任务没完成。解决办法把每个工具的 description 写清楚明确「什么时候该用这个工具」同时在主循环里设max_turns防止无限循环。MCP Server 启动失败。connect_mcp_server报错通常是command或args写错了。比如commandpython但系统里只有python3或者args里的文件路径不对。排查方法先在终端手动跑一遍python weather_server.py确认能启动再填进代码。工具返回结果为空。result.content[0].text报索引错误说明工具返回的 content 是空的。检查 MCP Server 里call_tool的返回值确保每个分支都返回了TextContent。这些报错覆盖了 90% 的初次搭建问题。遇到其他报错先看报错发生在哪一步是 curl 阶段、Agent 启动阶段、还是工具调用阶段。定位到阶段问题范围就缩小了一大半。6. 跑通之后往哪走从单工具到多 MCP Server 组合最小闭环跑通后Agent 的扩展方向很清晰挂载更多 MCP Server组合不同能力。一个 Agent 可以同时连接多个 Server比如天气、搜索、文件操作、数据库查询工具列表合并后一起传给 LLM。async def connect_multiple_servers(agent): 连接多个 MCP Server组合不同能力 servers [ (python, [weather_server.py]), (python, [search_server.py]), (python, [file_server.py]), ] all_tools [] all_handlers {} for command, args in servers: try: server_params StdioServerParameters(commandcommand, argsargs) read, write await stdio_client(server_params).__aenter__() session await ClientSession(read, write).__aenter__() await session.initialize() response await session.list_tools() for tool in response.tools: all_tools.append({ type: function, function: { name: tool.name, description: tool.description, parameters: tool.input_schema } }) all_handlers[tool.name] (session, tool) print(f已连接: { .join(args)}) except Exception as e: print(f连接失败 {args}: {e}) agent.tools all_tools agent.tool_handlers all_handlers几个实战建议。工具描述要写好LLM 靠 description 判断何时调用哪个工具描述越清楚Agent 越聪明。工具调用要设超时避免某个工具卡死整个 Agent。MCP Server 应该有独立的权限控制不能直接暴露给用户。工具最好幂等多次调用同一参数结果一致。日志要全记录每次工具调用的入参和出参方便排查。如果你用 HarmonyOS 开发官方提供了 Agent Framework KitAPI 11可以把 Agent 内嵌到 ArkTS 页面里。核心是FunctionComponent和AgentController先检查环境是否支持再挂载组件错误处理要区分错误类型给用户友好提示。从最小闭环到生产级 Agent中间隔的是工具生态、错误处理、权限控制、可观测性。但地基就是这篇里的三件事统一 Key 通道、Agent 主循环、MCP 工具注册。这三样跑通了后面都是在这个骨架上加肉。建议你先用这篇的代码跑通 demo确认 curl 返回正常、Agent 能调用工具、结果能汇总再根据实际需求扩展工具。