Agno

Agno 快速入门

一站式 Agent 平台 —— 从构建到运行到管理，Agno 帮你搞定 Agent 全生命周期。

这是什么？适合谁？

Agno（前身 phidata，2024 年底改名）是定位「Build, run, and manage agent platforms」的全栈 Agent 框架。它不只是一个 SDK，而是 SDK + AgentOS Runtime + AgentOS UI 三件套——把 Agent 开发、生产 API、存储、上下文、人在环、可观测、安全、调度、部署全部打包。GitHub 41.4K+ stars（截至 2026-07），Apache-2.0 开源，当前版本 v2.8.0（2026-07 发布，含 team_id 嵌套支持）。

它的核心定位跟 LangChain / OpenAI Agents SDK 显著不同：

• LangChain 是「库」——给你零件自己拼。
• OpenAI Agents SDK 是「SDK」——让你写 Python 代码构建 Agent。
• Agno 是「生产平台」——SDK 写完 Agent 后，一键部署成一个有 REST API、Web UI、Postgres 数据库、MCP server、control plane 的完整服务。

仓库 README 给出的「20 行代码第一个 Agent」+「一键 Docker 部署 AgentOS」是核心卖点。配套的 agentos-railway / agentos-docker / agentos-aws / agentos-gcp / agentos-azure / agentos-fly / agentos-render / agentos-modal / agentos-helm 九套模板覆盖主流云平台。

适合谁？一是想做「Agent 产品」（多用户、有 API、有 dashboard）的创业团队——AgentOS 全套组件齐全；二是企业级多租户 SaaS（JWT RBAC + multi-tenant isolation 是开箱即用）；三是要可观测 + 审计的团队（OpenTelemetry + run history + audit logs）。不适合：只想写个本地 demo 的人（LangChain / smolagents 更轻）；也不适合不想用 Docker 的纯本地开发（AgentOS 设计围绕容器化部署）。

准备工作

1. Python 3.10 及以上：访问 python.org 下载安装。
2. Docker + Docker Compose：跑 AgentOS 完整栈需要 Docker（推荐 Desktop for Windows/macOS）。
3. LLM API Key：OpenAI / Anthropic / Gemini / 任意 100+ provider，Agno 通过统一接口支持。
4. （可选）云平台账号：要部署到 Railway / Render / AWS / GCP 等需要对应平台账号。

环境变量：OPENAI_API_KEY（或对应厂商 key），生产环境还会用到 DB_URL、JWT_SECRET。

3 步快速上手

第 1 步：安装 Agno SDK

pip install agno

可选 extras（接数据库、向量库等）：pip install "agno[postgres,redis,chroma,pgvector]"

第 2 步：创建第一个 Agent

新建 hello_agent.py：

from agno.agent import Agent
from agno.models.openai import OpenAIChat

agent = Agent(
    name="助手",
    model=OpenAIChat(id="gpt-4o-mini"),
    instructions=["你是一个有帮助的中文助手，回答简洁。"],
    markdown=True,
)

response = agent.run("写一首关于秋天的五言绝句。")
print(response.content)

agent.run() 同步调用返回 RunResponse，带 content / metrics / messages 等字段。如果要流式响应用 agent.run("...", stream=True)，会逐 token yield 事件。

第 3 步：部署到 AgentOS

最快的方式是克隆官方模板仓库：

git clone https://github.com/agno-agi/agentos-railway
cd agentos-railway
# 编辑 .env 配置 API Key
docker compose up

启动后会得到：

• REST API：http://localhost:8000/v1/...（50+ endpoints）
• AgentOS UI：http://localhost:3000（管理面板）
• Postgres（会话/记忆/知识/trace 存储）
• MCP server（让其他 Agent 调用）
• Control plane（多 Agent 编排）

也可以用 Railway / Render / AWS / GCP 等云平台的一键部署按钮（README 有图标）。

常见踩坑

以下踩坑均基于真实的 Agno GitHub Issue 和研究报告（agno-agi/agno 41.4K★），每条均有可验证的 issue 链接。

踩坑 1：tool_call_limit 设了但 Agent 仍在无限重试工具

• 症状：设置 tool_call_limit=N 后，Agno 并不终止运行——工具调用达到上限后，Agent 继续把”limit reached” 错误发给模型，模型无视错误继续重试同一工具。最严重时一个用户消息触发了 ~4000 次工具调用才 timeout。
• 原因：tool_call_limit 在 Agno 中是软限制（阻止工具执行），不是硬停止（终止 run）。Agent loop 每次收到含 limit error 的 batch 后，依然无条件继续 continue，把错误发回给模型，模型收到”Tool call limit reached. Tool call not executed.” 后继续重试同一个工具调用，形成死循环。根本原因是 loop 缺少「全部工具调用失败则中断」的逻辑。
• 解决：该问题已在 PR #8324 中提出修复方案——当 batch 中所有 tool call 都有 tool_call_error=True 时立即 break loop。当前版本中建议通过 feature flag 禁用 tool_call_limit 作为 workaround；或在外层用 Python asyncio.timeout() 包裹 agent.run() 做硬超时兜底。
• 参考：Issue #8304（Open, 11👍, Agno 2.6.0, GPT-4o）

踩坑 2：Telemetry 是同步的——每次 agent.run() 多 1 秒延迟

• 症状：对比纯 HTTP 调 LLM（~0.13s），agent.run() 慢了整整 1 秒（telemetry=True 时 1.147s, telemetry=False 时 0.108s）。使用本地模型（Ollama/llama.cpp）的用户感受最明显——一次简单查询等 1 秒才出字。
• 原因：在 agno/api/agent.py 中，create_agent_run() 是同步阻塞的——每次 agent.run() 返回前必须等 HTTP POST 发到 api.agno.com 完成。两个问题叠加：(1) 每次 new 一个 httpx.Client（~29ms 开销），(2) 网络请求完全阻塞主线程。用云端 API 的用户不太注意，因为 LLM 本身网络延迟（~200-500ms）遮盖了这 1s 额外开销。
• 解决：立即关掉 telemetry：Agent(..., telemetry=False) 或设环境变量 AGNO_TELEMETRY=false。多个 PR（#8189、#8194）已提出修复——把 telemetry POST 包装到 daemon thread（同步）或 asyncio.create_task()（异步）中 fire-and-forget。
• 参考：Issue #8181（Open, Agno 2.5.17）；关联：#8294—Team.telemetry=True 在 api.agno.com 不可达时造成 60s 延迟

踩坑 3：MCP Server 断线后 Agent 永远不恢复工具连接

• 症状：两种模式：① MCP server 在 Agent 初始化时没启动 → 工具注册失败，Agent 整个生命周期都无法调用 MCP 工具，永远不会主动恢复；② MCP server 运行中重启 → Agent 不自动重连，所有后续工具调用全部失败。
• 原因：MCPTools 类（streamable-http 或 SSE transport）只在 init 时做一次工具发现（one-shot discovery），之后完全没有 reconnection 逻辑、健康检查、或周期刷新机制。连接一断就永久性丢失工具列表。
• 解决：当前唯一 workaround——MCP server 重启时也必须重启整个 Agent 进程。容器化环境（K8s）中建议把 MCP server 作为 sidecar 运行，与 Agent 容器共享生命周期。Agno 维护者已确认该问题并在规划自动重试工具发现 + 改进日志。
• 参考：Issue #3724（Closed, 22 条评论, 4👍）；关联：#4573—FastMCP 自定义 server 不注册工具

踩坑 4：AgentOS 多用户模式下 JWT 用户可跨账号读写数据和会话

• 症状：在 Multi-User AgentOS（authorization=True、JWT 认证开启）中，已验证的用户 A 可以读取和删除用户 B 的 session、session state、memory。不需要任何提权操作。
• 原因：libs/agno/agno/os/middleware/user_scope.py 中，配套设置 user_isolation 默认是 False。在这个默认值下，get_scoped_user_id() 永远返回 None，所以每个 session/memory 端点都接受调用者传入的 ?user_id= 参数作为数据过滤器。更严重的是 GET /sessions/{session_id} 连 user_id 参数都不需要——任何已认证用户都能访问任何 session。
• 解决：多用户生产环境必须显式设置 user_isolation=True。项目方认为 False 默认为了向后兼容可以理解，但这意味着默认配置下即使 JWT 认证已开启，也没有任何用户级数据隔离。影响范围：GET/DELETE/PATCH /sessions/*、/memories/* 及相关 trace/metrics 路由。
• 参考：Issue #8738（Closed, Bug）；关联：#8633—AG-UI 在前缀挂载时绕过 AgentOS JWT、#8629—A2A 接口绕过 AgentOS JWT

踩坑 5：KnowledgeBase 加载时报 LanceDB 向量列维度不匹配

• 症状：knowledge_base.load() 时报错：

  ValueError: Vector column 'vector' has variable length vectors.
  Set on_bad_vectors='drop' to remove them, or set on_bad_vectors='fill'
  and fill_value=<value> to replace them.
  

  多见于多 PDF 文件加载场景。
• 原因：LanceDB 的 vector column 要求所有向量同维度。当 KnowledgeBase 处理来自不同源的多个文档时，如果 embedder（比如 OllamaEmbedder）对不同文件产生了不同维度的向量——或 LanceDB 表是用旧 embedder 配置创建的——load() 就因为新向量不匹配现有 schema 而失败。
• 解决：① knowledge_base.load(recreate=True) 重建表；② 删除已有 LanceDB 存储文件后重新加载；③ PR #2102 已优化 LanceDB 的维度处理逻辑，确保 embedder 一致仍是关键。
• 参考：Issue #1865（Closed, 8 条评论, 合并于 #2102）；关联：#5525—PgVector 也报”expected 1024 dimensions, not 1536”

踩坑 6：pip install agno 成功，但运行时缺 packaging 模块

• 症状：pip install agno 安装成功无报错，但一跑用到 agno.tools.function 的代码就崩溃：

  ModuleNotFoundError: No module named 'packaging'
  

  CI/CD 环境、Docker 镜像、纯净 venv 中最容易出现。
• 原因：Commit e9a4145 在 agno/tools/function.py 中加了一行 from packaging.version import Version，但忘了把 packaging 加进 pyproject.toml 的 dependencies 列表。packaging 在大多数开发环境是传递依赖（被 pip、setuptools 等携带），但在纯净/容器化环境不一定存在。
• 解决：PR #4153 已修复——在 libs/agno/pyproject.toml 的 dependencies 中加上了 "packaging"。升级到修复版即可。Workaround：pip install packaging 和 agno 一起装。
• 参考：Issue #4142（Closed, 合并于 #4153, 4👍）

踩坑 7：AG-UI 丢弃工具调用历史 → HITL 工具无限循环重触发

• 症状：@tool(external_execution=True)（人在环, HITL）结合 AG-UI（比如 CopilotKit）使用时，用户点「批准」后工具不执行，反而重新生成一个新的 run，从最初的用户 prompt 开始执行。点多少次批复发多少次。
• 原因：Agno 2.5.10 → 2.6.x 的回归。在 agno/os/interfaces/agui/router.py 中，2.5.10 用 convert_agui_messages_to_agno_messages() 完整保留了 AG-UI 消息历史（含 role==\"tool\" 结果）。2.6.x 改为 extract_agui_user_input()——只保留最后一条用户文本消息，其余全靠 session DB 恢复历史。但问题在于：tool result 消息既不是用户消息、也还没持久化到 session DB（run 还在暂停状态），所以就被默默丢弃了。Agent 只看到自己上次留下的 external_execution 工具调用没返回，于是重新发起一次。
• 解决：恢复 2.5.10 的行为——把完整的 AG-UI 消息历史（含 tool result）传给 arun()。main 分支已修复，升级即可。
• 参考：Issue #8229（Closed, Agno 2.6.11 坏 / 2.5.10 正常）；关联：#7802—2.5.10 修好的原 bug

初级用法

• 单 Agent：上面示例就是——Agent(name=..., model=..., instructions=[...]) + agent.run("...")。
• @tool 装饰器：from agno.tools import tool，写 Python 函数 + docstring，一行定义 Agent 能调的工具。
• 内置工具：from agno.tools.duckduckgo import DuckDuckGoTools、from agno.tools.yfinance import YFinanceTools，几十个开箱即用。
• Knowledge / RAG：Agent(knowledge=PDFKnowledgeBase(path="docs/"))，自动向量化 + 检索增强回答。
• Storage 持久化：Agent(storage=SqliteStorage("agent.db"))，跨 run 保留会话历史。
• Memory：Agent(memory=AgentMemory(create_user_memories=True))，让 Agent 跨会话记住用户偏好。
• Team 模式：Agent(team=[agent_a, agent_b])，多 Agent 协作（Team 是 Agno 的核心差异化能力）。
• Stream 输出：agent.run("...", stream=True) 逐 token yield，适合接 SSE / WebSocket。

高级玩法

• AgentOS Runtime：把 Agent 部署成生产 REST API（50+ endpoints、SSE 流式、WebSocket、batch runs、async jobs）。
• 100+ Toolkits：GitHub / Slack / Postgres / Google Sheets / Stripe / Notion 等开箱即用工具集成。
• Context Providers：运行时从 Slack / Drive / Wiki / MCP / 自定义源拉取实时上下文。
• Human Approval：关键工具（删除数据库、发邮件、转账）执行前暂停等用户确认。
• Multi-tenant + JWT RBAC：原生支持多用户、多租户、基于 JWT 的角色权限控制。
• OpenTelemetry Observability：所有 run / tool call / message 都有 trace，可对接 Langfuse / Arize / Datadog。
• Interfaces：AgentOS 暴露 Slack / Telegram / WhatsApp / Discord / AG-UI / A2A 多种接入方式。
• Scheduling：内置 cron-based 定时任务调度，不依赖外部 scheduler。
• A2A Protocol：Agno 是 Agent-to-Agent 协议的早期实现者，Agent 之间可以跨平台互操作。
• Eval / Simulations：agentos eval 跑 evalset 评估 Agent 质量。
• Coding Agent 集成：把 Agno 文档作为 MCP server 加进 Claude Code / Cursor / Codex，AI 直接读 Agno 最新文档写代码。

小技巧

1. 先用本地 SQLite 跑通：生产再换 Postgres。storage=SqliteStorage("agent.db") 一行搞定。
2. 关闭 telemetry：生产环境第一时间设 AGNO_TELEMETRY=false。
3. Team 模式设 max_iterations：防止 Agent 之间互 delegate 死循环。
4. Toolkit docstring 写完整：内置工具的 docstring 一般够用，自定义 tool 必须把「用途、参数、返回、何时调用、何时不调用」五要素写清楚。
5. Docker 部署看 logs：第一次跑 docker compose up，盯 Postgres 日志确认迁移成功，再访问 UI。
6. AGNO_TELEMETRY=false：开箱即用关掉。
7. Coding Agent 用 docs.agno.com/mcp：把 Agno 文档作为 MCP 加进 Cursor/Claude Code，AI 自动按官方最新 API 写代码。
8. AgentOS 自带 PostgreSQL：用 agentos-railway 模板就内置了 Postgres + pgvector，无需自己装向量库。

进阶学习建议

如果你想从「能跑通 SDK」走到「能部署 Agent 产品」，按这条路径走最快：

1. 先看官方 README + docs.agno.com/first-agent：5 分钟跑通第一个 Agent。
2. 学 SDK → Runtime → UI 三件套：理解 SDK 写 Agent、AgentOS 起服务、UI 管平台的三层模型。
3. 接 Knowledge + Memory：用 PDFKnowledgeBase + AgentMemory 让 Agent 能查文档 + 记住用户。
4. Team 模式做多 Agent 协作：Agno 的 Team 模式是核心差异化能力，把研究 Agent + 写作 Agent + 审校 Agent 组起来。
5. 本地跑 AgentOS：克隆 agentos-docker 模板，docker compose up 把整套服务起起来。
6. 生产部署：上 Railway / Render / AWS / GCP，配 JWT RBAC + OpenTelemetry。
7. 加 A2A / AG-UI 接口：让 Agent 能被其他 Agent 或前端框架调用。

可以对比阅读的几个相关项目：LangChain、OpenAI Agents SDK、Google ADK、CowAgent。

FAQ

Q1: Agno 是免费的吗？

A1: 软件 Apache-2.0 开源免费。运行成本 = 模型 API 调用费（OpenAI GPT-4o-mini 约 $0.15/M input）+ 云平台费用（Railway 免费额度够 demo，Render 免费层不能用 persistent disk 需要付费）。本地跑用 SQLite + Ollama 可以做到 0 边际成本。

Q2: 跟 LangChain 比有什么区别？

A2: LangChain 是「Python 库」，你要自己写部署代码（FastAPI + Docker + DB）；Agno 是「完整平台」，AgentOS Runtime + Web UI + REST API + Postgres + JWT RBAC 都内置，少写 80% 的胶水代码。如果你只想写 Agent 逻辑、部署自己想完全掌控，选 LangChain；如果你想快速把 Agent 变成可上线的产品，选 Agno。

Q3: phidata 改名 agno 后还能用吗？

A3: 老 phidata 项目已停止维护，但仍然能装（pip install phidata）。新项目直接用 pip install agno，所有 import path 改成 from agno.xxx import ...。Agno v2.x 是当前主线，v1.x 老 phidata 兼容模式只用于迁移期。

Q4: 必须用 AgentOS 吗？

A4: 不是。Agno SDK 可以单独用——Agent(...) + agent.run(...) 就是普通的 Python 调用，跟 LangChain 一样轻。AgentOS 是可选的「生产部署包」，需要 Docker / Postgres 时才用。本地学习 / 跑 demo 不需要 AgentOS。

Q5: 跟 Manus / Devin 这类「自主 Agent 产品」是一个赛道吗？

A5: 不是。Manus / Devin 是「接到任务、自主执行」的消费级 Agent 产品（云端托管，有沙箱浏览器/桌面环境）；Agno 是「给开发者用的 Agent 平台框架」——你用 Agno 搭 Agent、部署 Agent、做 Agent 产品，但用户不直接用 Agno。两者的关系类似「Next.js vs ChatGPT」——一个是开发框架，一个是终端产品。

Q6: 100+ tools 具体包含哪些？

A6: 包括 GitHub / Slack / Postgres / Google Sheets / Gmail / Notion / Stripe / Linear / Jira / Salesforce / HubSpot / Discord / Telegram / YouTube / Spotify / HackerNews / ArXiv / Wikipedia / DuckDuckGo / Google Search / YFinance / Calculator / FileTools / ShellTools / PythonTools 等。完整列表看 docs.agno.com/tools/toolkits/overview。

参考链接

• Agno 官方文档
• Agno GitHub
• AgentOS Railway 模板
• AgentOS Docker 模板
• 20 行代码第一个 Agent 教程

免责声明

本文涉及的 GitHub stars 数、版本号、价格等信息基于公开资料整理（截至 2026-07），实际数据请以各项目仓库为准。Agno 项目仍在快速迭代（v2.7 → v2.8 间隔 2 周），API 接口和 config schema 可能在后续版本变化，部署到生产前请阅读最新 README 和 CHANGELOG。文中代码示例仅供学习参考，请在遵循各项目许可证的前提下使用。