Safety Model

Ageniti is built around explicit exposure. Your app chooses which capabilities become actions and which surfaces are allowed to call them.

Visibility

Use visibility to describe who should be able to discover or use an action.

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

Common meanings:

• private: internal only
• local: local development or operator usage
• agent: suitable for agent/tool usage
• public: safe for public manifests and docs

Private actions are hidden from public tool surfaces by default.

Supported Surfaces

Use supportedSurfaces to explicitly limit where an action can run.

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

If a runtime invocation arrives from an unsupported surface, it returns UNSUPPORTED_SURFACE.

Side Effects

Use sideEffects to communicate operational risk.

• read: no external mutation
• write: changes external state
• destructive: deletes, overwrites, cancels, closes, or performs irreversible work

Destructive actions require confirmation by default and are filtered from MCP and LLM adapters unless explicitly included.

Permissions

Permissions are declared on the action and enforced through the app-level permissionChecker.

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

Ageniti does not replace your auth system. It gives your app a consistent hook for applying it across surfaces.

Public Metadata

Use publicMetadata for data that can safely appear in manifests, MCP tools, and LLM tool schemas.

Use metadata for internal app-only fields.

Confirmation

Set requiresConfirmation: true when an action should not run without an explicit confirmation flag.

Destructive actions inherit this behavior by default.

Practical Checklist

• Keep actions narrow and named clearly.
• Prefer structured output over prose-only strings.
• Mark write and destructive operations honestly.
• Limit high-risk actions with supportedSurfaces.
• Use permissions plus permissionChecker for real authorization.
• Put safe usage guidance in description and docs.
• Review generated manifests before publishing.