核心概念

Ageniti 是用来构建「给 Agent 使用的应用」的 SDK。它不会替你创建 Agent，而是给你的应用提供一个清晰边界：把选定产品能力变成可调用、结构化、可审查的入口。

App

Ageniti app 是你选择暴露的能力集合。

export const app = createAgenitiApp({
  name: "workspace-tools",
  description: "通过受控入口暴露的工作区能力。",
  actions: [searchTasks, createTask],
  services: { tasks },
});

你可以从同一个 app 对象创建 CLI、MCP、HTTP、React、JSON、文档和打包入口。

Action

Action 是一个明确的应用能力。

它通常代表你的产品已经会做的事情：

搜索记录
创建任务
导出报表
查询账号状态
触发受控的内部流程

Action 不是 React component、route、prompt，也不是 Agent plan。

Contract

Action contract 是事实来源。

它包含：

name
description
input
output
sideEffects
permissions
supportedSurfaces
visibility
docs

每个对外入口都应该从这份 contract 生成，而不是重新实现一遍业务逻辑。

Runtime

Runtime 负责一致地执行 action。

它处理：

action 查找
surface 检查
输入校验
确认门禁
权限检查
middleware
超时与重试
logs、progress 和 artifacts
输出校验
结构化成功和失败 envelope

Surface

Surface 是调用 action 的入口。

支持的入口包括 CLI、HTTP、MCP、JSON runner、React invocation、本地 dev console、OpenAI-compatible tools 和 AI SDK 风格 tools。

Surface 应该保持轻薄：把自己的输入格式转换成 runtime invocation，再返回 runtime result。

Headless Entry

React、Next.js 和 Expo 应用应该把 UI 文件和用于 CLI、MCP、HTTP、package、publish 的 Ageniti entry 分开。

推荐结构：

src/ageniti/app.js
src/ageniti/actions/create-task.js
src/ageniti/services/tasks.js

这个 headless entry 应该 import services 和 actions，不应该 import React component 或 browser-only API。

Skill Guide

Ageniti 可以从 app 和 action 的 docs 字段导出确定性的 GUIDE.md。这份文档给 Agent、coding assistant 和自动化系统阅读，帮助它们安全使用你的应用能力。

它不是模型生成的，而是从你写下的 contract 推导出来的。