API Reference

This page documents the public SDK surface exported by @ageniti/core.

Top-Level Import

For most applications, start with the root export:

import {
  createAgenitiApp,
  createRuntime,
  defineAction,
  s,
} from "@ageniti/core";

Use subpath exports only when you want a narrower import boundary. See Entry Points.

`defineAction(config)`

Defines a typed action contract.

Required fields:

name: lowercase snake_case action name
description: human-readable action description
run(input, context): action implementation

Optional fields:

version
title
input
output
visibility
sideEffects
idempotency
permissions
supportedSurfaces
timeoutMs
retry
requiresConfirmation
metadata
publicMetadata
docs
deprecated
deprecation

Metadata model:

metadata: internal metadata kept in manifests and available at runtime through context.metadata
publicMetadata: safe-to-expose metadata copied into public manifests, MCP tool metadata, and LLM tool adapters

Docs model:

docs: natural-language guidance used to generate a unified GUIDE.md
app-level docs supports summary, audience, whenToUse, quickStart, setup, operationalNotes, sections, and examples
action-level docs supports whenToUse, whenNotToUse, usageNotes, inputExample, and outputExample
GUIDE.md is deterministic output; it does not call a model or infer behaviour from UI code

Versioning model:

version: action contract version, default 1.0.0
deprecated: marks an action as deprecated without removing it
deprecation: optional message, replacement, and timeline metadata

Important defaults:

title: derived from name
input: s.object({})
visibility: "local"
sideEffects: "read"
idempotency: "unspecified"
permissions: []
supportedSurfaces: cli, json, http, mcp, react, dev, ai-sdk
retry: normalised to { retries, delayMs }
requiresConfirmation: true for destructive actions unless overridden

Example:

const deleteTask = defineAction({
  name: "delete_task",
  description: "Delete a task by id.",
  sideEffects: "destructive",
  requiresConfirmation: true,
  input: s.object({
    taskId: s.string().min(1),
  }),
  async run(input, ctx) {
    return ctx.services.tasks.remove(input.taskId);
  },
});

`createAgenitiApp(options)`

Creates an app object that owns actions, runtime, and surface helpers.

const app = createAgenitiApp({
  name: "task-app",
  description: "Workspace task operations for agents.",
  docs: {
    summary: "Use this app to create tasks and inspect status.",
  },
  actions,
  services,
  permissionChecker,
  middleware,
  adapters,
  build,
});

Options:

name: required app name
actions: array of Ageniti actions
services: shared services injected into context.services
permissionChecker: authorisation hook
middleware: runtime middleware chain
adapters: custom surface adapter list for manifest generation
build: default build settings reused by app.build() and CLI build commands

Returned members:

name
actions
adapters
runtime
manifest()
actionManifest()
lint()
build()
createGuideDoc()
exportDocs()
createCli()
createJsonRunner()
createHttpHandler()
createHttpServer()
createMcpHandler()
createMcpManifest()
createOpenAITools()
createOpenAIResponsesTools()
createAISDKTools()
createFunctionCallingManifest()
createReactAdapter()
createDevServer()

Use createAgenitiApp() when you want one app definition and convenient access to every supported surface.

`createRuntime(options)`

Creates the headless runtime used by all app capability surfaces.

Options:

actions
services
permissionChecker
middleware

Returned API:

registry: Map<string, Action>
listActions({ surface? })
invoke(actionOrName, input?, invokeOptions?)

invokeOptions supports:

invocationId
surface
user
auth
env
services
metadata
signal
timeoutMs
retry
confirm

The runtime is responsible for:

action lookup
supported surface checks
input validation
confirmation checks
permission checks
middleware execution
timeout and retry
output serialisation and output validation
success and failure envelopes

Read Runtime Semantics for the full execution model.

Manifest And Registry Helpers

`createActionRegistry(actions)`

Builds a Map keyed by action name and throws on duplicates.

`createActionManifest(actions)`

Returns a plain array describing actions with schemas and metadata. This helper is useful for inspection, tooling, tests, or custom wrappers.

`describeAction(action)`

Normalises a single action into a manifest-friendly object.

`createSurfaceManifest({ appName, actions, adapters })`

Returns a manifest object with:

app name
generation timestamp
action descriptions
surface descriptions and capabilities

CLI API

`createCli(options)`

Creates a CLI object.

const cli = createCli({
  name: "task-app",
  actions,
  runtime,
  runtimeOptions,
  env,
  adapters,
  buildOptions,
});

Returned members:

name
actions
runtime
run(argv?, io?)
main(argv?, io?)

Built-in commands:

<app> <action> [options]
<app> <action> --json '{"field":"value"}'
<app> <action> --schema
<app> actions
<app> manifest
<app> diff --previous old.json --next new.json
<app> build [manifest|cli|mcp|docs|bundle] [options]
<app> docs [options]
<app> package [options]
<app> publish [options]
<app> init <react|expo|next> [options]
<app> doctor [options]
<app> lint
<app> mcp
<app> mcp --stdio
<app> dev --port 4321

Input behaviour:

snake_case actions can also be called as kebab-case commands
boolean flags accept --flag, --flag true, or --no-flag
array, object, and any inputs are parsed from JSON strings
runtime confirmation maps to --confirm

Build command options:

--out-dir <dir>
--app-module <module-path>
--app-export <name>
--package-json
--cwd <dir>
--filename <name> for docs

Launcher targets need a Node-safe app module so the generated files know what to import. If --app-module is omitted, Ageniti tries to discover a default entry such as ./src/ageniti/app.js.

JSON Runner API

`createJsonRunner(options)`

Creates a small structured invocation wrapper.

const runner = createJsonRunner({ actions, runtime, runtimeOptions });

Returned API:

runtime
invoke(payload)

Payload fields:

action
input
confirm
user
auth
metadata

If the payload is not an object, the runner returns INVALID_JSON_RUNNER_PAYLOAD.

MCP API

`createMcpManifest(actions, options)`

Returns:

{
  tools: [
    {
      name,
      title,
      description,
      inputSchema,
      metadata,
    },
  ],
}

Filtering rules:

action must support the mcp surface
private actions are excluded unless includePrivate: true
destructive actions are excluded unless includeDestructive: true

`createMcpHandler(options)`

Creates a JSON-RPC handler for tools/list and tools/call.

const handle = createMcpHandler({
  actions,
  runtime,
  runtimeOptions,
  includePrivate,
  includeDestructive,
});

tools/call returns both a text block and structuredContent containing the runtime result.

`createMcpStdioServer(options)`

Creates a line-delimited stdio transport around createMcpHandler().

await createMcpStdioServer({ actions, runtime }).start();

Use this when another process expects one JSON-RPC message per line over stdin and stdout.

LLM Tool Adapters

`createOpenAITools(actions, options)`

Returns Chat Completions-style function tools.

`createOpenAIResponsesTools(actions, options)`

Returns Responses-style function tools.

`createAISDKTools(actions, options)`

Returns a Vercel AI SDK-style tools object.

const tools = createAISDKTools(actions, {
  runtime,
  returnEnvelope: true,
});

Each tool contains:

description
parameters: Ageniti schema object
inputSchema: JSON Schema representation
execute(input, options?)

`createFunctionCallingManifest(actions, options)`

Returns a combined summary:

openaiChatTools
openaiResponsesTools
aiSdkTools as action names

Shared adapter options:

runtime
strict
includePrivate
includeDestructive
surface
returnEnvelope
filter

Filtering rules:

action must support the selected surface, default ai-sdk
private actions are excluded unless includePrivate: true
destructive actions are excluded unless includeDestructive: true
filter(action) can apply additional filtering

React API

`createReactActionAdapter(options)`

Creates a React-friendly wrapper over the shared runtime.

const { runtime, useAction } = createReactActionAdapter({ actions, runtime });

useAction(action) returns an async function that invokes the action with surface: "react".

Dev Server API

`createDevServer(options)`

Creates the local dev console server.

const devServer = createDevServer({
  name: "task-app",
  actions,
  runtime,
});
 
const listener = await devServer.listen(4321, "127.0.0.1");

Routes:

GET /: HTML dev console
GET /api/actions: action manifest for the dev surface
POST /api/actions/:name/invoke: invoke one action

HTTP API

`app.createHttpHandler(options)`

Creates a framework-friendly HTTP JSON handler.

const handle = app.createHttpHandler();
 
const response = await handle({
  method: "POST",
  path: "/ageniti/actions/create_task/invoke",
  body: {
    input: {
      title: "Follow up with design review",
      priority: "high",
    },
  },
});

Routes:

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

`app.createHttpServer(options)`

Creates a small Node HTTP server around the same handler.

const server = app.createHttpServer();
const listener = await server.listen(4322);

HTTP actions must support the http surface. Private and destructive actions are filtered out by default.

Build API

`app.build(options)`

Builds official Ageniti distribution artifacts from an app object.

await app.build({
  targets: ["bundle"],
  appModule: "./src/ageniti/app.js",
  appExport: "app",
  outDir: "./dist/ageniti",
});

Common options:

targets: manifest, cli, mcp, docs, or bundle
outDir: output directory, default dist/ageniti
appModule: headless Node-safe module that exports your app
appExport: export name, default app
includePackageJson: force a generated package.json
cwd: working directory used for path resolution
filename: custom file name for docs, default GUIDE.md

bundle expands to:

ageniti.manifest.json
ageniti.actions.json
cli.mjs
mcp-stdio.mjs
ageniti.mcp.json
GUIDE.md
package.json
README.md
ageniti.bundle.json

`app.createGuideDoc(options)`

Returns one Markdown guide string.

const markdown = app.createGuideDoc();

It reads the app description / docs, plus each action's description, permissions, side effects, surfaces, publicMetadata, and docs.

`app.exportDocs(options)`

Writes a unified guide document to disk.

await app.exportDocs({
  outDir: "./dist/ageniti",
});

Default output:

GUIDE.md

The same capability is available through the CLI:

task-app docs
task-app docs --out-dir ./dist/ageniti
task-app build docs --out-dir ./dist/ageniti

`app.package(options)`

Builds a bundle and then runs npm pack in the generated output directory.

const result = await app.package({
  appModule: "./src/ageniti/app.js",
  outDir: "./dist/ageniti",
});

The result includes:

outDir
packageDir
packageFile
build

`app.publish(options)`

Builds a bundle, runs npm pack, and then runs npm publish.

const result = await app.publish({
  appModule: "./src/ageniti/app.js",
  outDir: "./dist/ageniti",
  dryRun: true,
  access: "public",
});

Important defaults:

dryRun defaults to true
pass dryRun: false only for a real publish

The returned result includes:

ok
name
outDir
targets
files
report

`buildArtifacts(options)`

Lower-level build helper used by app.build().

Manifest Diff

`diffActionManifests(previous, next)`

Compares two action manifests or surface manifests and reports breaking changes, warnings, and informational changes.

const diff = diffActionManifests(previousManifest, nextManifest);

Breaking changes include removed actions and input/output schema changes.

const result = await buildArtifacts({
  appName: "task-app",
  actions,
  adapters,
  targets: ["bundle"],
  appModule: "./src/ageniti/app.js",
  appExport: "app",
});

Use this helper when you want to build launchers or manifests without first constructing an app object.

Project Tools

`initProject(options)`

Scaffolds a React- or Expo-friendly headless Ageniti entry.

const result = await initProject({
  cwd: process.cwd(),
  template: "react",
});

The result includes:

ok
template
cwd
files
appModule
nextSteps

`doctorProject(options)`

Inspects a project for framework type, default Ageniti entry discovery, and common launcher or build issues.

const result = await doctorProject({ cwd: process.cwd() });

The result includes:

ok
kind
cwd
defaultAppModule
checks
recommendations

`findDefaultAppModule(options)`

Finds the default Node-safe Ageniti app entry used by zero-config build flows.

const result = await findDefaultAppModule({ cwd: process.cwd() });

Possible outcomes include:

found: true with modulePath and reason node-safe-default
found: true with modulePath and reason configured
found: false with reason typescript-only-entry
found: false with reason missing

`loadProjectConfig(options)`

Loads ageniti.config.json, ageniti.config.js, ageniti.config.mjs, or ageniti.config.cjs from a project root.

const config = await loadProjectConfig({ cwd: process.cwd() });

Returned fields may include:

build.appModule
build.appExport
build.outDir
build.includePackageJson
build.typescriptRuntime
mcp.transport
mcp.env
package.name
package.version
package.description
package.private
package.binName
configPath

`detectTypeScriptRuntime(options)`

Detects whether the current project is configured to generate TypeScript launchers.

const runtime = detectTypeScriptRuntime({ packageJson, config });

Current built-in support:

returns tsx when tsx is configured or installed
returns undefined when no supported TypeScript runtime is available

Surface Adapter API

`defineSurfaceAdapter(adapter)`

Creates a custom adapter description.

Required field:

name

Defaulted fields:

description: ""
capabilities: {}
canExpose: () => true
describe: (action) => action

Built-In Adapters

cliAdapter
jsonAdapter
mcpAdapter
reactAdapter
devAdapter
aiSdkAdapter

duplicate action names
invalid action naming
weak descriptions
destructive MCP exposure
unspecified idempotency on write or destructive actions
non-object input shapes
write or destructive actions without permissions

Schema API

`s`

Lightweight schema builder.

Available builders:

s.string()
s.number()
s.boolean()
s.enum(values)
s.array(schema)
s.object(shape)
s.literal(value)
s.union(schemas)
s.record(schema)
s.any()

Common modifiers:

.describe(text)
.default(value)
.optional()
.nullable()
.meta(data)

Type-specific helpers:

string: .min(), .max(), .pattern(), .url(), .datetime()
number: .min(), .max(), .int()
object: .passthrough()

code
issues
retryable

Runtime Result Shape

Success:

{
  "ok": true,
  "data": {},
  "artifacts": [],
  "logs": [],
  "meta": {
    "action": "create_task",
    "invocationId": "invocation-id",
    "surface": "cli",
    "durationMs": 12
  }
}

Failure:

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid action input.",
    "issues": [],
    "retryable": false
  },
  "artifacts": [],
  "logs": [],
  "meta": {
    "action": "create_task",
    "invocationId": "invocation-id",
    "surface": "mcp",
    "durationMs": 3
  }
}

PreviousEntry Points Next Recipes