Agno 详解：构建、运行与管理代理平台
搭一个代理容易，把代理"运营"起来难：要有生产级 API、会话与记忆存储、权限隔离、审计追踪、定时任务，还要能接进 Slack、Telegram 这些用户所在的地方。agno-agi/agno（Agno）的口号正是"Build, run, and manage agent platforms"——它不只是代理框架，而是 SDK、运行时（AgentOS）与管理界面三件套，约 42.1k Star、Apache 2.0。本文从三层架构、快速上手、平台能力到选型对比，完整拆解。
1、项目概述
Agno 定位为"代理平台的框架与运行时"：用 Agno SDK 构建代理，通过 AgentOS 运行时把代理跑成服务，再用 AgentOS UI 统一管理。仓库约 42.1k Star、5.9k Fork、6000+ 次提交，Apache 2.0 协议，Python 3.9+ 即可用。
三件套：
- Agno SDK：写代理的框架层，几十行代码定义一个代理
- AgentOS 运行时：把代理变成生产服务，API、存储、调度一体化
- AgentOS UI：管理界面，经 os.agno.com 接入本地或远端实例
- 模型无关：换提供商只改 model 字符串，OpenAI、Anthropic、Gemini、Groq 通用
2、三层架构：从代码到平台
多数代理框架只解决"写"，Agno 把"跑"与"管"也纳入同一体系。
三层的职责：
- 构建层（SDK）：Agent 类聚合模型、工具、指令与知识，纯 Python 定义
- 运行层（AgentOS）：FastAPI 服务化，热重载开发、SSE 与 WebSocket 接口
- 管理层（UI + 数据）：会话、记忆、知识、追踪全落自有数据库，界面可视管理
架构要点：
1. 数据主权是卖点：会话与记忆存在你自己的数据库，不锁在托管服务里
2. 开发体验顺滑：本地 python 文件调试，成熟后原对象挂进 AgentOS 即成服务
3. 与 MCP 生态互通：Context Providers 可从 Slack、Drive、wiki 及 MCP 取实时数据
4. Headroom 等压缩层已提供 agno 集成项，生态在互认
3、安装与第一个代理
官方文档的入门示例是一个"分类帽"代理：盘点文件夹并给出整理建议——二十行内用上模型、工具与指令三大件。
// 安装（需 Python 3.9+；要跑 AgentOS 服务另装 agno[os]）
uv pip install -U agno openai
// 设置模型密钥
export OPENAI_API_KEY=sk-***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"])],
instructions=(
"Walk the folder, figure out what's there, and propose a clean organization. "
"Decide the categories yourself. Return a tidy summary, a category breakdown, "
"and a folder tree."
),
markdown=True,
)
sorting_hat.print_response(f"Inventory and organize {folder}", stream=True)
// 运行：python sorting_hat.py代码要点：
1. Agent 用字符串指定模型："openai:gpt-5.5"，换提供商只改前缀
2. tools 挂 Workspace 工具，allowed 白名单限定只读权限
3. instructions 写自然语言职责，markdown=True 让输出带格式
4. print_response(stream=True) 流式打印，python 直接跑无需服务
4、AgentOS：把代理跑成服务
代理写好后，几行代码挂进 AgentOS，就得到带热重载的本地服务与完整管理界面。
// workbench.py：把代理装配成 AgentOS 服务
agent_os = AgentOS(agents=[workbench], tracing=True)
app = agent_os.get_app()
if __name__ == "__main__":
agent_os.serve(app="workbench:app", reload=True)
// 运行：python workbench.py
// 服务地址 http://localhost:7777，接口文档见 /docs
// 管理界面：os.agno.com 里 Add OS 接入本地实例服务化要点：
1. serve 拉起 uvicorn 并带热重载，改代码即生效
2. tracing=True 开启运行追踪，历史与审计在界面可查
3. 生产 API 提供 50 余个端点，覆盖 SSE 与 WebSocket
4. os.agno.com 的 Add OS 把本地服务纳管，团队共享一个控制台
5、平台级能力清单
真正让它称"平台"的，是这些开箱的生产能力。
能力清单：
- 生产 API：50+ 端点，SSE 与 WebSocket 双通道
- 自有存储：会话、记忆、知识、追踪全存自己的数据库
- 100+ 集成与工具包：GitHub、Slack、Postgres 等即挂即用
- Context Providers：从 Slack、Drive、wiki、MCP 持续供给实时上下文
- 人工审批：高风险动作可暂停运行，等人确认再继续
- 接口矩阵：Slack、Telegram、WhatsApp、Discord、AG-UI、A2A
- 定时与后台：cron 调度与后台任务内建
6、安全、可观测与部署
面向企业的三件治理能力与部署自由度。
治理能力：
- 安全：JWT 的 RBAC 权限，多用户、多租户隔离开箱即用
- 可观测：OpenTelemetry 追踪、运行历史、审计日志
- 遥测可关：每次代理运行发一条匿名遥测，设 AGNO_TELEMETRY=false 关闭，提示词与输出永不外发
部署要点：
1. 容器能跑的地方都能部署：Docker、Railway、AWS、GCP、Azure、Fly、Render、Modal、Helm
2. 官方还提供 agentos-railway 等模板仓库，交给编码代理即可起整套平台
3. 数据在自有数据库，迁移与备份随自己基础设施走
7、定位对比：与 LangGraph、Dify 怎么选
代理工具三层里，Agno 占的是"代码优先的平台"这一格。
三者对比：
- Agno：框架 + 运行时 + 管理界面全套，代码优先，平台能力（API、租户、审计）开箱
- LangGraph：低层编排框架，图模型控制力最强，但运行时与管理要自己搭
- Dify：可视化平台，业务友好，但深度定制受画布边界限制
选型建议：
1. 想用代码写代理、又要平台化运营（API、多租户、审计）→ Agno
2. 代理工作流复杂到需要图级控制、自建运维 → LangGraph
3. 面向业务团队、可视化优先 → Dify
4. 组合参考：Agno 做平台层，模型接入统一走 LiteLLM，上下文成本用 Headroom 压
8、总结
Agno 是"构建、运行、管理"三合一的代理平台（42.1k Star、Apache 2.0、Python 3.9+）：SDK 用几十行代码定义代理（模型字符串化、工具白名单、指令即配置），AgentOS 把代理变成带热重载的生产服务（50+ 端点、SSE/WebSocket），会话记忆知识全存自有数据库；平台侧自带 100+ 集成、Context Providers、人工审批、JWT 多租户、OpenTelemetry 与 cron 调度，容器所至皆可部署。
落地建议：想以代码方式快速拥有"代理即服务"的团队，从文档的二十行示例起步，本地跑通后挂进 AgentOS、接 os.agno.com 管理台，再按需开租户隔离与人工审批；模型接入可并 LiteLLM、上下文可叠 Headroom。对于要把代理当成产品长期运营的团队，Agno 是必要的平台级候选。
