A10 · Agno / AgentOS 与跨语言 Runtime

本模块产出：runtime-agno（跨进程 Adapter）、Tool Governance 边界方案、跨语言 exit drill 报告 · 新增模块 · 建议 4 到 5 天

为什么加这一个框架

三个理由，按重要性排序：

1. 它是求职市场上绕不开的一个。 这门课主线是 TypeScript，但 AI Agent 岗位里 Python 岗占比不低。Agno 是目前 Python 侧工程完成度最高的一档：SDK 加 AgentOS 运行时加控制台三层齐全，四万多 star，迭代频繁。简历上只有 TS 栈的候选人，在 Python 岗面前会直接被过滤。
2. 它把「平台无关」这句话逼到真实边界。 前五个 Adapter 说自己框架无关，其实只证明了 TypeScript 无关。抽象漏没漏，跨语言这一刀切下去才知道。
3. 它自带 A2A、MCP、AG-UI 三个接口。 这三个协议正好是第 8 周、A7、A8 教的东西。接入面已经在你的知识范围内，不需要新学一套私有协议。

学前自测

学习目标

接入第一个不在你语言、也不在你进程里的 Runtime，并回答一个前五个 Adapter 回避掉的问题：当工具执行不再经过你的 Tool Runtime，平台治理靠什么延续。

课程内容

一、Agno SDK 的核心抽象

1. Agent：model / tools / db / knowledge / instructions / session_id / user_id / add_history_to_context / enable_user_memories
2. 执行入口：print_response() 用于开发，run() 与 arun() 用于生产，返回 RunOutputEvent 流
3. Team：members 加 mode，三种模式 coordinate（leader 分派并汇总）、route（路由到成员）、tasks（迭代任务循环，配 max_iterations）
4. Workflow 与步骤原语：Step、Steps、Parallel、Condition、Loop、Router，步骤间用 StepInput.previous_step_content 和 StepOutput 传递
5. Knowledge 与 db：多种向量库与关系库后端，对照你自己的 @agent-os/rag-kit
6. Tools 与 Toolkit 生态，以及 MCP 接入

二、AgentOS 运行时

7. AgentOS(agents=[...], db=..., tracing=True, scheduler=True, mcp_server=True, a2a_interface=True) 与 get_app() / serve()
8. 五十多个 REST 端点、SSE 与 WebSocket
9. JWT 加 RBAC、共享密钥、scoped service account
10. 审批流（human-in-the-loop）与 checkpoint
11. 内置接口：MCP、A2A、AG-UI、Slack、Telegram

三、接入你的平台

12. 三种接入方式的选型：A2A、MCP、裸 HTTP
13. RunOutputEvent 到 AgentEvent 的映射与丢包处理
14. 跨进程的取消、超时与预算控制
15. Tool Governance 边界：薄工具回调 vs 受限租户，两种方案的代价
16. Trace 与 Eval 的三条归一化路径
17. 跨语言 exit drill 与数据迁移成本

三种接入方式怎么选

AgentOS 同时提供 A2A、MCP 和裸 REST，选哪个不是口味问题。

推荐路径是先用 A2A 跑通，再按缺口局部下沉到 REST。一上来就直接调 REST，等于把 A7 学的协议白学了，而且 Adapter 会长满 AgentOS 的私有字段。

A2A 的三个端点是固定的，记住它们就够开工：

• /a2a/agents/{id}/.well-known/agent-card.json 发现
• /a2a/agents/{id}/v1/message:stream 流式执行
• /a2a/agents/{id}/v1/message:send 同步执行

边界在哪里

Tool Governance：这个模块真正的考题

前五个 Adapter 有一条隐含前提：工具执行永远在你手里。 不管上层是 LangGraph 的节点还是 Mastra 的 step，最终 execute 的都是 @agent-os/tool-runtime，所以 Permission Gate、沙箱、工具级 Trace 一次实现处处生效。

Agno 打破了这条前提。它有自己的一百多个 toolkit，在 Python 进程里直接执行。你的审批流对它不可见。

两种解法，各有代价，方案里必须选一个并说明理由。

方案一 · 薄工具回调

Agno 侧只注册一批没有实际执行逻辑的工具，每个工具的函数体是一次回调，把调用请求打回你的 Tool Runtime，等结果再返回给 Agno。

• 好处：Permission Gate、沙箱、工具级 Trace 全部保留，治理和前五个 Runtime 完全一致
• 代价：每次工具调用多一次网络往返，延迟明显上升；Agno 的一百多个内置 toolkit 基本用不上，等于放弃了它的一大卖点
• 适合：工具本身涉及写操作、外部副作用、或者受合规约束的场景

方案二 · 受限租户

把整个 Agno 进程当成平台里的一个租户，不管它内部调什么工具，只在边界上做策略：网络出口白名单、文件系统只读挂载、独立凭证、租户级配额。

• 好处：Agno 的生态可以照常用，延迟没有额外开销
• 代价：工具级审批做不了，只能做进程级隔离；Trace 里看不到它内部调了哪个工具，除非从 AgentOS 拉
• 适合：只读的检索、研究、分析类 Agent

大多数团队最后是混合的：读类工具走方案二，写类和高风险工具走方案一。能把这条混合边界画清楚，比选哪一个更能说明你想过。

实施任务

实现 runtime-agno，这是第六个 Runtime Adapter，也是第一个跨语言跨进程的：

1. 起一个最小 AgentOS 服务：一个 Agent，接 SqliteDb，开 a2a_interface=True 与 tracing=True（骨架在 services/agno-os/）
2. 在 TS 侧补齐 packages/runtime-agno/，通过 A2A 三个端点调用它，复用 A7 的 A2A 客户端
3. 把 RunOutputEvent 流映射为统一 AgentEvent，明确标注哪些事件类型无法一一对应
4. 实现跨进程取消：TS 侧收到取消信号后如何中断远端，以及远端已经发出的工具调用怎么办
5. 选一种 Tool Governance 方案落地，至少实现三个薄工具回调作为对照
6. 把 runtime-agno 注册进 Agent Registry，Capability Matrix 补上进程边界、语言边界、故障域三列，并用 formatCoverage() 打出策略覆盖率
7. 执行一次跨语言 exit drill

框架对照

最后一行是这张表最反直觉的地方：跨进程的依赖在代码上更容易退出，在数据上更难退出。 很多人只算代码那一半。

动手挑战

三十分钟，只做一件事：证明 Agno 的工具调用绕过了你的 Permission Gate。

1. 在 Agno 侧给 Agent 装一个内置 toolkit，比如网络搜索
2. 在你的平台侧把 Permission Gate 的策略调到最严：拒绝一切网络出口工具
3. 通过 A2A 发起一次会触发搜索的请求
4. 观察：请求成功了，你的审批日志里一条记录都没有

看到这个结果之后再往下做。没亲眼见过绕过，就不会真的重视边界方案。

进阶半步：把 Agno 进程的网络出口用防火墙规则封掉，再跑一次，看错误是从哪一层冒出来的、你的平台收到的是什么事件。这半步能让你直观理解方案二的隔离粒度。

Agent OS 里程碑

Agent Registry 支持六类 Runtime，其中一类跨语言跨进程。Capability Matrix 新增三列。

验收标准

• 同一份 Agent Definition 可通过 A2A 调度到 Agno Runtime 执行
• 核心 packages 不出现任何 Agno 或 AgentOS 私有概念，边界只在 packages/runtime-agno/
• 跨进程取消可用，且取消不可靠时显式失败而不是假装成功
• Capability Matrix 明确记录 Agno 在事件完整度上的缺口
• Tool Governance 方案落地并有对照数据：薄工具回调的延迟开销、受限租户的可见性缺口
• 完成跨语言 exit drill，报告同时包含代码迁移成本和数据迁移成本

学后自测

本模块作业

1. services/agno-os/：最小 AgentOS 服务，含一个 Agent、一个 Team、A2A 接口开启
2. packages/runtime-agno/：TS 侧 Adapter，含事件映射表与跨进程取消实现
3. docs/agno-tool-governance.md：两种方案的对照，含薄工具回调的延迟实测和受限租户的可见性缺口清单
4. Capability Matrix 更新：进程边界、语言边界、故障域三列，六个 Runtime 全填
5. docs/agno-exit-drill.md：跨语言 exit drill 报告，代码成本和数据成本分开记

面试考点

这个模块对应面试里的异构系统集成与治理边界，是 Staff 级面试里区分度最高的一类题。

• 「你们平台怎么支持不同语言的 Agent？」：答协议边界替代进程内契约，讲 A2A 先跑通再按缺口下沉的路径。多数候选人只能答「用 HTTP 调」，你能说清楚为什么先 A2A 后 REST。
• 「跨进程之后你的权限控制还生效吗？」：这题是陷阱，答「生效」就完了。诚实答不生效，要重新设计，然后给薄工具回调和受限租户两个方案加各自代价加混合边界。承认抽象失效比声称万能更能拿分。
• 「Agno 和 LangGraph 你选哪个？」：不要站队。答分场景：需要状态图显式建模和 time travel 调试的选 LangGraph，需要快速起一个带 RBAC 和审批的多租户服务的选 AgentOS，团队是 Python 栈的后者省掉一整层。给判断依据不给结论。
• 「引入一个别的语言的运行时，长期成本是什么？」：答三块，代码维护、数据迁移、团队技能。重点讲数据迁移成本被低估这一条，用 exit drill 的两个耗时数字对比。这是很成熟的架构回答，能报数字的候选人极少。
• 「部分可用怎么向调用方表达？」：答 Capability Matrix 加自动降级加监控分层，强调不能把 Runtime 故障伪装成平台故障，反过来也不行。
• 反向陷阱：面试官可能说「既然治理都失效了，为什么还要接」。答生态和岗位现实，同时承认如果团队全是 TS 栈且没有 Python 需求，这一层确实不值得。边界画得比方案更重要。

复习与延伸

官方文档

• Agno 文档
• 构建 Agent
• Team 与三种模式
• Workflow 与步骤原语
• AgentOS 运行时
• AgentOS 的 A2A 接口
• agno-agi/agno 仓库

本仓库对应源码

起手代码已经在仓库里，四个模块正好对应这个模块的四个论点：

pnpm --filter @agent-os/runtime-agno test

29 条测试，全部不依赖网络（fetch 和时钟都是注入的）。测的是机制不是某个版本的事件名，所以 Agno 升级不会让它们变红，只会让 MappingReport.droppedByName 里多出条目。

Python 侧在 services/agno-os/：两个 Agent 分别演薄工具回调和受限租户，一个 Team 给 A6 的编排范式对照用。services/agno-os/README.md 里有绕过实验的完整步骤。

对照着读的：

• packages/contracts/src/agent.ts：AgentDefinition，跨语言之后它仍然是唯一的共同语言
• packages/tool-runtime/：前五个 Runtime 共用的执行层，读一遍才知道跨进程丢的是什么
• packages/adapter-langchain/src/messages.ts：同语言反腐层的写法，和跨进程边界对照着看

相关模块

• A5 的 Capability Matrix 与 exit drill 是这个模块的直接上游
• A7 的 A2A 客户端在这里被复用，Agno 是它第一个真实的对端
• A6 的 Multi-Agent 设计可以拿 Agno 的 Team 三种模式做对照实验
• A9 的责任边界在跨进程场景下要重新过一遍

下一步：回到 A5 把 Capability Matrix 补完，或者去 附录 C 把 Agno 加进贯穿式对照实验。