调用入口

Surface 是从 Ageniti app 生成的可调用入口。每个 surface 都应该复用 shared runtime，而不是重复实现校验、授权、日志或输出处理。

CLI

当人、脚本、CI job 或本地运维需要命令入口时，使用 CLI。

await app.createCli().main();

生成的 action command 支持 flags、--json、--schema、稳定 JSON 输出，以及受保护 action 的确认机制。

当 MCP host 需要发现和调用选定应用能力时，使用 MCP。

const handleMcp = app.createMcpHandler();

打包后的 app 也可以生成 stdio launcher：

node ./dist/ageniti/mcp-stdio.mjs

默认情况下，private 和 destructive actions 不会出现在 MCP discovery 中。

当你想把 Ageniti 放在自己的 server、API gateway、route handler 或内部平台后面时，使用 HTTP。

默认路由：

HTTP handler 返回和其他 surface 一样的 runtime envelope。

JSON runner 适合测试、本地脚本、自动化，以及不启动网络服务的确定性调用。

const result = await app.createJsonRunner().invoke({
  action: "create_task",
  input: { title: "Review release" },
});

当现有 UI 想复用 CLI 或 MCP 使用的同一个 action 时，使用 React invocation。

const { useAction } = app.createReactAdapter();
const runCreateTask = useAction(createTask);

Ageniti 不会替换你的组件、路由、状态管理或表单库。

当 LLM 工具栈需要从 action contract 生成 function/tool schema 时，使用 tool adapter。

const openaiTools = app.createOpenAITools();
const responsesTools = app.createOpenAIResponsesTools();
const aiSdkTools = app.createAISDKTools();

面向 LLM 的 adapter 默认会过滤 private 和 destructive actions。

集成过程中可以使用 dev console 在本地检查 action schema 并调用 action。

task-app dev --port 4321

Dev console 是本地测试工具，不是 hosted production UI。