API 参考

这页文档描述 @ageniti/core 的公开 SDK API。

顶层导入

大多数应用直接从根导出开始即可：

import {
  createAgenitiApp,
  createRuntime,
  defineAction,
  s,
} from "@ageniti/core";

只有在你明确需要更窄的导入边界时，才建议使用 subpath export。见入口模块。

`defineAction(config)`

用于定义类型化 action contract。

必填字段：

name：小写 snake_case action 名
description：面向人的 action 描述
run(input, context)：action 实现

可选字段：

version
title
input
output
visibility
sideEffects
idempotency
permissions
supportedSurfaces
timeoutMs
retry
requiresConfirmation
metadata
publicMetadata
docs
deprecated
deprecation

Metadata 模型：

metadata：内部 metadata，会保留在 manifest 中，并在运行时通过 context.metadata 可用
publicMetadata：可安全暴露的 metadata，会进入公开 manifest、MCP tool metadata 和 LLM tool adapter

文档模型：

docs：用于生成统一 GUIDE.md 的自然语言说明
app 级 docs 支持 summary、audience、whenToUse、quickStart、setup、operationalNotes、sections、examples
action 级 docs 支持 whenToUse、whenNotToUse、usageNotes、inputExample、outputExample
GUIDE.md 是确定性导出，不会调用模型，也不会从 UI 里猜测业务逻辑

版本模型：

version：action contract 版本，默认 1.0.0
deprecated：标记 action 已废弃，但不直接移除
deprecation：可选的废弃说明、替代 action 和时间线 metadata

重要默认值：

title：由 name 自动推导
input：s.object({})
visibility："local"
sideEffects："read"
idempotency："unspecified"
permissions：[]
supportedSurfaces：cli、json、http、mcp、react、dev、ai-sdk
retry：会被标准化成 { retries, delayMs }
requiresConfirmation：destructive action 默认会开启

示例：

const deleteTask = defineAction({
  name: "delete_task",
  description: "Delete a task by id.",
  sideEffects: "destructive",
  requiresConfirmation: true,
  input: s.object({
    taskId: s.string().min(1),
  }),
  async run(input, ctx) {
    return ctx.services.tasks.remove(input.taskId);
  },
});

`createAgenitiApp(options)`

创建一个持有 action、runtime 和 surface helper 的 app 对象。

const app = createAgenitiApp({
  name: "task-app",
  description: "Workspace task operations for agents.",
  docs: {
    summary: "Use this app to create tasks and inspect status.",
  },
  actions,
  services,
  permissionChecker,
  middleware,
  adapters,
  build,
});

参数：

name：必填 app 名称
actions：Ageniti action 数组
services：注入到 context.services 的共享服务
permissionChecker：授权检查 hook
middleware：runtime 中间件链
adapters：用于 manifest 生成的自定义 surface adapter 列表
build：传给 app.build() 和 CLI build 命令的默认构建配置

返回成员：

name
actions
adapters
runtime
manifest()
actionManifest()
lint()
build()
createGuideDoc()
exportDocs()
createCli()
createJsonRunner()
createHttpHandler()
createHttpServer()
createMcpHandler()
createMcpManifest()
createOpenAITools()
createOpenAIResponsesTools()
createAISDKTools()
createFunctionCallingManifest()
createReactAdapter()
createDevServer()

如果你希望围绕一组 action 搭一个统一 app，这是最推荐的入口。

`createRuntime(options)`

创建底层 headless runtime，所有应用能力调用入口都复用它。

参数：

actions
services
permissionChecker
middleware

返回 API：

registry：Map<string, Action>
listActions({ surface? })
invoke(actionOrName, input?, invokeOptions?)

invokeOptions 支持：

invocationId
surface
user
auth
env
services
metadata
signal
timeoutMs
retry
confirm

runtime 负责：

action 查找
surface 支持检查
输入校验
确认检查
权限检查
中间件执行
超时和重试
输出序列化与输出校验
成功和失败 envelope

完整执行模型见 Runtime 语义。

Manifest 与 Registry Helper

`createActionRegistry(actions)`

创建一个以 action name 为 key 的 Map，若有重复 action name 会直接抛错。

`createActionManifest(actions)`

返回一个纯对象数组，包含 action 的 schema 与元数据。适合做 inspection、tooling、测试，或自定义包装层。

`describeAction(action)`

把单个 action 规范化成 manifest-friendly 的对象。

`createSurfaceManifest({ appName, actions, adapters })`

返回的 manifest 包含：

app 名称
生成时间戳
action 描述列表
surface 描述和 capabilities

CLI API

`createCli(options)`

创建 CLI 对象。

const cli = createCli({
  name: "task-app",
  actions,
  runtime,
  runtimeOptions,
  env,
  adapters,
  buildOptions,
});

返回成员：

name
actions
runtime
run(argv?, io?)
main(argv?, io?)

内建命令：

<app> <action> [options]
<app> <action> --json '{"field":"value"}'
<app> <action> --schema
<app> actions
<app> manifest
<app> diff --previous old.json --next new.json
<app> build [manifest|cli|mcp|docs|bundle] [options]
<app> docs [options]
<app> package [options]
<app> publish [options]
<app> init <react|expo|next> [options]
<app> doctor [options]
<app> lint
<app> mcp
<app> mcp --stdio
<app> dev --port 4321

输入行为：

snake_case action 也可以用 kebab-case 调用
布尔 flag 支持 --flag、--flag true 或 --no-flag
array、object 和 any 类型通过 JSON 字符串解析
运行时确认映射为 --confirm

构建命令常用参数：

--out-dir <dir>
--app-module <module-path>
--app-export <name>
--package-json
--cwd <dir>
docs 命令可额外使用 --filename <name>

launcher target 需要一个可在 Node 中直接导入的 app module。若未提供 --app-module，Ageniti 会尝试自动发现默认入口，例如 ./src/ageniti/app.js。

JSON Runner API

`createJsonRunner(options)`

创建一个轻量的结构化调用包装层。

const runner = createJsonRunner({ actions, runtime, runtimeOptions });

返回 API：

runtime
invoke(payload)

payload 字段：

action
input
confirm
user
auth
metadata

如果 payload 不是对象，runner 会返回 INVALID_JSON_RUNNER_PAYLOAD。

MCP API

`createMcpManifest(actions, options)`

返回结构：

{
  tools: [
    {
      name,
      title,
      description,
      inputSchema,
      metadata,
    },
  ],
}

过滤规则：

action 必须支持 mcp surface
private action 默认不暴露，除非 includePrivate: true
destructive action 默认不暴露，除非 includeDestructive: true

`createMcpHandler(options)`

创建处理 tools/list 和 tools/call 的 JSON-RPC handler。

const handle = createMcpHandler({
  actions,
  runtime,
  runtimeOptions,
  includePrivate,
  includeDestructive,
});

tools/call 的结果里既有文本内容，也有包含 runtime 结果的 structuredContent。

`createMcpStdioServer(options)`

围绕 createMcpHandler() 构建一个按行分隔 JSON-RPC 消息的 stdio transport。

await createMcpStdioServer({ actions, runtime }).start();

适合对接要求 stdin/stdout 每行一条 JSON-RPC 消息的宿主进程。

LLM Tool Adapter API

`createOpenAITools(actions, options)`

返回 Chat Completions 风格的 function tools。

`createOpenAIResponsesTools(actions, options)`

返回 Responses 风格的 function tools。

`createAISDKTools(actions, options)`

返回 Vercel AI SDK 风格的 tools object。

const tools = createAISDKTools(actions, {
  runtime,
  returnEnvelope: true,
});

每个 tool 包含：

description
parameters：Ageniti schema 对象
inputSchema：JSON Schema 表示
execute(input, options?)

`createFunctionCallingManifest(actions, options)`

返回组合摘要：

openaiChatTools
openaiResponsesTools
aiSdkTools，其中内容是 action name 列表

共享参数：

runtime
strict
includePrivate
includeDestructive
surface
returnEnvelope
filter

过滤规则：

action 必须支持被选中的 surface，默认是 ai-sdk
private action 默认被过滤，除非 includePrivate: true
destructive action 默认被过滤，除非 includeDestructive: true
filter(action) 可以叠加额外过滤条件

React API

`createReactActionAdapter(options)`

创建 React 友好的 runtime 包装层。

const { runtime, useAction } = createReactActionAdapter({ actions, runtime });

useAction(action) 会返回一个异步函数，并以 surface: "react" 调用该 action。

Dev Server API

`createDevServer(options)`

创建本地 dev console server。

const devServer = createDevServer({
  name: "task-app",
  actions,
  runtime,
});
 
const listener = await devServer.listen(4321, "127.0.0.1");

路由：

GET /：HTML dev console
GET /api/actions：dev surface 下的 action manifest
POST /api/actions/:name/invoke：调用单个 action

HTTP API

`app.createHttpHandler(options)`

创建一个适合接入任意 Web 框架的 HTTP JSON handler。

const handle = app.createHttpHandler();
 
const response = await handle({
  method: "POST",
  path: "/ageniti/actions/create_task/invoke",
  body: {
    input: {
      title: "Follow up with design review",
      priority: "high",
    },
  },
});

路由：

GET /ageniti/actions
POST /ageniti/actions/:name/invoke

`app.createHttpServer(options)`

基于同一个 handler 创建一个轻量 Node HTTP server。

const server = app.createHttpServer();
const listener = await server.listen(4322);

HTTP action 必须支持 http surface。private 和 destructive action 默认不会暴露。

Build API

`app.build(options)`

基于 app 对象构建官方 Ageniti 分发产物。

await app.build({
  targets: ["bundle"],
  appModule: "./src/ageniti/app.js",
  appExport: "app",
  outDir: "./dist/ageniti",
});

常用参数：

targets：manifest、cli、mcp、docs 或 bundle
outDir：输出目录，默认 dist/ageniti
appModule：导出 app 的 headless、Node-safe 模块
appExport：导出名，默认 app
includePackageJson：强制生成 package.json
cwd：用于解析路径的工作目录
filename：docs 的自定义文件名，默认 GUIDE.md

bundle 会展开生成：

ageniti.manifest.json
ageniti.actions.json
cli.mjs
mcp-stdio.mjs
ageniti.mcp.json
GUIDE.md
package.json
README.md
ageniti.bundle.json

`app.createGuideDoc(options)`

返回单个 Markdown 指南字符串。

const markdown = app.createGuideDoc();

它会读取 app 的 description / docs，以及每个 action 的 description、权限、副作用、surface、publicMetadata 和 docs。

`app.exportDocs(options)`

把统一指南写入磁盘。

await app.exportDocs({
  outDir: "./dist/ageniti",
});

默认输出：

GUIDE.md

也可以通过 CLI 使用同一能力：

task-app docs
task-app docs --out-dir ./dist/ageniti
task-app build docs --out-dir ./dist/ageniti

`app.package(options)`

先构建 bundle，然后在输出目录里执行 npm pack。

const result = await app.package({
  appModule: "./src/ageniti/app.js",
  outDir: "./dist/ageniti",
});

返回结果包含：

outDir
packageDir
packageFile
build

`app.publish(options)`

先构建 bundle，再执行 npm pack，最后执行 npm publish。

const result = await app.publish({
  appModule: "./src/ageniti/app.js",
  outDir: "./dist/ageniti",
  dryRun: true,
  access: "public",
});

重要默认值：

dryRun 默认是 true
只有在真实发布时才应传 dryRun: false

返回结果包含：

ok
name
outDir
targets
files
report

`buildArtifacts(options)`

app.build() 底层使用的低层构建 helper。

Manifest Diff

`diffActionManifests(previous, next)`

比较两个 action manifest 或 surface manifest，并报告 breaking change、warning 和信息性变化。

const diff = diffActionManifests(previousManifest, nextManifest);

breaking change 包括 action 被移除，以及输入/输出 schema 变化。

const result = await buildArtifacts({
  appName: "task-app",
  actions,
  adapters,
  targets: ["bundle"],
  appModule: "./src/ageniti/app.js",
  appExport: "app",
});

当你希望不先创建 app 对象、直接构建 launcher 或 manifest 时，可以使用它。

Project Tools

`initProject(options)`

初始化一个适合 React 或 Expo 的 headless Ageniti 入口。

const result = await initProject({
  cwd: process.cwd(),
  template: "react",
});

返回结果包含：

ok
template
cwd
files
appModule
nextSteps

`doctorProject(options)`

检查当前项目的框架类型、默认 Ageniti 入口发现结果，以及常见 launcher 或构建问题。

const result = await doctorProject({ cwd: process.cwd() });

返回结果包含：

ok
kind
cwd
defaultAppModule
checks
recommendations

`findDefaultAppModule(options)`

查找零配置构建流程使用的默认 Node-safe Ageniti app 入口。

const result = await findDefaultAppModule({ cwd: process.cwd() });

可能的结果包括：

found: true，并带有 modulePath，原因是 node-safe-default
found: true，并带有 modulePath，原因是 configured
found: false，原因是 typescript-only-entry
found: false，原因是 missing

`loadProjectConfig(options)`

从项目根目录加载 ageniti.config.json、ageniti.config.js、ageniti.config.mjs 或 ageniti.config.cjs。

const config = await loadProjectConfig({ cwd: process.cwd() });

返回字段可能包括：

build.appModule
build.appExport
build.outDir
build.includePackageJson
build.typescriptRuntime
mcp.transport
mcp.env
package.name
package.version
package.description
package.private
package.binName
configPath

`detectTypeScriptRuntime(options)`

检测当前项目是否已经配置好 TypeScript launcher 生成所需 runtime。

const runtime = detectTypeScriptRuntime({ packageJson, config });

当前内建支持：

当项目安装或配置了 tsx 时返回 tsx
当没有可用的受支持 TypeScript runtime 时返回 undefined

Surface Adapter API

`defineSurfaceAdapter(adapter)`

创建一个自定义 adapter 描述对象。

必填字段：

name

默认字段：

description: ""
capabilities: {}
canExpose: () => true
describe: (action) => action

内建 Adapter

cliAdapter
jsonAdapter
mcpAdapter
reactAdapter
devAdapter
aiSdkAdapter

`defaultSurfaceAdapters()`

返回 createAgenitiApp() 和 createCli() 默认使用的 adapter 列表。

`findAdapter(adapters, name)`

按名称查找单个 adapter。

Lint API

`lintActions(actions)`

对 action 定义执行静态检查。

当前可能的 finding 包括：

重复 action name
非法 action 命名
描述太弱
destructive action 暴露到 MCP
write 或 destructive action 未声明 idempotency
输入 schema 不是 object
write 或 destructive action 未声明 permissions

Schema API

`s`

轻量 schema builder。

可用 builder：

s.string()
s.number()
s.boolean()
s.enum(values)
s.array(schema)
s.object(shape)
s.literal(value)
s.union(schemas)
s.record(schema)
s.any()

常用 modifier：

.describe(text)
.default(value)
.optional()
.nullable()
.meta(data)

类型相关 helper：

string：.min()、.max()、.pattern()、.url()、.datetime()
number：.min()、.max()、.int()
object：.passthrough()

`toJSONSchema(schema)`

把 Ageniti schema 转成 JSON Schema。

`SchemaValidationError`

schema parse 路径在校验失败时会抛出的错误类型。

错误与结果类型

`AgenitiError`

自定义 runtime 错误，包含：

code
issues
retryable

Runtime Result 结构

成功：

{
  "ok": true,
  "data": {},
  "artifacts": [],
  "logs": [],
  "meta": {
    "action": "create_task",
    "invocationId": "invocation-id",
    "surface": "cli",
    "durationMs": 12
  }
}

失败：

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid action input.",
    "issues": [],
    "retryable": false
  },
  "artifacts": [],
  "logs": [],
  "meta": {
    "action": "create_task",
    "invocationId": "invocation-id",
    "surface": "mcp",
    "durationMs": 3
  }
}