agno-agi/agno · 上手攻略

• 仓库：agno-agi/agno
• 链接：https://github.com/agno-agi/agno
• 分类：ai / agent framework
• 作者：Tom
• 更新：2026-07-11

这是什么

Agno 是一个生产级的 Agent 平台框架（用 Python 编写），包含两层核心组件：

• Agno SDK：用于构建单个或多个 Agent，提供工具调用、记忆管理、上下文注入等能力
• AgentOS 运行时：完整的 Agent 平台后端——FastAPI 服务 + SQLite/PostgreSQL 存储 + JWT RBAC + OpenTelemetry 追踪

它的定位比"写一个 Agent 脚本"更高，直接帮你搭建一个多租户、多 Agent、可观测、支持 100+ 工具集成的生产平台。官方口号是"Build, run, and manage your own agent platform"。

当前版本为 Production 成熟度（Stars 41086，最近更新 2026-07-10），比大多数同类框架更成熟。

解决什么问题

企业构建 Agent 系统时，每个团队都在重复造同样的轮子： - Agent 运行服务（流式响应、批量处理） - Session 存储和历史上下文管理 - JWT 认证和权限控制 - OpenTelemetry 可观测性埋点 - 100+ 工具接入（Slack、Drive、MCP等）

Agno 的 AgentOS 把这些全部打包好，开发者只需写业务逻辑（定义 Agent、选择模型、配置工具），其他交给运行时。

快速安装

基础安装

uv venv --python 3.12
source .venv/bin/activate       # Linux/macOS
# .venv\Scripts\activate        # Windows

uv pip install -U agno openai

⚠️ Python 版本：官方推荐 3.12+。3.11 可能兼容，3.10 以下未测试。

AgentOS 完整套件（含数据库、UI）

uv pip install -U 'agno[os]'

验证安装

python -c "import agno; print(agno.__version__)"

核心用法

1. 写一个最简单的 Agent（20 行）

sorting_hat.py：

from pathlib import Path
from agno.agent import Agent
from agno.tools.workspace import Workspace

folder = Path(__file__).parent

sorting_hat = Agent(
    name="Sorting Hat",
    model="openai:gpt-5.5",
    tools=[Workspace(root=str(folder), allowed=["read", "list", "search", "shell"])],
    instructions=(
        "Walk the folder, figure out what's there, and propose a clean organization. "
        "Return a tidy summary, a category breakdown, and a folder tree."
    ),
    markdown=True,
)

sorting_hat.print_response(f"Inventory and organize {folder}", stream=True)

运行：

export OPENAI_API_KEY=sk-...   # Linux/macOS
# setx OPENAI_API_KEY sk-...  # Windows
python sorting_hat.py

⚠️ 模型名格式：openai:gpt-5.5 是官方文档示例格式。实际可用模型 ID 需参考 OpenAI/Anthropic 官方，实际项目中常见 openai/gpt-4o、anthropic/claude-sonnet-5 等格式，具体以安装版本的 provider 配置为准。

2. 升级为有状态服务（AgentOS）

workbench.py：

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.os import AgentOS
from agno.tools.workspace import Workspace

workbench = Agent(
    name="Workbench",
    model="openai:gpt-5.5",
    db=SqliteDb(db_file="workbench.db"),  # Session 持久化
    tools=[Workspace(".")],
    enable_agentic_memory=True,            # Agent 学习使用模式
    add_history_to_context=True,
    num_history_runs=3,
)

agent_os = AgentOS(agents=[workbench], tracing=True)
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="workbench:app", reload=True)

运行：

uv pip install -U 'agno[os]' fastapi uvicorn
fastapi dev workbench.py
# 服务运行在 http://localhost:8000
# API 文档：http://localhost:8000/docs

启动后访问 os.agno.com，点 Connect OS → Local，填入 http://localhost:8000，即可用图形界面管理 Agent。

3. 核心配置项

典型适用场景

• 企业内部 Agent 平台：多团队、多租户隔离，JWT RBAC 内置
• 需要对话记忆的客服/助手：SQLite/PostgreSQL 持久化 Session
• Coding Agent 平台：用 Claude Code 等 coding agent 构建平台自身（官方推荐用法）
• 需要审批流的工作流：内置 Human Approval，可暂停 Agent 等待确认
• 跨工具集成：Slack、Drive、MCP、100+ 工具包，开箱即用
• 可观测性要求高的生产环境：OpenTelemetry tracing、审计日志

坑与注意

1. API Key 管理：Agno 默认将模型提供商使用情况用于优先级排序（可设置 AGNO_TELEMETRY=false 禁用），但 API Key 直接写代码中是安全隐患，生产环境建议用环境变量或密钥管理服务。

2. 数据库依赖：完整 AgentOS 套件需要 PostgreSQL（生产）或 SQLite（开发）。PostgreSQL 需要额外运维，如果只是快速原型，SQLite 够用但不支持多用户并发。

3. 模型支持：官方文档示例用 openai:gpt-5.5，但 GPT-5 目前（2026年7月）可能尚未正式发布。实际使用时需确认你使用的模型 ID 格式和版本兼容性，建议从 openai/gpt-4o 或 anthropic/claude-sonnet-5 开始测试。

4. os.agno.com 云端 UI：这个 UI 连接你的本地 localhost:8000，数据不经过 Agno 官方云端，但首次使用需要注册账号。

5. 部署复杂度：相比单个 Agent 脚本，AgentOS 是一整套微服务架构（FastAPI + DB + 认证），首次部署到 Railway/AWS 等平台有一定学习曲线，官方有各平台部署模板。

6. 100+ 工具集成：工具包很多是社区维护的，部分工具包的稳定性和维护状态参差不齐，使用前建议看对应 tool 的 GitHub 最近更新时间。

7. 记忆（Memory）机制：enable_agentic_memory=True 后 Agent 会自动调用 update_user_memory 工具，但记忆的组织和检索逻辑是框架自动处理的，高级定制可能需要深入源码。

与同类对比

Agno 的核心优势：开箱即用的平台级能力（存储、认证、可观测性、多渠道），省去大量基建工作。

一句话结论

如果你要构建企业内部 Agent 平台、需要开箱即用的多租户 RBAC 和 OpenTelemetry、以及需要同时支持 Slack/Discord 等多渠道，Agno AgentOS 是目前最省力的选择；如果只是写个简单 Agent 脚本，LangChain 生态更丰富、社区更大。

来源

• GitHub README：https://github.com/agno-agi/agno
• 官方文档：https://docs.agno.com
• First Agent 教程：https://docs.agno.com/first-agent
• Agent Platform 概述：https://docs.agno.com/agent-platform/overview