Ageniti

Core Concepts

Ageniti is an SDK for building apps that agents can use. The SDK does not create an agent. It gives your app a clear boundary where selected product capabilities become callable, structured, and reviewable.

App

An Ageniti app is the container for the capabilities you choose to expose.

export const app = createAgenitiApp({
  name: "workspace-tools",
  description: "Workspace capabilities exposed through controlled surfaces.",
  actions: [searchTasks, createTask],
  services: { tasks },
});

The app object is where you create CLI, MCP, HTTP, React, JSON, docs, and packaging surfaces from the same action list.

Action

An action is one explicit app capability.

It should represent something your product already knows how to do:

  • search records
  • create a task
  • export a report
  • inspect account state
  • trigger a controlled internal workflow

An action is not a React component, route, prompt, or agent plan.

Contract

The action contract is the source of truth.

It includes:

  • name
  • description
  • input
  • output
  • sideEffects
  • permissions
  • supportedSurfaces
  • visibility
  • docs

Every surface should be generated from this contract instead of reimplementing business logic.

Runtime

The runtime executes actions consistently.

It handles:

  • action lookup
  • surface checks
  • input validation
  • confirmation gates
  • permission checks
  • middleware
  • timeout and retry
  • logs, progress, and artifacts
  • output validation
  • structured success and failure envelopes

Surface

A surface is a way for a caller to use an action.

Supported surfaces include CLI, HTTP, MCP, JSON runner, React invocation, local dev console, OpenAI-compatible tools, and AI SDK-style tools.

Surfaces should stay thin. They translate their own input format into a runtime invocation and return the runtime result.

Headless Entry

React, Next.js, and Expo apps should keep UI files separate from the Ageniti entry used for CLI, MCP, HTTP, package, and publish artifacts.

Recommended layout:

src/ageniti/app.js
src/ageniti/actions/create-task.js
src/ageniti/services/tasks.js

The headless entry should import services and actions, not React components or browser-only APIs.

Skill Guide

Ageniti can export one deterministic GUIDE.md from app and action docs fields. This guide is for agents, coding assistants, and automation systems that need to understand how to use the app safely.

It is not model-generated. It is derived from the contract you wrote.

PreviousGetting StartedNext Surfaces