Surfaces

Surfaces are the callable interfaces generated from an Ageniti app. Each surface should reuse the shared runtime instead of duplicating validation, authorization, logging, or output handling.

CLI

Use CLI when humans, scripts, CI jobs, or local operators need a command entry point.

await app.createCli().main();

Generated action commands support flags, --json, --schema, stable JSON output, and confirmation for protected actions.

MCP

Use MCP when an MCP host should discover and call selected app capabilities.

const handleMcp = app.createMcpHandler();

A bundled app can also generate a stdio launcher:

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

Private and destructive actions are filtered from MCP discovery by default.

HTTP

Use HTTP when you want to put Ageniti behind your own server, API gateway, route handler, or internal platform.

Default routes:

• GET /ageniti/actions
• POST /ageniti/actions/:name/invoke

The HTTP handler returns the same structured runtime envelope as other surfaces.

JSON Runner

Use the JSON runner for tests, local scripts, automation, and deterministic invocation without a network server.

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

React Invocation

Use React invocation when an existing UI wants to call the same action as CLI or MCP.

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

Ageniti does not replace your components, router, state management, or form library.

OpenAI And AI SDK Tools

Use tool adapters when an LLM stack needs function/tool schemas generated from action contracts.

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

LLM-oriented adapters filter private and destructive actions by default.

Dev Console

Use the dev console during integration to inspect action schemas and invoke actions locally.

task-app dev --port 4321

The dev console is for local testing, not a hosted production UI.

Choosing A Surface

• Start with CLI when you want the fastest local proof.
• Add MCP when an agent host needs tool discovery.
• Add HTTP when your own backend should own transport and auth.
• Add React invocation when existing UI should reuse the same action.
• Add generated tool schemas when an LLM stack needs structured function definitions.