Ageniti

Ageniti 概览

Ageniti 是 agentic 应用的 action 基础原语层。定义一次 action，runtime 就能把它暴露给 CLI、HTTP、MCP、OpenAI 兼容的 tool calling、Vercel AI SDK 风格工具、JSON runner、类型化 client、React useAction hook，以及本地 dev console —— 全部来自同一份 contract。

你会得到什么

  • 通过 defineAction() 定义的类型化 action contract（或用 defineActions / actionsFromHandlers 批量包装）。
  • 一套共享 runtime，统一处理校验、权限、中间件、超时、retry、idempotency key、并发限制、日志脱敏，以及实时流式事件。
  • 面向 CLI、HTTP、MCP、React、JSON 自动化、本地开发和 LLM tool calling 的薄适配层。
  • 类型化 client（createClient）和 codegen（generateClientTypes），跨进程也能拿到 IDE 自动补全。
  • Zod 与 Standard Schema v1 的直接互操作 —— 不需要重写 schema。
  • 官方打包能力，生成 CLI launcher、MCP stdio launcher（自动识别 Content-Length 和 newline framing）、manifest 和 bundle 元数据。
  • 面向项目接入的工具，包括 init、doctor、配置驱动构建，以及零配置 app 入口发现。
  • 在不同 surface 上保持一致的成功和失败返回结构。

核心模型

Existing app capability
        |
        v
Typed action contract
        |
        v
Shared runtime
        |
        +--> CLI
        +--> JSON runner
        +--> MCP
        +--> OpenAI tools
        +--> AI SDK tools
        +--> Dev console
        +--> React invocation

Ageniti 把重要语义集中在 runtime 中，把每个对外 surface 做得很薄。这样同一个 action 定义可以复用到多种入口，而不用为每种集成方式重复写一遍业务逻辑。

安装

npm install @ageniti/core

Ageniti 是纯 ESM 包，需要 Node.js 20 或更高版本。

最小示例

import { createAgenitiApp, defineAction, s } from "@ageniti/core";
 
const searchTasks = defineAction({
  name: "search_tasks",
  description: "Search workspace tasks by status.",
  input: s.object({
    status: s.enum(["open", "blocked", "done"]).describe("Task status"),
  }),
  output: s.object({
    items: s.array(
      s.object({
        id: s.string(),
        status: s.string(),
      })
    ),
  }),
  run(input, ctx) {
    ctx.logger.info("Searching tasks.", { status: input.status });
    return ctx.services.tasks.search(input);
  },
});
 
export const app = createAgenitiApp({
  name: "workspace-tools",
  actions: [searchTasks],
  services: { tasks },
});

接下来你可以通过 app.createCli()、app.createMcpHandler()、app.createAISDKTools()、app.createReactAdapter() 或 app.createDevServer() 把同一个 action 暴露到不同入口。

React 与 Expo 工作流

对于 React、Next.js 和 Expo 项目，推荐工作流是：

  • 把业务逻辑放在可复用 service 中
  • 把选定能力包成 Ageniti action
  • 单独增加一个 Node-safe 的 headless app 入口，例如 src/ageniti/app.ts
  • 使用 npx @ageniti/core init react、npx @ageniti/core init expo、npx @ageniti/core init next 和 npx @ageniti/core doctor 完成项目接入
  • 使用你生成的 app CLI，例如 task-app build 和 task-app publish 生成并交付官方产物

这样可以保持现有 UI 不变，同时得到稳定的对外调用打包路径。

文档导航

  • 快速开始：从零定义第一个 action 并暴露到主要 surface。
  • 基础原语：5 个核心原语 —— action contract、schema 互操作、批量 handlers、流式事件、类型化 client。
  • 核心概念：app、action、contract、runtime、surface 和 headless entry。
  • 调用入口：什么时候使用 CLI、MCP、HTTP、JSON、React、tools 和 dev console。
  • 安全模型：visibility、权限、确认、副作用和 metadata。
  • 打包发布：generated bundle、MCP descriptor、package、publish 和 release review。
  • API 参考：完整的公开 SDK API 说明。
  • 入口模块：包导出路径和各 subpath 的使用场景。
  • Runtime 语义：返回结构、错误、重试、超时、确认、日志和 artifacts。
  • Recipes：常见集成方式的可复制模式。
  • SDK 成熟度：判断一个让应用能力可被 Agent 调用的 SDK 何时足够可发布、可推广。
  • Roadmap：按 P0 / P1 / P2 排好的下一阶段产品与文档路线图。
  • Skill 指南：说明 Ageniti app 对外暴露的 skill contract。
  • 边界说明：Ageniti 有意包含和不包含的能力。
  • 常见问题：关于定位和使用方式的直接回答。
  • 发布检查清单：打包和发布前的检查项。

设计边界

你需要显式声明想暴露的应用能力，再决定哪些 surface 可以调用它们。Runtime 保持小而聚焦 —— 不会扫描你的 React tree、替换路由、接管状态管理或编排 planning loop。

下一篇 快速开始