Ageniti

Ageniti

Ageniti is the action primitive layer for apps that need to expose capabilities to agents, automation systems, and external tools. Define an action once and the runtime makes it callable from CLI, HTTP, MCP, OpenAI-compatible tool calling, Vercel AI SDK-style tools, a JSON runner, a typed client, the React useAction hook, and a local dev console — all from the same contract.

What You Get

  • A typed action contract built with defineAction() (or defineActions / actionsFromHandlers for batch wiring).
  • A shared runtime with validation, permissions, middleware, timeout, retry, idempotency keys, concurrency limits, log redaction, and live streaming events.
  • Thin surface adapters for CLI, HTTP, MCP, React, JSON automation, local development, and LLM tool calling.
  • A typed client (createClient) and codegen (generateClientTypes) for IDE autocomplete across processes.
  • Direct interop with Zod and Standard Schema v1 — no schema rewrite required.
  • Official packaging helpers for CLI launchers, MCP stdio launchers (Content-Length and newline framing), manifests, and bundle metadata.
  • Project tools for init, doctor, config-driven builds, and zero-config app entry discovery.
  • A consistent success and failure envelope across surfaces.

Core Model

Existing app capability
        |
        v
Typed action contract
        |
        v
Shared runtime
        |
        +--> CLI
        +--> JSON runner
        +--> MCP
        +--> OpenAI tools
        +--> AI SDK tools
        +--> Dev console
        +--> React invocation

Ageniti keeps most decisions in the runtime and keeps each external surface thin. That means one action definition can be reused across tooling without rewriting the business logic for every integration.

Install

npm install @ageniti/core

Ageniti is ESM-only and requires Node.js 20 or newer.

Minimal Example

import { createAgenitiApp, defineAction, s } from "@ageniti/core";
 
const searchTasks = defineAction({
  name: "search_tasks",
  description: "Search workspace tasks by status.",
  input: s.object({
    status: s.enum(["open", "blocked", "done"]).describe("Task status"),
  }),
  output: s.object({
    items: s.array(
      s.object({
        id: s.string(),
        status: s.string(),
      })
    ),
  }),
  run(input, ctx) {
    ctx.logger.info("Searching tasks.", { status: input.status });
    return ctx.services.tasks.search(input);
  },
});
 
export const app = createAgenitiApp({
  name: "workspace-tools",
  actions: [searchTasks],
  services: { tasks },
});

From there you can expose the same action through app.createCli(), app.createMcpHandler(), app.createAISDKTools(), app.createReactAdapter(), or app.createDevServer().

React And Expo Workflow

For React, Next.js, and Expo projects, the intended model is:

  • keep business logic in shared services
  • wrap selected capabilities as Ageniti actions
  • add one headless Node-safe app entry such as src/ageniti/app.ts
  • use npx @ageniti/core init react, npx @ageniti/core init expo, npx @ageniti/core init next, and npx @ageniti/core doctor for project setup
  • use your generated app CLI, such as task-app build and task-app publish, to generate and ship official artifacts

That keeps your UI unchanged while giving you a stable packaging path for the surfaces agents and automation systems can use.

Documentation Map

  • Getting Started: build the first action and expose it through the main surfaces.
  • Agentic Primitives: the five core primitives — action contract, schema interop, bulk handlers, streaming events, typed client.
  • Core Concepts: app, action, contract, runtime, surface, and headless entry.
  • Surfaces: when to use CLI, MCP, HTTP, JSON, React, tools, and the dev console.
  • Safety Model: visibility, permissions, confirmation, side effects, and metadata.
  • Packaging: generated bundles, MCP descriptors, package, publish, and release review.
  • API Reference: detailed reference for the public SDK API.
  • Entry Points: package exports and when to import each subpath.
  • Runtime Semantics: envelopes, errors, retry, timeout, confirmation, logs, and artifacts.
  • Recipes: copyable integration patterns for common setups.
  • SDK Readiness: product bar for shipping an SDK that exposes app capabilities to agents.
  • Roadmap: prioritized next steps for turning the SDK into a more trusted product.
  • Skill Guide: compact reference for the skills an Ageniti app exposes.
  • Scope: what Ageniti deliberately does and does not do.
  • FAQ: direct answers about positioning and usage.
  • Release Checklist: packaging and publish checks.

Design Boundaries

You explicitly declare the capabilities you want to expose, then choose which surfaces should be allowed to invoke them. The runtime stays small — it does not inspect your React tree, replace routing, own state management, or orchestrate planning loops.

Next Getting Started