边界说明

Ageniti 是 agentic 应用的 action 基础原语层。它让现有 React 和 TypeScript 系统中的选定能力可以作为结构化 action 被所有 surface 调用。

包含范围

• 定义显式 app action（defineAction、defineActions、actionsFromHandlers）
• 直接接受 Zod、Standard Schema v1，或内置 schema
• 保持现有应用结构不变
• 通过 useAction 在 React UI 中调用 action（含状态机与实时流式更新）
• 从 action schema 自动生成 CLI 命令
• 发出实时流式事件（logs / progress / artifacts），任何消费者都能订阅
• 通过轻量 HTTP JSON handler 暴露 action（带细粒度状态码）
• 把 action 暴露为 MCP tool（Content-Length 与 newline framing 自动识别）
• 把 action 暴露为 OpenAI-compatible tool 与 AI SDK 风格 tool
• 通过 JSON runner、进程内或 HTTP 类型化 client 调用
• 为消费方生成 .d.ts 类型化 client 实现自动补全
• 在本地 dev console 中检查 action
• 生成可打包的 CLI 和 MCP launcher
• 导出确定性的 GUIDE.md skill 文档
• 对比 action manifest 以降低发布风险
• 返回结构化成功与失败 envelope
• 附带 logs、progress 和 artifacts
• 处理权限、确认、超时、retry、idempotency key 与单 action 并发限制
• 在 logs、artifact metadata 与 error message 中脱敏密钥
• 通过 manifest 和 adapter 描述 surface 能力

由你决定

下面这些不在本层的范围内 —— 这样 runtime 保持小而聚焦，对你如何在它之上组合 action 不持立场：

• planning 或 reasoning loop
• 长期 memory system
• 模型之间的 tool routing
• workflow orchestration engine
• hosted execution platform
• durable job queue
• marketplace distribution
• 替代应用自身的鉴权系统
• 自动把任意 React component tree 解析成工具

你可以在它之上构建任意一种 —— runtime 提供的流式事件 API 和类型化 contract 都可以被这些上层读取。

设计原则

Action contract 是事实来源。所有 surface 和 client 都从它派生；runtime 负责观察它。