Ageniti

SDK 成熟度

这页用来判断 Ageniti 作为“给 Agent 使用的应用 SDK”是否已经足够成熟。

它不是用来评估 autonomous agent orchestration 的清单，而是用来评估一个 app-facing SDK 是否已经能把产品能力安全、稳定、可预期地暴露给外部宿主。

“够成熟”到底指什么

对 Ageniti 来说，“够成熟”不意味着：

  • 它负责 planning loop
  • 它内建长期 memory
  • 它负责模型路由
  • 它变成一个 agent runtime

它真正应该做到的是：

  • 开发者可以不重构整个应用，就暴露一个真实产品能力
  • 宿主可以通过标准 surface 发现并调用这个能力
  • operator 可以在发布前审查 contract
  • 高风险 action 可以被一致地过滤、确认或拒绝
  • 所有 surface 都返回一致的执行语义

如果这些属性已经扎实，这个 SDK 就在完成自己的职责。

面向 Agent-App SDK 的发布标准

下面这些能力足够稳定时，才适合把 SDK 叫做“广泛可用”。

1. 稳定的 action contract

SDK 必须让应用能力变得显式、可审查。

最低标准：

  • typed input schema
  • typed output schema
  • 稳定的 action name
  • side effect metadata
  • visibility control
  • 面向 host 和 operator 的自然语言说明

在 Ageniti 里，这部分由 defineAction()、action metadata 和导出的 manifest 承担。

2. 共享 runtime 语义

所有 surface 都应该经过同一套 runtime 规则。

最低标准：

  • input validation
  • output validation
  • timeout handling
  • retry support
  • permission check
  • 风险 action 的 confirmation
  • 结构化 logs、progress 和 artifacts
  • 稳定的成功/失败 envelope

没有这一层，每个 adapter 都会变成一个行为分叉点。

3. 标准宿主入口

一个给 Agent 使用应用的 SDK，必须覆盖足够多的宿主接入面。

当前高价值入口通常是：

  • CLI，给 operator、脚本和 CI
  • MCP，用于 tool discovery
  • HTTP，给内部 gateway
  • OpenAI-compatible tools
  • OpenAI Responses tools
  • AI SDK executable tools
  • JSON runner，给测试和自动化

真正关键的问题不是“surface 数量够不够多”，而是“它们是否都保留了同一份 contract”。

4. 默认安全模型

如果一个 app SDK 会把产品能力暴露给外部调用方，默认安全策略比功能数量更重要。

最低标准：

  • destructive action 默认要求确认
  • private action 不进入 public surface
  • 高风险 action 可以限制在受信任入口
  • auth hook 能复用宿主应用自己的鉴权模型
  • public metadata 和 internal metadata 分离

这不只是安全问题，也是产品可信度问题。

5. 打包与交付产物

SDK 应该生成下游团队真的能安装、检查、review 的产物。

最低标准：

  • CLI launcher
  • MCP stdio launcher
  • action manifest
  • surface manifest
  • 确定性的 guide 或 contract 文档
  • 方便 release review 的 bundle metadata

如果每次交付都还要大量手工 glue code，这个 SDK 仍然太薄。

下一步最该补什么

如果核心 runtime 和 surface 已经具备，下一阶段通常更该补“接入质量”，而不是继续扩展框架边界。

宿主接入示例

SDK 应该给出真实宿主接入示例，而不只是底层 API 片段。

最值得优先补的例子：

  • OpenAI Responses API host
  • Vercel AI SDK route handler
  • MCP desktop host setup
  • internal HTTP gateway wrapper

这些示例能帮开发者回答一个很现实的问题：这周我要怎么把它接进我的栈里？

Contract 维护工作流

SDK 应该帮助团队在演进应用能力时避免意外破坏兼容性。

高价值补强：

  • CI 里的 manifest diff
  • action rename 或 deprecate 时的兼容说明
  • versioned action rollout 示例
  • 高风险 contract 变更的 release review 指南

面向 operator 的调试能力

采用 app SDK 的团队，需要快速定位失败原因。

高价值补强：

  • 更清晰的 error taxonomy
  • invocation replay 示例
  • artifact inspection 指南
  • logging 和 progress 约定示例
  • 针对常见接入错误的 doctor 检查

更锋利的定位文档

很多 SDK 被误解，是因为大家总拿它和 agent framework 对比。

文档里应该明确区分：

  • app SDK 和 agent framework
  • app capability 和 agent skill
  • host integration 和 orchestration
  • product boundary 和 workflow engine

定位越锋利，正确用户越容易快速自我筛选。

一个简单的成熟度测试

如果一个新团队能在一个下午内完成下面这些事，这个 SDK 就已经很像样了：

  1. 把一个现有产品能力包成 action。
  2. 在本地通过 CLI 跑通。
  3. 通过 MCP 或 tool calling 暴露出去。
  4. 把一个高风险 action 限制在 public surface 之外。
  5. 导出可审查的 guide 和 manifest。
  6. 不读 SDK 内部源码也能理解失败原因。

如果其中某一步仍然很脆弱，那它就是下一步最该补的产品或文档缺口。

结论

Ageniti 不需要长成 agent framework，才能变得更强。

它会因为下面这些方面做得更好而变强：

  • 更容易接入
  • 默认更安全
  • 更容易 review
  • 更容易打包
  • 更容易接进真实宿主

这才是最值得优化的标准。

上一篇Recipes下一篇 Roadmap