★ FEATURED ARTICLE 1. 先搞清楚 Agno 是什么、能做什么、适合谁Agno 是一个用 Python 写的多智能体框架核心卖点就三个字快、轻、稳。你在 GitHub 上看到的那些 awesome-llm-apps 项目里大量 Agent 应用都是拿它搭的star 数已经 34k提交频率也高不是那种半年不更新的玩具库。它能做的事情覆盖很广单个 Agent 带工具跑任务、多个 Agent 组成 Team 协作、用 Workflow 编排稳定输出流程还能挂知识库、记忆模块、会话存储工具层面原生支持 MCP。适合谁如果你是刚接触 Agent 开发的新手之前只写过简单的 OpenAI API 调用那 Agno 的上手曲线算是平缓的——定义一个 Agent 只要几行代码不需要你先学一套复杂的图编排 DSL。如果你是从 LangGraph 迁过来的会发现 Agno 在实例化开销上明显更省官方那个 1000 次带工具 Agent 实例化的对比测试里时间和内存都占优。如果你是要做多智能体协作链路的Team 机制把 Leader 和 Member 的职责分得很清楚不用自己手写调度逻辑。但这里有个现实问题不管框架多好用模型调用这一层你总得配。Agno 支持 OpenAILike 这种兼容接口意味着你可以把任意兼容 OpenAI 协议的服务接进来。我这次的做法是用 TaoToken 的统一 Key 作为模型通道一个 Key 覆盖多个模型省得在 Agno 里为每个模型维护一套 base_url 和 api_key。下面从环境初始化开始一步步把单 Agent、带存储的会话、带工具的 Agent、再到 Team 协作链路全部跑通每一段都给可复制的配置和预期输出。先说清楚本文的验证目标跑通一个「新闻 Agent 天气 Agent」的 TeamLeader 根据用户问题自动分派任务最终返回聚合结果。中间会经过单 Agent 冒烟测试、会话存储验证、工具调用验证三个关卡任何一关卡住都能在排错章节找到对应报错。2. TaoToken 前置准备统一 Key 与模型通道配置在写 Agno 代码之前先把模型通道准备好。TaoToken 的角色是给你一个统一的 API 入口和 KeyAgno 这边只需要按 OpenAILike 的方式填 base_url、api_key、model id 三个值就行。这一步不涉及任何复杂配置但顺序别搞反先拿 Key再确认模型 ID最后写进代码。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录进入控制台。控制台里找到 API Keys 页面路径是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentconsole 点创建新 Key复制出来保存好。这个 Key 就是后面所有配置里的api_key值格式通常是一串以固定前缀开头的字符串别弄丢页面关闭后不一定能再次完整查看。第二步确认你要用的模型 ID。Agno 的 OpenAILike 需要传id参数这个 id 必须和服务端支持的模型名完全一致。你可以在模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chat 里先手动发一条消息验证模型可用页面上会显示当前可选的模型列表。选一个你打算长期用的比如通用的对话模型或者代码能力强的模型把它的 ID 记下来。本文示例里我用一个通用对话模型你替换成自己账号下可用的即可。第三步确认 API 基础地址。TaoToken 的 API 入口是 https://taotoken.net/api 注意这里不带任何查询参数直接作为 base_url 使用。Agno 的 OpenAILike 内部会在这个 base_url 后面拼/chat/completions所以你不要自己再加/v1之类的后缀填https://taotoken.net/api就行。这一点很容易踩坑后面排错章节会专门讲。把这三个值整理成一张对照表写代码时直接对照填配置项值说明base_urlhttps://taotoken.net/api不带 /v1不带查询参数api_key控制台创建的 Key以实际复制为准model id模型对话页确认的 ID必须与服务端一致注意Key 不要硬编码进提交到 Git 的代码里本文示例为了直观直接写在代码中你实际项目里请用环境变量或.env文件读取。如果你后续打算长期跑编码类 Agent 或者多智能体流水线可以顺带看一下 Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_plan 它面向的是持续编码和 Agent 场景的用量方案和本文的入门验证不冲突先跑通再考虑。3. 可复制配置环境初始化与 Agent 定义片段这一节是全文的核心操作区所有代码都可以直接复制运行。先建虚拟环境再装依赖然后写模型配置文件最后逐层往上搭 Agent 和 Team。3.1 环境初始化与依赖安装建议用 Python 3.10 以上版本Agno 对异步和类型标注用得比较多版本太低容易出兼容问题。命令如下python -m venv agno-env source agno-env/bin/activate pip install -U agno openai python-dotenvWindows 下激活命令换成agno-env\Scripts\activate。装完之后验证一下python -c import agno; print(agno.__version__)能打印出版本号就说明装好了。如果报ModuleNotFoundError检查是不是虚拟环境没激活或者 pip 装到了全局环境。3.2 模型配置文件统一 Key 接入新建一个model_config.py把 TaoToken 的统一 Key 通道封装成一个可复用的模型对象。这样后面所有 Agent 和 Team 都导入同一个对象改模型只改一处import os from dotenv import load_dotenv from agno.models.openai import OpenAILike load_dotenv() TAOTOKEN_API_KEY os.getenv(TAOTOKEN_API_KEY, sk-你的Key) TAOTOKEN_BASE_URL https://taotoken.net/api MODEL_ID os.getenv(TAOTOKEN_MODEL_ID, 你的模型ID) open_ai_like_model OpenAILike( idMODEL_ID, base_urlTAOTOKEN_BASE_URL, api_keyTAOTOKEN_API_KEY, )配套的.env文件TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_MODEL_ID你的模型ID这里三个参数必须齐全id是模型 IDbase_url是https://taotoken.net/apiapi_key是控制台拿到的 Key。少任何一个都会在请求阶段报错具体报错对照见第 5 节。3.3 单 Agent 冒烟测试新建single_agent.py先验证最小可用链路from agno.agent import Agent from model_config import open_ai_like_model agent Agent( modelopen_ai_like_model, description你是一个简洁的中文助手, markdownTrue, ) agent.print_response(用两句话介绍你自己, streamTrue)运行python single_agent.py预期看到流式输出两句话的自我介绍。这一步通了说明 Key、base_url、模型 ID 三者都对后面再往上加存储和工具。3.4 带会话存储的 Agent 配置会话存储用 SQLite 最省事不用额外起数据库服务。新建agent_with_db.pyfrom agno.agent import Agent from agno.db.sqlite import SqliteDb from model_config import open_ai_like_model db SqliteDb(db_filetmp/agno_session.db, session_tableagno_session) agent Agent( description你是一个小助手, modelopen_ai_like_model, dbdb, add_history_to_contextTrue, num_history_runs2, ) agent.print_response(我叫小林记住我的名字, user_idu-001, session_ids-001) agent.print_response(我叫什么名字, user_idu-001, session_ids-001)关键参数两个add_history_to_contextTrue让历史消息进入上下文num_history_runs2控制带几轮历史。第二次提问时 Agent 应该能答出「小林」这就是会话存储生效的证据。tmp目录不存在的话先mkdir tmp否则 SQLite 建库会报路径错误。3.5 带工具的 Agent 配置工具用自定义函数最直观也方便你理解工具描述是怎么传给模型的。新建agent_with_tool.pyfrom agno.agent import Agent from model_config import open_ai_like_model def get_weather(city: str) - str: 查询指定城市的天气。 Args: city(str): 城市名称。 return f{city} 今天晴气温 22 到 28 度微风。 agent Agent( modelopen_ai_like_model, tools[get_weather], description你是一个天气助手, markdownTrue, debug_modeTrue, ) agent.print_response(杭州今天天气怎么样, streamTrue)debug_modeTrue会把编译后的系统提示词和工具调用日志打出来你能看到模型是怎么决定调用get_weather的。函数 docstring 里的 Args 描述很重要模型靠它判断参数含义写清楚能显著降低调用失败率。3.6 Team 多智能体协作配置最后把两个 Agent 组成 Team新建team_demo.pyfrom agno.agent import Agent from agno.team import Team from agno.utils.pprint import pprint_run_response from model_config import open_ai_like_model def get_news(topic: str) - str: 获取指定话题的最新新闻。 Args: topic(str): 新闻话题。 return f关于 {topic} 的最新消息某科技公司发布了新一代开源框架。 def get_weather(city: str) - str: 查询指定城市的天气。 Args: city(str): 城市名称。 return f{city} 今天晴气温 22 到 28 度微风。 news_agent Agent( modelopen_ai_like_model, roleNews agent, tools[get_news], description负责获取最新新闻, ) weather_agent Agent( modelopen_ai_like_model, roleWeather agent, tools[get_weather], description负责查询未来三天天气, ) team Team( modelopen_ai_like_model, nameNews and Weather Team, members[news_agent, weather_agent], ) result team.run(input杭州今天天气怎么样, debug_modeTrue) pprint_run_response(result)这段配置里Team的model是给 Leader 用的负责判断把任务分给哪个 Member每个 Member 的role和description是 Leader 做路由决策的依据写清楚比写花哨更重要。运行后预期看到 Leader 把「杭州天气」这个任务分派给weather_agent最终输出天气结果。4. 验证请求与成功结果从单 Agent 到 Team 链路配置写完不算完得逐层验证。我按「单 Agent → 会话 → 工具 → Team」的顺序走一遍每一层给出你该看到的输出特征对不上就停下来排查别急着往上叠。第一层单 Agent 冒烟。运行single_agent.py终端应该流式吐出两句话内容大意是「我是一个基于大模型的助手可以回答问题、协助写作」。如果输出为空或者报 401直接跳到第 5 节看认证类报错。如果输出是乱码或者截断检查streamTrue下终端编码Windows 可以临时chcp 65001。第二层会话存储。运行agent_with_db.py第一次提问后tmp/agno_session.db文件应该被创建出来用sqlite3 tmp/agno_session.db .tables能看到agno_session表。第二次提问的输出里应该出现「小林」这个名字。如果第二次答不出名字检查session_id和user_id两次是否一致以及add_history_to_context是否为 True。第三层工具调用。运行agent_with_tool.py因为开了debug_modeTrue你会先看到一段系统提示词日志里面有工具名get_weather和参数说明然后看到模型返回的工具调用请求参数是{city: 杭州}接着工具返回天气字符串最后模型组织成自然语言回答。预期最终输出类似「杭州今天晴气温 22 到 28 度微风」。如果模型没调工具而是直接编了个天气说明工具描述不够清晰或者模型没理解把 docstring 写得更具体再试。第四层Team 协作。运行team_demo.pydebug_modeTrue下你能看到 Leader 的系统提示词里列出了两个 Member 的 ID、role 和工具列表。预期日志顺序是Leader 分析问题 → 决定委派给weather_agent→weather_agent调用get_weather→ 返回结果给 Leader → Leader 汇总输出。最终pprint_run_response打印的结果里应该包含杭州天气信息且不包含新闻内容说明路由正确。再补一个组合问题的验证把team.run的输入改成「杭州天气怎么样顺便看看有什么科技新闻」预期 Leader 会同时或依次委派给两个 Member最终输出里天气和新闻都有。这一步能验证多 Member 协作是否真的生效而不是只走了单条分支。如果你想把验证过程做成可重复的脚本可以在每个文件末尾加断言比如检查输出字符串里是否包含关键词。这样每次改配置后跑一遍比肉眼看输出可靠。验证通过后这套配置就可以作为你后续项目的骨架换模型只改model_config.py加 Agent 只加 Member。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来每个报错给出触发场景和修复动作。你遇到问题时先对号入座别盲目改代码。401 Unauthorized / invalid api key。最常见原因是api_key不对。检查三处.env里的 Key 是否完整复制有没有多余空格或换行、代码里os.getenv的变量名是否和.env一致、Key 是否已经在控制台被删除或过期。修复动作是重新去 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentconsole 创建一个新 Key 替换。注意 Key 只在创建时完整显示一次复制时别漏字符。local proxy failed / connection refused。这个报错通常出现在base_url写错或者网络出口配置有问题时。先确认base_url是https://taotoken.net/api没有多余路径、没有/v1、没有尾部斜杠。如果你本地配了系统级网络设置检查它是否影响了 Python 的请求最直接的办法是在干净终端里用curl -I https://taotoken.net/api看能否通。另外检查是不是把base_url写成了带查询参数的完整 URLOpenAILike 不接受这种形式。Error reading choices / choices 字段为空。这个报错说明请求发出去了、服务端也回了但返回体结构不符合 OpenAI 兼容格式或者模型 ID 不存在导致返回了错误结构。先确认MODEL_ID和模型对话页显示的完全一致大小写、连字符都别错。再检查是不是把base_url多加了/v1导致实际请求路径变成/api/v1/chat/completions服务端返回 404 页面而不是 JSON。修复后重跑单 Agent 冒烟测试确认。OAuth / authentication flow 相关报错。如果你在 Agno 里用了某些需要 OAuth 的工具或 MCP 服务可能会看到这类提示。本文的模型通道走的是 API Key不涉及 OAuth如果你确实要接 OAuth 类工具先把它从tools列表里摘掉确认模型链路通了再单独接。排查顺序永远是先隔离模型层再查工具层。Team 路由错误任务分给了错误的 Member。这不是报错是行为不符合预期。原因通常是 Member 的role和description写得太模糊Leader 判断不了。修复动作是把 role 写成明确的职责短语description 里写清楚「负责什么、不负责什么」工具 docstring 也同步改清楚。改完开debug_modeTrue看 Leader 的系统提示词确认 Member 信息被正确注入。SQLite 报 unable to open database file。tmp目录不存在。先mkdir -p tmp再跑。如果你在 Windows 上路径分隔符用/也能被 SQLite 接受但目录必须真实存在。流式输出卡住或只输出一半。检查streamTrue时是否在异步环境里用了同步方法或者终端缓冲导致看起来卡住。可以先改成非流式streamFalse确认结果完整再切回流式。另外print_response和run的返回结构不同别混用。提示排错时把debug_modeTrue打开日志里能看到完整的请求参数和响应结构比猜快得多。定位到具体层之后再关掉避免日志刷屏。6. 下一步怎么走从跑通到长期使用的接入路径跑通上面这套链路之后你手里已经有一个可复用的骨架统一 Key 的模型配置、单 Agent、带存储的会话、带工具的 Agent、Team 协作。接下来往哪个方向走取决于你的实际场景。如果你要继续做模型调用层的验证和调试比如换模型对比输出质量、测试不同参数下的表现直接去模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chat 手动试比改代码快。确认某个模型适合你的场景后再把它的 ID 写回model_config.py。如果你要把这套东西接到自己的项目里重点看接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc 里面把 base_url、认证方式、请求格式讲清楚了和本文的配置能对上。Key 管理统一在 API Keys 页面 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentconsole 做建议给不同项目建不同的 Key方便单独吊销。如果你打算长期跑编码类 Agent 或者多智能体流水线比如让 Team 持续处理任务、接 CI 流程那 Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_plan 是更匹配的用量方案可以先了解再决定是否切换。最后给一个实操建议把本文的model_config.py作为你所有 Agno 项目的公共模块Agent 和 Team 只导入模型对象不重复写 base_url 和 Key。这样以后换模型、换 Key、加备用通道都只改一个文件。我试过在三个小项目里这么干维护成本明显低。跑通之后别停在示例上把get_weather换成你真实要调的工具把 Team 的 Member 换成你业务里的角色这套骨架就能直接长成你的应用。
阅读完成 · 觉得有帮助？
