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」的 Team，Leader 根据用户问题自动分派任务，最终返回聚合结果。中间会经过单 Agent 冒烟测试、会话存储验证、工具调用验证三个关卡，任何一关卡住都能在排错章节找到对应报错。

2. TaoToken 前置准备：统一 Key 与模型通道配置

在写 Agno 代码之前，先把模型通道准备好。TaoToken 的角色是给你一个统一的 API 入口和 Key，Agno 这边只需要按 OpenAILike 的方式填 base_url、api_key、model id 三个值就行。这一步不涉及任何复杂配置，但顺序别搞反：先拿 Key，再确认模型 ID，最后写进代码。

第一步，打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册并登录，进入控制台。控制台里找到 API Keys 页面，路径是 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=console ，点创建新 Key，复制出来保存好。这个 Key 就是后面所有配置里的api_key值，格式通常是一串以固定前缀开头的字符串，别弄丢，页面关闭后不一定能再次完整查看。

第二步，确认你要用的模型 ID。Agno 的 OpenAILike 需要传id参数，这个 id 必须和服务端支持的模型名完全一致。你可以在模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat 里先手动发一条消息验证模型可用，页面上会显示当前可选的模型列表。选一个你打算长期用的，比如通用的对话模型或者代码能力强的模型，把它的 ID 记下来。本文示例里我用一个通用对话模型，你替换成自己账号下可用的即可。

第三步，确认 API 基础地址。TaoToken 的 API 入口是 https://taotoken.net/api ，注意这里不带任何查询参数，直接作为 base_url 使用。Agno 的 OpenAILike 内部会在这个 base_url 后面拼/chat/completions，所以你不要自己再加/v1之类的后缀，填https://taotoken.net/api就行。这一点很容易踩坑，后面排错章节会专门讲。

把这三个值整理成一张对照表，写代码时直接对照填：

注意：Key 不要硬编码进提交到 Git 的代码里，本文示例为了直观直接写在代码中，你实际项目里请用环境变量或.env文件读取。

如果你后续打算长期跑编码类 Agent 或者多智能体流水线，可以顺带看一下 Coding Plan 页面 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_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-dotenv

Windows 下激活命令换成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( id=MODEL_ID, base_url=TAOTOKEN_BASE_URL, api_key=TAOTOKEN_API_KEY, )

配套的.env文件：

TAOTOKEN_API_KEY=sk-你的Key TAOTOKEN_MODEL_ID=你的模型ID

这里三个参数必须齐全：id是模型 ID，base_url是https://taotoken.net/api，api_key是控制台拿到的 Key。少任何一个都会在请求阶段报错，具体报错对照见第 5 节。

3.3 单 Agent 冒烟测试

新建single_agent.py，先验证最小可用链路：

from agno.agent import Agent from model_config import open_ai_like_model agent = Agent( model=open_ai_like_model, description="你是一个简洁的中文助手", markdown=True, ) agent.print_response("用两句话介绍你自己", stream=True)

运行python single_agent.py，预期看到流式输出两句话的自我介绍。这一步通了，说明 Key、base_url、模型 ID 三者都对，后面再往上加存储和工具。

3.4 带会话存储的 Agent 配置

会话存储用 SQLite 最省事，不用额外起数据库服务。新建agent_with_db.py：

from agno.agent import Agent from agno.db.sqlite import SqliteDb from model_config import open_ai_like_model db = SqliteDb(db_file="tmp/agno_session.db", session_table="agno_session") agent = Agent( description="你是一个小助手", model=open_ai_like_model, db=db, add_history_to_context=True, num_history_runs=2, ) agent.print_response("我叫小林，记住我的名字", user_id="u-001", session_id="s-001") agent.print_response("我叫什么名字", user_id="u-001", session_id="s-001")

关键参数两个：add_history_to_context=True让历史消息进入上下文，num_history_runs=2控制带几轮历史。第二次提问时 Agent 应该能答出「小林」，这就是会话存储生效的证据。tmp目录不存在的话先mkdir tmp，否则 SQLite 建库会报路径错误。

3.5 带工具的 Agent 配置

工具用自定义函数最直观，也方便你理解工具描述是怎么传给模型的。新建agent_with_tool.py：

from 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( model=open_ai_like_model, tools=[get_weather], description="你是一个天气助手", markdown=True, debug_mode=True, ) agent.print_response("杭州今天天气怎么样", stream=True)

debug_mode=True会把编译后的系统提示词和工具调用日志打出来，你能看到模型是怎么决定调用get_weather的。函数 docstring 里的 Args 描述很重要，模型靠它判断参数含义，写清楚能显著降低调用失败率。

3.6 Team 多智能体协作配置

最后把两个 Agent 组成 Team，新建team_demo.py：

from 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( model=open_ai_like_model, role="News agent", tools=[get_news], description="负责获取最新新闻", ) weather_agent = Agent( model=open_ai_like_model, role="Weather agent", tools=[get_weather], description="负责查询未来三天天气", ) team = Team( model=open_ai_like_model, name="News and Weather Team", members=[news_agent, weather_agent], ) result = team.run(input="杭州今天天气怎么样", debug_mode=True) 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 节看认证类报错。如果输出是乱码或者截断，检查stream=True下终端编码，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_mode=True，你会先看到一段系统提示词日志，里面有工具名get_weather和参数说明；然后看到模型返回的工具调用请求，参数是{"city": "杭州"}；接着工具返回天气字符串；最后模型组织成自然语言回答。预期最终输出类似「杭州今天晴，气温 22 到 28 度，微风」。如果模型没调工具而是直接编了个天气，说明工具描述不够清晰或者模型没理解，把 docstring 写得更具体再试。

第四层，Team 协作。运行team_demo.py，debug_mode=True下你能看到 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_source=taotoken_aicg_blog_end&utm_content=console 创建一个新 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写成了带查询参数的完整 URL，OpenAILike 不接受这种形式。

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_mode=True看 Leader 的系统提示词，确认 Member 信息被正确注入。

SQLite 报 unable to open database file。tmp目录不存在。先mkdir -p tmp再跑。如果你在 Windows 上，路径分隔符用/也能被 SQLite 接受，但目录必须真实存在。

流式输出卡住或只输出一半。检查stream=True时是否在异步环境里用了同步方法，或者终端缓冲导致看起来卡住。可以先改成非流式stream=False确认结果完整，再切回流式。另外print_response和run的返回结构不同，别混用。

提示：排错时把debug_mode=True打开，日志里能看到完整的请求参数和响应结构，比猜快得多。定位到具体层之后再关掉，避免日志刷屏。

6. 下一步怎么走：从跑通到长期使用的接入路径

跑通上面这套链路之后，你手里已经有一个可复用的骨架：统一 Key 的模型配置、单 Agent、带存储的会话、带工具的 Agent、Team 协作。接下来往哪个方向走，取决于你的实际场景。

如果你要继续做模型调用层的验证和调试，比如换模型对比输出质量、测试不同参数下的表现，直接去模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat 手动试，比改代码快。确认某个模型适合你的场景后，再把它的 ID 写回model_config.py。

如果你要把这套东西接到自己的项目里，重点看接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc ，里面把 base_url、认证方式、请求格式讲清楚了，和本文的配置能对上。Key 管理统一在 API Keys 页面 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=console 做，建议给不同项目建不同的 Key，方便单独吊销。

如果你打算长期跑编码类 Agent 或者多智能体流水线，比如让 Team 持续处理任务、接 CI 流程，那 Coding Plan 页面 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan 是更匹配的用量方案，可以先了解再决定是否切换。

最后给一个实操建议：把本文的model_config.py作为你所有 Agno 项目的公共模块，Agent 和 Team 只导入模型对象，不重复写 base_url 和 Key。这样以后换模型、换 Key、加备用通道，都只改一个文件。我试过在三个小项目里这么干，维护成本明显低。跑通之后别停在示例上，把get_weather换成你真实要调的工具，把 Team 的 Member 换成你业务里的角色，这套骨架就能直接长成你的应用。