AgentOS 是 Agno 框架的生产级运行时Runtime是一个基于 FastAPI 构建的、用于部署、运行和管理 AI 智能体Agents、团队Teams和工作流Workflows的完整平台。如果说Agent是思考与行动的“大脑”Team是分工协作的“项目组”那么 AgentOS 就是承载这一切的“身体”和“生命维持系统”让它们能在真实世界稳定、安全、大规模地运作。在 Agno 三层架构中的位置理解 AgentOS需要先了解 Agno 的整体架构。Agno 被设计为一个完整的“三层架构”第一层框架层 (Framework)这是最基础的 SDK 层。开发者使用Agent、Team、Workflow等组件来构建智能体的核心逻辑并配备记忆Memory、知识库Knowledge、护栏Guardrails等能力。它解决的核心问题是“如何构建一个智能体”。第二层运行时层 (Runtime - AgentOS)这就是 AgentOS。它是一个高性能的 FastAPI 服务负责执行智能体、管理会话、处理存储等核心基础设施。它解决的核心问题是“如何让智能体快速、可靠地运行”。第三层生产层 (Production Layer)这是 Agno v2.5 后补齐的最后一环提供了治理、审计、合规、人机回环HITL、审批流等生产环境必需的能力。它解决的核心问题是“如何将智能体作为可信赖的业务能力进行部署和治理”。AgentOS 是连接本地开发与生产部署的关键桥梁AgentOS 提供了大量开箱即用的生产级功能生产级 API提供 50 多个即用型端点支持 REST API 和 SSEServer-Sent Events兼容的流式传输。会话管理支持跨重启、多副本的长会话时长可从几分钟到数周。数据所有权所有数据会话、记忆、知识、追踪完全存储在您自己的数据库中没有第三方数据中继。请求隔离确保不同用户、智能体或会话之间的状态完全隔离无数据泄露风险。安全与治理内置基于 JWT 的 RBAC基于角色的访问控制。可观测性所有运行和操作日志都存储在您的数据库中方便审计。多框架支持不仅能运行原生 Agno Agent还能运行其他流行框架如 Claude Agent SDK、LangGraph、DSPy构建的智能体。控制平面 (Control Plane)提供一个 Web UI用于可视化管理、监控和调试你的系统工作原理AgentOS 的设计是“私有化”的所有组件都运行在您自己的基础设施中运行时 (Runtime)一个 FastAPI 服务以容器形式运行在您的云环境中负责执行智能体。控制平面 (Control Plane)一个 Web UI从您的浏览器直接连接到运行时无需经过代理快速上手如何运行 AgentOS使用 AgentOS 部署智能体非常简单通常只需三步定义智能体像平常一样创建你的Agent、Team或Workflow。创建 AgentOS 实例将定义好的组件传递给AgentOS。获取 FastAPI 应用调用get_app()方法得到一个标准的 FastAPIapp对象即可使用uvicorn等工具启动服务from agno.agent import Agent from agno.db.sqlite import SqliteDb from agno.os import AgentOS from agno.models.deepseek import DeepSeek from dotenv import load_dotenv load_dotenv() deepseek DeepSeek(iddeepseek-chat) # 1. 定义你的 Agent hello_agent Agent( idhello-agent, name智能助手, modeldeepseek, dbSqliteDb(db_fileagno.db), instructions[你是一个乐于助人的助手可以回答问题并协助完成任务。] ) def create_agent_os(flask_app): agent_os AgentOS( agents[hello_agent], base_app flask_app, dbSqliteDb(db_fileagno.db), ) return agent_os.get_app()from fastapi import FastAPI from fastapi.concurrency import asynccontextmanager from agentos_init.agentos_simple import create_agent_os from api import common_api asynccontextmanager async def lifespan(app: FastAPI): print(启动中...) yield print(关闭中...) flask_app FastAPI( titleAgno Assist, lifespanlifespan ) #如果有其它接口 #flask_app.include_router(common_api.common_api.router, prefix) app create_agent_os(flask_app)启动后http://127.0.0.1:8888/docs#/即可看到自动生成的 50 多个 OpenAPI 端点鉴权默认情况下 AgentOS 确实没有开启鉴权。不过Agno 提供了两种官方认证方式来保护 AgentOS确保只有授权用户才能访问。方案一基础认证 (Basic Authentication) - 适合开发测试这是最简单的认证方式通过一个共享密钥 (Shared Secret) 来验证请求。配置步骤设置环境变量在启动 AgentOS 的服务中设置环境变量OS_SECURITY_KEY。bashexport OS_SECURITY_KEYyour-strong-secret-key启动 AgentOS你的 AgentOS 现在会要求所有请求除了/health等少数路由都附带这个密钥。发起认证请求在调用 AgentOS API 时需要在请求头中携带这个密钥curl -H Authorization: Bearer your-strong-secret-key http://localhost:8888/agents注意官方文档指出这种方式已弃用 (Deprecated)主要用于本地开发或简单原型。对于生产环境官方强烈推荐使用下一种 RBAC (基于角色的访问控制) 方案方案二RBAC (基于角色的访问控制) - 推荐用于生产这是 AgentOS 官方推荐的认证方式基于 JWT (JSON Web Token) 提供细粒度的权限控制。它允许你为不同的调用者如用户、服务分配不同的角色和权限。生成密钥对 (以 RS256 为例)你可以使用 OpenSSL 命令行工具来生成 RSA 密钥对。生成私钥 (Private Key):bashopenssl genrsa -out private.pem 2048从私钥导出公钥 (Public Key):bashopenssl rsa -in private.pem -pubout -out public.pem现在private.pem是你的私钥务必妥善保管切勿泄露public.pem是你的公钥。在 AgentOS 中配置 RBAC需要在初始化AgentOS时通过代码来启用并配置 RBAC。启用授权将authorization参数设置为True。配置验证信息通过authorization_config参数传入一个AuthorizationConfig实例。verification_keys: 填入你的公钥内容对于 RS256或共享密钥对于 HS256。algorithm: 指定你使用的算法例如RS256。参考代码import os from agno.agent import Agent from agno.db.sqlite import SqliteDb from agno.os import AgentOS from agno.models.deepseek import DeepSeek from dotenv import load_dotenv load_dotenv() from agno.os.config import AuthorizationConfig deepseek DeepSeek(iddeepseek-chat) # 1. 定义你的 Agent hello_agent Agent( idhello-agent, name智能助手, modeldeepseek, dbSqliteDb(db_fileagno.db), instructions[你是一个乐于助人的助手可以回答问题并协助完成任务。] ) # 获取当前脚本所在的目录绝对路径 current_dir os.path.dirname(os.path.abspath(__file__)) # 拼接出 public.pem 的绝对路径 pem_path os.path.join(current_dir, public.pem) with open(pem_path, r) as f: public_key f.read() def create_agent_os(flask_app): agent_os AgentOS( agents[hello_agent], base_app flask_app, dbSqliteDb(db_fileagno.db), authorizationTrue, authorization_configAuthorizationConfig( verification_keys[public_key], algorithmRS256, # verify_audienceFalse, # 默认为 False保持即可 ), ) return agent_os.get_app()生成用于测试的 JWT 令牌在客户端如你的前端应用或测试脚本调用 AgentOS API 之前需要先获取一个有效的 JWT 令牌。可以使用之前生成的私钥 (private.pem) 来签发 JWT。这里是一个使用 PyJWT 库的 Python 示例:import jwt from datetime import datetime, timedelta, timezone import json # 加载你的私钥 with open(private.pem, r) as f: private_key f.read() # 定义令牌的有效载荷 (Payload) payload { sub: user-123, # 用户唯一标识[reference:16] aud: my-agent-os, # 必须与 AgentOS 的 id 完全一致[reference:17] scopes: [agents:read, agents:my-agent:run], # 授权范围[reference:18][reference:19] exp: datetime.now(timezone.utc) timedelta(hours1), # 1小时后过期[reference:20] iat: datetime.now(timezone.utc), # 签发时间[reference:21] } # 使用 RS256 算法和私钥签发令牌 token jwt.encode(payload, private_key, algorithmRS256) print(token)常用 Scope 参考你可以在 JWT 的scopes声明中添加以下权限来控制访问。Scope描述agent_os:admin超级管理员拥有所有权限agents:read列出和查看所有 Agentagents:run运行任何Agentagents:agent-id:run仅运行指定 ID 的 Agentteams:run运行任何 Teamworkflows:run运行任何 Workflowsessions:read查看所有会话memories:write创建和更新记忆
