第 41 章 · Agno AgentOS 与运行时

demo 能跑，不等于业务能用

还是那个跨境卖家。经过前几章，他的 Research Agent 已经相当能干：会查资料、记得住偏好、能拆成团队协作。可这一切都跑在他电脑上的一个 agent.py 里——他一关电脑，Agent 就没了。

而他真正想要的是：市场部同事能从内部网页里点一下就生成报告；运营想在 Slack 里 @ 一下就问竞品动态；他自己想设一个“每天早上 8 点自动出一份竞品监控”的定时任务；出了问题时，技术同事能查到到底是哪一步、哪个模型、哪个工具出了错，花了多少钱。这些需求，一个本地脚本一个都满足不了。

demo 证明的是“模型能回答”，业务需要的是“系统能运营”。 这中间隔着一整层——如何让 Agent 从一个跑完即停的脚本，变成一个能被远程触达、能观测、能恢复、能取消的服务。这正是第 22、23、24 章处理的问题，Agno 用 AgentOS / Runtime 这一层来承接。这一章讲的就是这道从脚本到服务的坎怎么迈过去。

概念与主书映射：运行时这一层在解决什么

Agno 的 AgentOS 取向，是把 Agent 应用从“一段脚本”推进到“一个服务化平台”。它对应主书的这几章：

第 23 章：运行时架构设计——Agent 作为一个有状态服务，进程、会话、并发怎么组织。
第 24 章：RPC 与远程驱动——客户端如何远程驱动一个有状态的会话，而不是调一个无状态函数。
第 25 章：可观测性——会话、工具调用、成本、失败点如何被记录和追踪。
第 33 章：后台 Agent——长时、异步、定时任务如何跑得住、控得住。

把这几件事合起来，就是“运行时”这一层的职责：不再关心模型答得好不好，而是关心这个系统能不能被稳定地运营。 下面按“形态演进 → 会话 → 接口 → 观测 → 入口 → 后台”的顺序展开。

运行形态的演进：很多 demo 卡在第二阶段

从脚本到平台，Agent 的运行形态大致经历五个阶段，每个阶段要回答的核心问题都不同：

阶段	形态	主要问题
本地脚本	`python agent.py`	能不能跑通
CLI / Playground	交互调试	行为是否符合预期
API 服务	前端或系统调用	鉴权、会话、并发、错误处理
AgentOS	平台化运行	观测、权限、租户、任务、接口
后台 Agent	异步 / 定时任务	成本、恢复、取消、重试

很多项目卡在第二阶段就以为大功告成，因为 Playground 里跑得很漂亮。但那只证明了“模型能回答”，离“系统能运营”还差三个阶段——鉴权、观测、租户、任务控制这些真正决定能不能上线的东西，一个都还没碰。这一章要帮你把视线从第二阶段挪到第四、第五阶段。

会话是服务化的核心，而不是 run(prompt)

一旦 Agent 被远程调用，最先暴露的问题就是状态。本地脚本可以靠进程内的变量把状态凑合过去，服务化不行——你必须把这些标识显式管理起来：

user_id：谁在使用。
session_id：哪一次会话（决定历史怎么续接，见第 39 章）。
tenant_id：属于哪个客户或组织（多租户隔离的基础）。
run_id / task_id：哪一次具体执行。
trace_id：用来把日志、工具调用、成本串成一条可追的链路。

第 24 章反复强调的一点，在这里是命门：RPC 远程驱动时，客户端不是在调用一个无状态函数，而是在驱动一个有状态的会话。 这意味着服务端接口的设计重心，从“接收 prompt、返回 answer”转向“维护会话生命周期”。Agno 接 AgentOS 时，也应该按这个思路组织接口——会话是一等公民，run(prompt) 只是会话生命周期里的一个动作。

# 服务化调用的思路：始终携带身份与会话标识，而不是无状态地丢一句 prompt
# （以下为示意，展示需要显式传递的关键标识）
response = research_agent.run(
    "生成本周德国玩具竞品监控简报",
    user_id="seller_001",        # 谁
    session_id="weekly_de_toys", # 哪次会话（决定历史续接与状态恢复）
    # tenant_id / run_id 等由服务层在更外层统一注入和记录
)
# 服务层还要能对这次 run 做：查状态、取 trace、必要时取消

接口层：别只暴露一个 run()

顺着“会话是核心”往下想，一个成熟的 Agent 服务对外暴露的接口，绝不止一个 run。至少需要这些接口语义：

接口语义	作用
创建会话	初始化用户、租户、模型、工具权限
发送消息	让会话继续运行下一轮
查询状态	看当前是运行中、暂停、失败还是完成
人工确认	批准或拒绝敏感工具调用（第 37 章的 `is_paused`/`continue_run`）
获取 trace	查看模型调用、工具调用、成本和错误
取消任务	终止长任务或后台任务

如果只暴露一个 run(prompt)，前端和运维会很快失控：断线了无法恢复，敏感操作无法人审，跑飞的任务无法取消，出了错无法定位。这些能力不是“锦上添花”，而是把 Agent 当服务运营的地基。注意其中“人工确认”一项，正是第 37 章 human-in-the-loop 在服务层的落点——response.is_paused 需要一个接口把它暴露出去、等人点确认后再 continue_run()。

观测：把它当基础设施，不是演示面板

Agno 的 Monitoring / tracing 能力，应该被当作生产基础设施来对待，而不是给老板看的漂亮面板。这对应第 25 章的可观测性。最小可观测字段，建议至少覆盖这些：

session_id      # 哪次会话
user_id         # 谁
tenant_id       # 哪个租户
run_id          # 哪次执行
agent_name      # 哪个 Agent / Team 成员
model           # 用了哪个模型
tool_name       # 调了哪个工具
input_tokens    # 输入 token
output_tokens   # 输出 token
cost            # 这次调用花了多少钱
duration_ms     # 耗时
status          # 成功 / 失败 / 暂停
error_type      # 失败时的错误类型

这些字段不是为了好看，它们支撑四件真正要命的事：

查失败：哪一步错了？是模型、工具、RAG 检索，还是策略拦截？没有 error_type 和 tool_name，你只能靠猜。
算成本：哪个用户、哪个租户、哪个任务最烧钱？没有 cost 和 tenant_id，成本就是一笔糊涂账。这也是第 24 章预算控制的数据来源。
做评测：把真实的失败会话，变成评测集里的回归样本（见附录 D），让同样的错不再犯第二次。
做治理：识别越权调用、危险工具、异常流量——第 26 章之后的安全治理，全靠这些字段作为原料。

一句话：观测字段是运行时的一切治理动作的原材料。 缺了它们，恢复、算账、评测、治理都无从谈起。

应用入口：Playground、AG-UI、Slack、API、A2A

Agent 服务化后，用户和系统总要有个地方触达它。Agno 提供或接入多种入口，但要分清它们解决的是不同层次的问题：

入口	适合用途
Playground	开发调试、演示、内部试用
AG-UI	快速接一个前端聊天界面
Slack / Chat 接口	把 Agent 放进团队日常工作流
API	被业务系统程序化调用
A2A	与其他 Agent 系统协作

最容易犯的认知错误，是把入口和能力混为一谈。入口只是“用户或系统如何触达 Agent”，它换来换去都改变不了真正的生产能力所在——那些能力在会话管理、权限控制、工具治理、观测和回滚里。换句话说：接一个 Slack 入口很快，但它不会自动帮你解决鉴权、成本、失败恢复。入口是门面，治理是内功，别把门面当内功。

后台 Agent：把智能变成可控的成本，而不是黑洞

当 Research Agent 要跑“每天早上 8 点自动生成竞品监控报告”这类长时任务时，它就从交互式 Agent 变成了后台 Agent（对应第 33 章）。后台形态有一整套额外的东西要设计：

任务队列与并发限制——别让几十个任务同时把 API 打爆。
超时、取消、重试——任务卡住了要能掐掉，失败了要能重来。
中间状态持久化——跑到一半崩了，要能从断点恢复（这依赖第 39 章的 State/Storage）。
预算上限——单次任务烧到某个额度就停（第 24 章）。
失败告警与结果通知——出错要有人知道，完成要通知到人。

这些控制少一样，后台 Agent 就可能把“智能”变成一个看不见的成本黑洞：没人盯着，它可能在后台反复重试、无限循环、悄悄烧掉一大笔 token 费用，等发现时账单已经很难看。所以后台 Agent 的设计重心，从来不是“让它更聪明”，而是“让它可控”。

深入一层：AgentOS 帮你到哪，剩下靠你，以及和 pi 的分野

AgentOS 帮你做了什么，没帮你做什么？ 它把“启动服务、管理会话、记录 trace、提供入口”这些基础设施做成了现成的一层，省掉你自己搭 Web 框架、拼观测系统的力气。但它不替你做业务判断：哪个租户能用哪些工具、哪个操作需要人审、单任务预算是多少、失败了通知谁——这些是你的策略，框架只提供承载它们的位置。把 AgentOS 理解成“一个装好了地基和水电的毛坯房”，治理规则是你自己要砌的墙。

服务化后最反直觉的一点：会话是有状态的，接口设计要顺着这个来。 本地脚本里，一次调用就是一次函数调用，无状态、跑完即忘。服务化之后，同一个 session_id 背后是一段持续演进的对话和任务状态，客户端每次调用都是在“推进”这个状态，而不是“重新开始”。第 24 章把这叫“远程驱动一个有状态会话”——如果你的接口还按无状态函数来设计（每次只收 prompt、不管 session），断线恢复、人审续跑、任务取消这些能力就全都无处安放。

这和 pi 的做法什么关系？ pi 作为 harness，本身就更贴近“运行时”这一层——它天然按“驱动一个有状态会话”来设计（回顾第 22、23 章的 RPC 与会话驱动），观测、恢复、取消这些是它的原生关切。Agno 的 AgentOS 则是在应用框架之上补齐服务化能力：它把 Agent 应用打包成一个能观测、能交互的服务，让你不必自己从零搭这套运行时。同样一套运行时方法论——有状态会话、可观测、可恢复、可取消——pi 让你从底层完全掌控，Agno 让你在它的服务平台上快速拥有。选哪个，取决于你是要一个自己完全掌控的运行时，还是要一个开箱即用的服务化平台。

动手看看

拿你前几章写好的 Research Agent 做起点，做三个小实验，感受“脚本 → 服务”的变化：

给同一个 Agent 用两个不同的 session_id 各跑一轮不同话题，再分别用这两个 id 续问“接着刚才的”，确认两条会话互不串线——这是服务化“有状态会话”最基本的样子。
打开 Agno 的观测能力，跑一次带工具和检索的复杂问题，然后去看这次 run 留下的 trace：模型调了几次、工具调了哪些、花了多少 token。对照上面那张最小字段表，看还缺哪些字段。
把一次“正常的交互式提问”，改造成“设想它由定时任务在早上 8 点触发”的后台形态，列出你需要为它补上的控制项（超时、预算、失败通知……）——你会发现后台形态的清单比交互形态长得多，这正是第 33 章的重点。

实战中的几个坑

坑一：只暴露一个 run(prompt)，服务很快失控。

现象：断线了没法恢复会话，敏感操作没法人审，跑飞的任务没法取消，出错了定位不到。
原因：把有状态会话当成无状态函数来暴露，接口层缺了创建会话、查状态、确认、取 trace、取消这些语义。
对策：按“会话生命周期”设计接口，run 只是其中一个动作，把状态查询、人审、取消、trace 一并暴露。

坑二：把观测面板当演示品，字段严重不全。

现象：出了问题只知道“失败了”，不知道是哪一步、哪个模型、哪个工具、花了多少钱。
原因：观测被当成给人看的漂亮面板，没当成治理的原材料，关键字段（error_type/tool_name/cost/tenant_id）缺失。
对策：按最小字段表落地观测，确保能支撑查失败、算成本、做评测、做治理这四件事。

坑三：把入口当能力，接了 Slack 就以为上线了。

现象：Slack 里能聊了，但鉴权、租户隔离、成本控制、失败恢复一样没有。
原因：混淆了“入口”和“生产能力”——入口只是触达方式，治理能力另在别处。
对策：入口该接就接，但上线门槛看的是会话、权限、观测、回滚，别让门面掩盖内功的缺失。

坑四：后台 Agent 没有预算和超时，成了成本黑洞。

现象：某个定时任务在后台反复重试或死循环，等看到账单才发现烧掉了一大笔 token。
原因：后台形态缺了并发限制、超时、取消、预算上限和失败告警。
对策：后台 Agent 必须配齐预算上限、超时取消、中间状态持久化和失败通知，把“智能”约束成可控成本。

Agno vs 主书 pi 做法

能力	Agno 怎么做	pi（harness）怎么做	各自适合谁
运行时定位	AgentOS 在应用框架之上补齐服务化	harness 本身就是运行时这一层	Agno 快速服务化；pi 从底层完全掌控
会话驱动	显式传 `user_id`/`session_id` 等，框架维护会话	原生按“驱动有状态会话”设计 RPC 接口	两者理念一致，pi 更贴近底层原语
可观测	Monitoring / tracing 现成能力	自建 trace 体系，字段与埋点全掌控	Agno 开箱即用；pi 精确定制
应用入口	Playground / AG-UI / Slack / API / A2A 多入口	入口由你按需接，harness 不预设门面	Agno 入口丰富；pi 保持精简
后台任务	在服务平台上承载定时/异步任务	自己编排队列、超时、重试、预算	Agno 提供承载位；pi 完全自定义

分野和前几章一致：pi 作为 harness，本身就活在“运行时”这一层，有状态会话、可观测、可恢复是它的原生关切，你从底层完全掌控每一个细节；Agno 作为应用框架，用 AgentOS 在应用之上补齐服务化——把启动服务、管理会话、记录 trace、提供多种入口都做成现成的一层，让你不必从零搭运行时。底层是同一套方法论——有状态会话、可观测、可恢复、可取消——只是一个让你掌控地基，一个给你一栋精装好的服务平台。而无论用哪个，治理规则（谁能用什么、什么要人审、预算多少）永远是你要砌的墙，不是框架送的门。

工程检查项

是否区分了本地调试入口（Playground）和生产 API？
是否在每次调用中显式传递 user_id/session_id/tenant_id？
是否支持暂停、确认、取消、恢复这四个动作？
trace 是否覆盖了模型、工具、RAG、Team、Workflow 的每一层调用？
是否能从真实会话抽样，把失败案例送进评测集？
后台任务是否配齐了预算上限、超时和失败告警？

小结

AgentOS/Runtime 负责把 Agno Agent 从脚本推进到可运营服务（对应第 23 章）——demo 证明模型能回答，运行时证明系统能运营。
服务化的核心是有状态会话，不是无状态 run(prompt)（对应第 24 章）：接口要按会话生命周期设计，暴露创建、发送、查状态、确认、取 trace、取消等语义。
观测是治理的原材料，不是演示面板（对应第 25 章）：最小字段要能支撑查失败、算成本、做评测、做治理四件事。
入口不等于能力：Playground、AG-UI、Slack、API、A2A 只是触达方式，真正的生产能力在会话、权限、观测、回滚里。
后台 Agent 要可控（对应第 33 章）：没有预算、超时、恢复和告警，长时任务就是看不见的成本黑洞。

现在 Research Agent 已经是一个能被远程触达、能观测、能恢复的服务了。但“能运营”还不等于“能放心上线”——谁有权调用危险工具、敏感操作怎么审、预算怎么兜底、出了事怎么回滚。下一章，我们把权限、安全、部署和上线门槛这些治理话题合到一起，给这套系统装上最后一道闸。