Agno：把 Agent 当作持久化服务运行的自驾式 Agent 平台｜部署与使用全指南
项目仓库： https://github.com/agno-agi/agno
开源协议：Apache 2.0 · 交付形态：Python SDK + AgentOS（API / MCP / Interfaces）· 存储：PostgreSQL · 官方文档：docs.agno.com · 控制台：os.agno.com
官方定位（README 原文）：Agno is a self-driving agent platform. Build agents for your company, product, or customers. Run them as durable services on AgentOS. Put them to work automating company operations.
1 项目简介
Agno 把 Agent 开发分成三层：Build（用 Agno、Claude Agent、Codex SDK 构建 Agent，组合成团队与工作流）、Run（在 AgentOS 上以持久化服务运行，内置 API 与 MCP）、Automate（Company OS 把工作组织成产品、项目、任务与例行例程）。Agent 可以通过 REST API、MCP server（Claude / ChatGPT）、Slack 等聊天界面三种方式对外提供。
1.1 核心信息一览
| 项目项 | 内容 |
|---|---|
| 项目名称 | Agno（仓库 agno-agi/agno，对应平台 AgentOS） |
| 仓库地址 | github.com/agno-agi/agno |
| 项目定位 | 自驾式 Agent 平台，把 Agent 当作持久化服务运行 |
| 开源协议 | Apache 2.0 |
| 主要语言 | Python（SDK）+ TypeScript（AgentOS UI） |
| 存储 | PostgreSQL（对话、记忆、平台活动） |
| 对外接口 | REST API、MCP server、Agno Interfaces（Slack 等） |
| 部署形态 | 官方一键模板：Docker、Railway、AWS、GCP、Azure、Fly.io、Render、Modal、Helm |
| 官方文档 | docs.agno.com |
| 控制台 | os.agno.com |
| 遥测 | 默认每个 Agent 发一次事件；AGNO_TELEMETRY=false
关闭 |
1.2 适用场景
- 把 Agent 当作公司内部服务长期运行，需要鉴权、RBAC、断点续跑、人工审批与调度。
- 把现有 Agent 同时暴露给产品 API、Claude / ChatGPT（MCP）、Slack 等多个入口。
- 需要用 Claude / Codex 在沙箱里自动改代码、跑回归、提 PR 的“coding agent”工作流。
- 想在自己的云里保留数据控制权，同时用 AgentOS UI 审查对话、追踪 trace、管理知识库。
1.3 能力边界（官方口径）
- README 明确：Agno 提供“编排与服务层”，模型本身不附带，需要自行准备 OpenAI / Anthropic / Gemini 等模型凭据。
- 平台化能力（Company OS、调度、HITL、可观测性）由 AgentOS 承载；裸 SDK 只覆盖 Agent 与工作流定义。
- 遥测默认开启，但 README 承诺“Prompts, messages, and outputs are never sent”，可通过环境变量关闭。
2 功能特性
2.1 Agent 与团队
- 用 Agno、Claude Agent 或 Codex SDK 构建 Agent；Agent 可以使用工具、委派任务、互相协作。
- 把多个 Agent 组合成团队（teams），按角色分工完成复杂任务。
2.2 工作流（Workflows）
- 显式控制执行顺序：路由（routing）、条件分支（conditions）、循环（loops）、并行步骤（parallel）。
- 与自由推理的 Agent 互补：工作流适合需要确定性路径的业务流程。
2.3 记忆与知识
- Memory：跨会话记住用户，支持长短期记忆。
- Knowledge：从自有数据检索答案，构建 RAG 类应用。
2.4 工具与集成
- 把 Agent 接到 API、数据库、MCP servers；内置常用工具与集成。
2.5 持久化执行与 HITL
- Durable execution：后台任务持久化，重启后可追踪状态。
- Human approval：敏感动作先审批再继续，避免 Agent 自动执行高风险操作。
2.6 可观测性、调度与安全
- Tracing：追踪每次运行、工具调用、失败原因。
- Scheduling：按 cron 或例行计划跑 Agent、团队、工作流。
- Security：鉴权、角色权限、按用户数据隔离。
2.7 Coding Agents 与 Company OS
- 内置 Claude / Codex harness，在沙箱里实现并测试代码改动。
- Company OS 把工作组织成产品、项目、任务与例行例程；人定方向与复核，Agent 负责执行。
3 官方界面预览
README 未在 Markdown 中嵌入产品截图，仅以品牌 Logo 作为顶部视觉；完整 UI 请访问官方控制台 os.agno.com 在线体验。
4 官方跳转链接汇总
| 类别 | 链接 | 说明 |
|---|---|---|
| 仓库主页 | github.com/agno-agi/agno | 源码、README、贡献指南 |
| 官方文档 | docs.agno.com | Agent、Teams、Workflows、Memory、Knowledge、AgentOS 全套文档 |
| AgentOS 控制台 | os.agno.com | 对话审查、trace、知识库、活动管理 |
| Docker 模板 | agentos-docker | 本地 / 服务器 Docker 一键起 |
| Railway 模板 | agentos-railway | Railway 一键部署 |
| AWS 模板 | agentos-aws | AWS 部署模板 |
| GCP 模板 | agentos-gcp | GCP 部署模板 |
| Azure 模板 | agentos-azure | Azure 部署模板 |
| Fly.io 模板 | agentos-fly | Fly.io 部署模板 |
| Render 模板 | agentos-render | Render 部署模板 |
| Modal 模板 | agentos-modal | Modal 部署模板 |
| Helm 模板 | agentos-helm | Kubernetes Helm Chart |
| X / 推特 | @AgnoAgi | 发布与演示 |
| Newsletter | The Agno Loop | 官方邮件通讯 |
5 前置要求与服务器配置
5.1 软件前提
- Python 3.11+：用于本地跑 Agno SDK 与 setup skill。
- Docker 与 Docker Compose：官方推荐的本地 / 服务器运行方式。
- Git：克隆 setup skill 仓库。
- 一个支持 LLM 的 API Key：OpenAI、Anthropic、Gemini 等，或本机 Ollama。
- PostgreSQL：AgentOS 用于存储对话、记忆与活动；Docker 模板会自带容器。
- 编码助手（可选）：README 推荐把 Agno 接入 Claude
Code、Codex 等 coding agent，由它按
.agents/skills/setup-platform/SKILL.md自动起平台。
5.2 服务器建议
| 项目 | 最低 / 建议 |
|---|---|
| 操作系统 | Linux（Ubuntu 22.04+）/ macOS |
| CPU | 2 核起步，4 核建议 |
| 内存 | 4 GB 起步，8 GB 建议（含 PostgreSQL） |
| 磁盘 | 20 GB 可用，含镜像与数据 |
| 网络 | 能访问模型厂商 API；如需公网访问，准备域名与 TLS 证书 |
5.3 端口说明
| 端口 | 服务 | 默认绑定 | 用途 |
|---|---|---|---|
| 由模板决定 | AgentOS API | 容器内 | 业务系统调用 |
| 由模板决定 | MCP server | 容器内 | Claude / ChatGPT 接入 |
| 5432 | PostgreSQL | 仅容器网络 | AgentOS 内部存储 |
6 方式一：Docker / Compose 部署（推荐）
README 推荐用官方 setup skill 一键起平台，底层即 Docker 模板。
6.1 用 coding agent 引导（官方推荐）
把下面提示词交给你的 coding agent（Claude Code / Codex 等）：
Help me set up my agent platform and build my first agent.
Clone https://github.com/agno-agi/agentos-railway into a folder called agent-platform, cd into it, and follow .agents/skills/setup-platform/SKILL.md.setup skill 会在本地启动：
- API server 与 MCP server；
- PostgreSQL（对话、记忆、平台活动）；
- OS Manager（帮助你构建与管理平台）；
- Claude / Codex engineers；
- 构建、评估、改进 Agent 的 skills；
- Company 工作区（含每日例行维护）。
6.2 直接用 Docker 模板
# 以 Docker 模板为例
git clone https://github.com/agno-agi/agentos-docker.git
cd agentos-docker
# 按仓库 README 复制 .env 并填入模型 Key
cp .env.example .env
# 编辑 .env 填入 OPENAI_API_KEY / ANTHROPIC_API_KEY 等
# 启动
docker compose up -d其它云的一键模板（Railway / AWS / GCP / Azure / Fly / Render / Modal / Helm）见第 4 节链接，按各自 README 操作。
7 方式二：源码 / 本地运行
7.1 克隆 SDK 仓库
git clone https://github.com/agno-agi/agno.git
cd agno7.2 安装 Python SDK
# 推荐用 uv
uv pip install agno
# 或
pip install agno7.3 连接到 AgentOS
本地跑起平台后，把它连接到 os.agno.com：
- 用代码构建 Agent；
- 用 no-code UI 配置；
- 或直接与 OS Manager 对话。
7.4 用 /improve
持续改进
# 在 coding agent 中触发
/improve保留有用改动与回归测试；准备好后可配置沙箱里的定时改进任务，自动提 PR 等你 review。
8 配置项说明
8.1 模型凭据
Agno 本身不附带模型；在 .env 或运行环境中配置：
| 变量 | 作用 |
|---|---|
OPENAI_API_KEY |
OpenAI 模型 |
ANTHROPIC_API_KEY |
Anthropic 模型 |
GEMINI_API_KEY |
Google Gemini |
| 其它 | 按所接模型厂商文档配置 |
8.2 遥测
| 变量 | 默认 | 说明 |
|---|---|---|
AGNO_TELEMETRY |
开启 | 每个 Agent 发一次事件；设为 false 关闭。README
承诺不发送 prompts / messages / outputs。 |
export AGNO_TELEMETRY=false8.3 数据存储
- PostgreSQL 由 AgentOS 容器提供；连接串由各模板的
.env决定，不要把库暴露到公网。 - 对话、记忆、知识库、调度记录均落库，备份策略自定。
9 常用运维命令
# ---- Docker 模板 ----
docker compose up -d # 启动
docker compose down # 停止
docker compose logs -f # 跟踪日志
docker compose pull && docker compose up -d # 升级镜像
# ---- SDK 开发 ----
uv pip install agno # 安装 SDK
python -c "import agno; print(agno.__version__)" # 查看版本
# ---- 遥测 ----
export AGNO_TELEMETRY=false # 关闭遥测
# ---- 平台入口 ----
# API server / MCP server：按模板 README 暴露的端口访问
# 控制台：https://os.agno.com10 常见故障排查
10.1 setup skill 跑不起来
- 确认本机有 Docker 与 Docker Compose。
- 确认 coding agent 能读到
.agents/skills/setup-platform/SKILL.md。 - 模型 API Key 已设置；网络能访问对应模型厂商。
10.2 模型调用失败
- 检查环境变量名与值是否正确；PostgreSQL 容器是否健康。
- 用
docker compose logs查看 API server 报错；常见是额度耗尽或网络拦截。
10.3 AgentOS UI 连不上本地平台
- 确认本地平台已启动并暴露对应端口；
- 浏览器插件 / 代理不要拦截到
os.agno.com的回调； - 重启浏览器或更换网络后重试。
10.4 遥测顾虑
- 按 README 设
AGNO_TELEMETRY=false即可关闭；不需要改代码。
11 风险与合规说明
以下条款整理自官方 README 与 Apache 2.0 许可证；如与官方原文不一致，以仓库
LICENSE、README 与 docs.agno.com 为准。
11.1 开源协议与商业边界
Agno 开源代码采用 Apache 2.0；AgentOS 平台能力（Company OS、调度、HITL、可观测性 UI）的具体使用条款以 os.agno.com 与官方文档最新说明为准。
11.2 模型与 API 责任
- 平台不附带模型；OpenAI、Anthropic、Gemini 等模型与服务归各自厂商，受其条款、隐私政策与计费约束。
- 业务数据、对话、代码会按所选模型发送；敏感仓库优先使用本地模型与离线配置。
11.3 自动化与工具权限
- Agent / Coding Agent 可以读写文件、执行命令、提 PR；在共享服务器上应限制工作目录、保留人工审批环节。
- 沙箱、HITL、RBAC 等能力由 AgentOS 提供，不等于对系统安全边界的保证。
11.4 免责
使用者在法律允许的最大范围内，自行承担因部署、修改、运行本项目产生的代码质量、数据泄露、服务中断与业务损失风险。如认为仓库内特定文件侵犯合法权益，请通过 GitHub Issues 提交说明，不要在公开 Issue 中提交账号凭据或敏感代码。