导出工具与文档

你只定义一次 action。从这同一份 contract,Ageniti 能产出消费者需要的所有产物:MCP tool 清单、LLM tool-call 定义、给 CI 用的机器可读清单,以及人读的 guide 文档。这些都不需要手工维护 —— 全部从活的 action 定义派生,所以永远不会和实现脱节。

下面的例子假设你有一个 app 或一组 actions:

import { createAgenitiApp } from "@ageniti/core";
 
const app = createAgenitiApp({ name: "task-app", actions, services });

LLM tool-call 定义

一份 action 列表,四种目标格式 —— 从 @ageniti/core/ai-sdk 导入:

import {
  createOpenAITools,
  createOpenAIResponsesTools,
  createAISDKTools,
  createFunctionCallingManifest,
} from "@ageniti/core/ai-sdk";
 
const openai = createOpenAITools(actions);             // OpenAI function calling
const responses = createOpenAIResponsesTools(actions); // OpenAI Responses API
const aiSdk = createAISDKTools(actions, { runtime });  // Vercel AI SDK tools
const generic = createFunctionCallingManifest(actions);// 通用 tool-call 清单

默认情况下,destructive 和非 public 的 action 会被排除在这些对外 tool 导出之外 —— 可见性与 side-effect 规则见安全模型。

MCP 清单与 server

import { createMcpManifest, createMcpHandler } from "@ageniti/core/mcp";
 
const manifest = createMcpManifest(actions); // { tools: [...] }
const handler = createMcpHandler({ actions, runtime });

命令行:

ageniti mcp           # 查看 MCP tool 清单 / 启动 server

机器可读清单

用于检视、自定义封装,或 CI 里的 contract 检查 —— 从 @ageniti/core/manifest 导入:

import {
  createActionManifest,
  createSurfaceManifest,
  describeAction,
} from "@ageniti/core/manifest";
 
const actionsManifest = createActionManifest(actions);
const surfaceManifest = createSurfaceManifest({ appName: "task-app", actions });

或通过 app 和 CLI:

const manifest = app.manifest();          // surface 清单
const actionsOnly = app.actionManifest(); // 仅 action contract

ageniti manifest      # 导出清单(接进工具链 / CI)

人读文档

从 @ageniti/core/docs 生成一份统一的 GUIDE.md,描述每个 action 的名字、描述、side-effects、可见性、权限、支持的 surface、何时使用、输入输出示例:

import { createGuideDoc, exportDocs } from "@ageniti/core/docs";
 
const markdown = createGuideDoc({ appName: "task-app", actions });
await exportDocs({ appName: "task-app", actions, outDir: "dist/ageniti" });

或通过 app 和 CLI:

const markdown = app.createGuideDoc();
await app.exportDocs();

ageniti docs          # 打印或导出统一 guide

检测 contract 回归

两个多数 SDK 不会给你的额外能力:

ageniti diff / diffActionManifests(prev, next) —— 对比两份清单,报告破坏性变更、警告和提示性变更。接进 CI,就能让破坏 action contract 的 PR 直接挂掉。
ageniti lint / lintActions(actions) —— 在发布前标出有风险的 action 契约。

ageniti diff old.json new.json   # 检测破坏性 contract 变更
ageniti lint                     # 给 action 契约做体检

import { diffActionManifests } from "@ageniti/core/manifest";
import { lintActions } from "@ageniti/core/lint";
 
const diff = diffActionManifests(previous, next);
if (!diff.ok) throw new Error("破坏性的 action contract 变更");

为什么这很重要

因为每一份导出都从同一组 action 定义派生,你的 MCP tools、LLM tool call、清单和文档永远和 runtime 的真实行为一致。加一个 action,它就会正确地出现在每个 surface 和每份导出产物里。

上一篇测试你的 Action 下一篇 SDK 成熟度