安全模型

Ageniti 的核心是显式暴露。你的应用决定哪些能力成为 action，也决定哪些 surface 可以调用它们。

Visibility

用 visibility 描述 action 应该被谁发现或调用。

defineAction({
  name: "create_task",
  visibility: "public",
  // ...
});

常见含义：

• private：仅内部使用
• local：本地开发或运维使用
• agent：适合给 Agent 或工具入口调用
• public：适合公开 manifest 和文档展示

默认情况下，private actions 不会暴露到公开工具入口。

Supported Surfaces

用 supportedSurfaces 显式限制 action 可以在哪些入口运行。

defineAction({
  name: "export_report",
  supportedSurfaces: ["cli", "json", "dev"],
  // ...
});

如果 invocation 来自不支持的 surface，runtime 会返回 UNSUPPORTED_SURFACE。

Side Effects

用 sideEffects 表达操作风险。

• read：不修改外部状态
• write：会改变外部状态
• destructive：会删除、覆盖、取消、关闭或执行不可逆操作

Destructive actions 默认需要确认，并且默认不会暴露到 MCP 和 LLM adapter。

Permissions

Action 声明所需权限，app 通过 permissionChecker 执行真实检查。

createAgenitiApp({
  actions,
  permissionChecker({ action, context }) {
    return action.permissions.every((permission) =>
      context.auth?.permissions?.includes(permission)
    ) || "Missing required permission.";
  },
});

Ageniti 不替代你的 auth system。它提供统一 hook，让你的应用授权模型可以跨 surface 生效。

Public Metadata

publicMetadata 用来放可以安全出现在 manifest、MCP tools 和 LLM tool schema 中的信息。

metadata 用来放应用内部字段。

Confirmation

如果某个 action 必须显式确认才能运行，设置 requiresConfirmation: true。

Destructive actions 默认继承这个行为。

实用检查清单

• 让 action 保持窄而清晰。
• 优先返回结构化对象，而不是只有自然语言文本。
• 诚实标记 write 和 destructive 操作。
• 用 supportedSurfaces 限制高风险 action。
• 用 permissions 和 permissionChecker 做真实授权。
• 把安全使用说明写进 description 和 docs。
• 发布前检查生成的 manifest。