Appearance
Q120 · AI Agent 中的 AgentOS 概念及核心功能是什么？（进阶）
小林在网页上申请跟进订单 A-17 的退款。客服 Agent 要查订单、读政策，再等主管批准是否加急。运行到一半，用户关掉网页；后台处理还在继续。几分钟后服务发布新版本，原先处理任务的实例退出；用户重新打开网页，请求又落到另一台实例。此时最重要的问题已经不是“模型会不会回答”，而是：任务是否被可靠接收、状态保存在哪里、换一台实例怎样接上、谁有权限查看或批准、失败后怎样查证？
本文专门讨论 Agno 产品中的 AgentOS，截至 2026 年 9 月 26 日以其当前官方文档为准。Agno 把 SDK 用于构建 Agent、Team、Workflow，把 AgentOS 用作提供 API 与运行管理的 FastAPI 运行时，把 Control Plane 用作连接和管理运行时的界面。这里“AgentOS”是产品名及其架构；不同项目也可能使用相同词语，不能由本文推断它们都有相同的队列、权限或重连能力。基础的“SDK → 运行时 → 控制台”分层可参照相邻题；本题聚焦上线后的运行保证与限制。Agno：What is AgentOS? · Agno：AgentOS Runtime
术语：运行时的几个身份与状态
| 术语 / 记号 | 含义 | A-17 示例 |
|---|---|---|
| Agent | 按任务使用模型与工具的执行单元 | 查 A-17、核规则并起草回复的客服 Agent |
| 运行时 / Runtime | 对外提供运行、会话、任务等 API，并管理执行所需基础设施的服务 | 部署在公司环境中的 AgentOS 服务 |
| 实例 / replica | 同一个服务的一个运行进程或容器；多实例可分担请求 | 实例 A 接受请求，实例 B 接到重连 |
| session_id（会话 ID） | 把相关交互归到同一会话的标识 | S-17 表示小林本次退款沟通 |
| run_id（运行 ID） | 一次 Agent、Team 或 Workflow 执行的标识 | R-17 表示这次跟进任务 |
| 后台任务 / background run | 客户端不用一直连着，服务端继续执行的 run | 小林关网页后 R-17 继续查资料 |
| 持久队列 / durable queue | 把已接受任务写入持久存储，让可用 worker 领取和处理 | R-17 先成为数据库里的待办任务 |
| worker | 真正领取、执行队列任务的工作者，通常运行在实例内 | 实例 A 的 worker 执行 R-17 |
| 流事件 / SSE | 服务器持续向网页发送进度片段；SSE 是服务器发送事件的网页传输方式 | “开始查询”“正在等审批”等进度 |
| event_index（事件序号） | 流中每条事件的顺序号，用于断线后请求后续事件 | 小林记住最后看到第 8 条 |
| RBAC / scope | 基于角色或权限范围限制能调用哪些接口 | 普通客服可查，主管才可批准 |
| 追踪 / trace | 记录一次 run 及其模型、工具、步骤的时间、结果和错误 | 查出 R-17 卡在订单工具还是审批步骤 |
| 评测 / eval | 用预先定义的案例和指标检查系统行为 | 检查“待审批”时是否错误说成“已加急” |
S-17、R-17、实例 A/B 和订单状态都是教学假设。请特别区分 session_id 是会话归属，run_id 是一次执行，队列任务是待执行工作，流事件是给客户端看的进度；它们有关联，却不是一个东西。Agno 官方背景执行文档也分开描述数据库中的会话/运行记录、队列表、跨实例事件流和取消信号。Agno：Background Execution
多实例上线，哪些数据必须共享
只在开发电脑上运行一个实例时，内存里保存的临时事件流与取消标记看起来可用。一旦有实例 A、B，网页首次请求落到 A、重连却落到 B，如果 B 只能看自己的进程内存，就看不到 A 发布的实时事件；用户在 B 点击取消，也不一定能通知执行中的 A。数据库中的 run 状态可供查询，不代表实时流和取消信号也天然跨进程。
Agno 当前文档给出的多实例组合是：数据库（生产示例使用 Postgres）存会话、运行记录及启用持久队列后的任务表；配置共享 Redis 或兼容服务作为跨实例的事件流与取消协调。官方的 QueueConfig(redis=...) 会同时给实例配置共享事件流和取消管理器，所以用户可从另一实例接流或发取消。Redis 在此承担协调，不能误称为所有业务事实的唯一存储；其事件有保留窗口，故障时实时流和取消会退化，不能说成永不丢失。Agno：Multi-Replica Deployments
同一组实例要连接一致的数据库和协调服务，部署相容的 Agent/Workflow 定义，并对队列超时、重试等关键配置保持一致。若滚动发布时某些 worker 不再包含 R-17 对应的组件，任务可能等待匹配的 worker；若不同实例对任务超时或租约宽限判断不一致，可能误判正在运行的任务已失联。Agno 的队列运行文档明确列出了跨实例配置一致性与部署匹配的注意事项。Agno：Operations and Monitoring
这里有一个部署边界：Agno AgentOS 运行在你部署的基础设施里，运行状态写到配置的数据库；Control Plane 是连接运行时的管理界面，官方说明它从浏览器直接连接运行时端点。控制台能展示会话、追踪、审批等信息，不代表它代替了运行时数据库、网络权限、模型服务或你的业务系统。生产环境仍要设计数据库备份、密钥管理、网络接入、流量限制和工具权限。Agno：What is AgentOS? · Agno：Control Plane
客户端断线、worker 重启是两类不同故障
客户端断线指网页关闭或网络中断，服务端进程还活着。Agno 支持将一次 run 以 background=true 提交；若同时使用 stream=true，服务端继续执行并缓冲带 event_index 的进度事件。小林最后看到第 8 条，重新连接时带上 R-17、S-17 和序号 8，通过对应的 resume 接口请求后续事件。缓冲事件有保留范围；若已不在实时缓冲中，能否从数据库重放还取决于事件是否配置为持久保存，不能承诺每一段文字永久可重播。若只关心最终结果，也可按 run_id 查询状态。Agno：Background Execution
worker 崩溃或实例退出则不同。普通 background=true 是把执行与客户端连接分离，进程没了，进程内任务也可能没了；仅有保存为 PENDING 的运行记录，不会自动让它重新执行。若要求“服务已接受的任务在实例重启后仍可被处理或明确失败”，需要配置 AgentOS 的 durable queue，也就是 QueueConfig(durable=True)，并使用受支持的持久队列存储。Agno 官方强调：数据库持久化本身不等于后台任务有崩溃恢复能力。Agno：AgentOS Runtime · Agno：Durable Queue
持久队列的保证也要说准确：可入队的任务在服务返回接受结果前写成数据库记录，可用 worker 后续领取。若 worker 已开始执行却突然失联，Agno 当前默认的 max_attempts=1 会把该次任务标记失败，默认不会偷偷重新执行；运维可以查看失败任务，再决定是否重排。把 max_attempts 调高才可能重跑整个 run，而整个 run 可能包含已执行过的发短信、提交审批等有副作用工具。框架的队列尝试计数与晚到写入防护，不能代替外部工具的幂等设计；业务接口应通过稳定的业务请求 ID 防止同一加急申请重复提交。官方也明确说明，提交时的 Idempotency-Key 可避免客户端重复排队，但不能使执行中的外部副作用自动幂等。Agno：Durable Queue
对小林的 R-17，正常路径可从头走一遍：
- 已登录的小林提交“跟进 A-17”，应用带上身份、S-17，得到一次 run R-17；如果它需要长时间处理，就用持久后台队列接收，保留队列任务与运行记录。
- 实例 A 的 worker 领取 R-17，按权限查订单和政策，进度通过流发送；网页暂时断开不影响后台任务继续。
- 小林重开网页，请求落到实例 B。B 从共享运行状态识别 R-17，并从共享事件流接收仍在执行的进度；若需重放旧事件，要看实际保留与持久事件设置。
- 系统读到“加急须主管确认”，把 run 放到等待审批的状态；小林只看到“待确认”，不会看到“已加急”。主管凭自己的权限处理审批后，流程才继续。
- 完成后用订单/审批系统的实际结果回复，记录最终 run 状态、工具调用与耗时。第二天回看 S-17 能找到这次运行，但需要以业务系统为准判断加急是否真正生效。
这里“后台任务接受”“流式续看”“人工暂停/继续”是可组合但不同的能力；某一项启用不自动打开另两项。Agno 文档也说明，暂停等待人工的任务不是自动完成，任务接受不保证无需人介入就到成功终态。Agno：Background Execution · Agno：Durable Queue
身份、接口权限与用户数据隔离分开配置
客服、主管和小林都可能访问 AgentOS，但权限不同。Agno 当前安全文档区分三件事：身份验证确认调用者是谁；JWT scope / RBAC 授权检查能否访问某个接口；user isolation限制同一接口里能看到哪些用户的会话、记忆、追踪等记录。只配 JWT 验证密钥会启用身份验证，但要执行 JWT scope 检查，还需启用 authorization=True；用户数据隔离是另外的设置。开发模式若没有配置中央认证，也不能当成可直接暴露在公网的生产安全配置。Agno：Security & Auth · Agno：Auth Middleware
把这三层放回 R-17：普通客服凭受限 scope 可以启动售后 Agent 和读自己负责的工单；主管角色才可执行审批接口；小林只能看到自己的 S-17/R-17。即使客服有“读取会话”的接口权限，也不应因这个 scope 就读到其他用户所有会话；须有用户隔离或应用侧业务授权。Agno 文档里的 user_isolation 按 JWT 的用户主体限制用户自有记录，但多租户企业、业务订单归属和工具内部权限仍应按你的系统设计，不能把一项框架开关说成全部安全问题已解决。Control Plane 的 Owner、Administrator、Member 是管理界面角色，不能直接等同于你的业务 API 里“主管可审批 A-17”的规则。Agno：Auth Middleware · Agno：Control Plane
下面的设置名便于读懂官方配置，不是让读者复制一份便可上线的完整代码：
| 设置或组件 | 负责什么 | 没设置好时会怎样 |
|---|---|---|
| AgentOS 的 db | 保存会话、运行与可用的队列数据 | 重启后缺少持续状态；持久队列无法正确建立 |
| QueueConfig(durable=True) | 将被接受的后台 run 写入持久任务表 | 进程退出可能留下状态记录却没有任务继续执行 |
| QueueConfig(redis=共享地址) | 跨实例分发流事件和取消信号 | 重连落到另一实例时看不到实时尾流，取消可能不到执行处 |
| JWT 验证配置 | 确认调用者身份 | 服务无法可靠区分小林、客服和主管 |
| authorization=True | 对 JWT 的 scope 做接口授权 | 有身份的请求可能仍缺少所需的接口权限检查 |
| user_isolation=True | 对用户自有的会话等资源按身份隔离 | 用户可能通过已授权接口读到别人的资源 |
| tracing=True | 采集并存储执行追踪 | 排错时缺少模型和工具步骤细节；同时须管理追踪数据访问与保留 |
这些名称来自官方当前接口；启用与否、是否还有外围网关及具体密钥由部署环境决定。尤其是 idempotency（幂等）要落到实际会产生副作用的订单、短信或审批接口，不能只看队列参数。Agno 的持久队列文档明确说明多个同会话任务不保证严格先后执行；若 R-18 必须等 R-17 审批完成，应用需额外串行或依赖控制。Agno：Durable Queue
追踪、评测和故障定位怎样闭环
假设用户说“进度一直停在核规则”。先按 R-17 找 trace（追踪记录）：查看是模型调用慢、订单工具超时，还是 Workflow 等待主管。Agno 文档说明 opt-in tracing 可记录 Agent/Team/Workflow run、模型调用、工具调用、成员协作和步骤耗时；它存到配置的数据库，访问控制与保留期限也要单独设计。若没有 tracing，仍可看运行状态和服务日志，但不能假设能重建每一步内部过程。Agno：Tracing
再看队列：若待办数量增长、最老任务越来越久没有 worker 领取，检查实例容量、数据库连接与部署匹配；失败列表可供运维决定重排。流式进度卡住而 run 最终已完成，可能是多实例缺少共享事件流，不该简单重跑任务。Agno 官方的队列监控文档列出 queue stats、失败任务和重排入口，重排属于运维动作，需要权限与副作用判断。Agno：Operations and Monitoring
评测则回答“系统做得对不对”，不能用 trace 数量代替。为 A-17 准备固定案例：待审批、主管拒绝、订单不存在、订单工具超时、浏览器断线、实例退出后重排。逐例检查用户可见答复、审批状态、重复提交次数、工具参数与权限结果。Agno 的评测能力支持准确性、工具调用可靠性、模型评审、运行性能等维度，也能将结果存入 AgentOS 查看；模型评审分数不能代替业务系统事实和人工审批。Agno：Agent Evaluation
一个需要格外谨慎的故障例子是：R-17 已经把加急请求提交给外部系统，worker 在收到响应前崩溃。队列里看见的可能是“失败”，但外部系统可能已接收。正确排查顺序是先用业务请求 ID 查外部系统，再决定是否重排；若直接提高 max_attempts 并让整个 run 重试，可能重复提交。另一个例子是 Redis 暂时不可用：数据库仍可能保存最终 run 状态，但跨实例的实时接流和取消受影响；此时网页可降级为轮询最终状态，不能向用户显示“取消已生效”却没有确认。上述行为应在上线前做故障注入测试，而非等真实用户碰到才判断。
面试中可以这样回答
我会把 Agno AgentOS 理解为把 SDK 里定义的 Agent、Team、Workflow 服务化的运行时，上面再有管理界面。进阶重点是运行保证：会话和 run 状态放在配置的数据库里；长任务用 background 执行，但要让已接受任务跨 worker 重启，就需要持久队列；多实例还要共享流事件和取消协调，才能让用户断线后在另一实例续看。身份验证、JWT scope 授权和用户数据隔离要分别配置，Control Plane 的管理角色也不等于业务审批权限。追踪用于定位哪一步慢或错，评测用于检查工具轨迹和答案是否符合业务规则。比如 A-17 退款待主管审批，浏览器断线不应终止后台任务，但 worker 崩溃后的默认处理可能是显式失败，不能宣称自动无损恢复；重试前还要核对加急提交是否已发生，防止副作用重复。
如果被问“有数据库是否就能恢复任务”，答：数据库可以保留会话与 run 状态；Agno 官方明确说进程内后台任务的崩溃恢复还要启用 durable queue。若问“有 Redis 是否就不用数据库”，答：当前官方组合里，Redis 主要承担跨实例实时事件和取消协调，队列接受与会话状态仍需可靠存储。若问“AgentOS 是否天然是完整多租户平台”，答：它提供身份、scope 和用户隔离机制，但部署者仍要配置这些机制，并在业务工具里验证订单归属、租户和审批权限。
资料来源
- Agno：What is AgentOS?：产品分层、运行时能力与数据部署边界。
- Agno：AgentOS Runtime：运行时组成，以及持久数据库与 durable queue 的区别。
- Agno：Background Execution：后台运行、状态存储与跨实例协调总览。
- Agno：Durable Queue：持久接受、默认失败、重试、幂等和会话并发边界。
- Agno：Multi-Replica Deployments：共享事件流与取消信号的配置和失效模式。
- Agno：Background Execution and Resumable Streaming：SSE 的 event_index、断线续流与重放条件。
- Agno：Security & Auth、Agno：Auth Middleware：身份、scope 与用户隔离的区别。
- Agno：Tracing、Agno：Agent Evaluation：追踪范围与评测类型。
- Agno：Operations and Monitoring：队列统计、失败任务、重排与多实例运维边界。