Skip to content
Agento

SDK overview

@agento/sdk is the TypeScript framework for extending Agento. It provides contracts and builders for custom tools, human approval gates, boot-time pre-flight checks, and mode-aware system prompts.

Quickstart

Section titled “Quickstart”

Scaffold a starter plugin with the CLI:

Terminal window
# Scaffold a new plugin project
agento plugin init my-plugin


cd agento-plugin-my-plugin


# Install dependencies
npm install # or pnpm install / bun install


# Build
npm run build # or pnpm build / bun run build

Installation

Section titled “Installation”

Install @agento/sdk directly into any plugin repository:

Terminal window
# npm
npm install @agento/sdk


# pnpm
pnpm add @agento/sdk


# bun
bun add @agento/sdk

@agento/sdk exports tool, z, Effect, and Schema directly. You do not need separate package installations for schema validation or Effect primitives.

Plugin capabilities

Section titled “Plugin capabilities”
  1. Custom tools: Define tools with defineTool() using Zod schemas or Effect programs.
  2. Approval gates: Require user confirmation before running destructive actions.
  3. Boot setup tasks: Run health and environment checks during application launch.
  4. Mode instructions: Provide tailored guidance for Plan Mode and Act Mode.

Plugin architecture

Section titled “Plugin architecture”

Define a plugin using definePlugin() or the chainable createPluginBuilder():

import { definePlugin, defineTool, z } from "@agento/sdk";


export const helloTool = defineTool({
  description: "Greet a user with a message",
  parameters: z.object({
    name: z.string().default("world"),
  }),
  execute: ({ name }) => ({ message: `Hello, ${name}!` }),
});


export default definePlugin({
  id: "com.example.my-plugin",
  name: "My Custom Plugin",
  version: "1.0.0",
  description: "Custom deterministic tools and verification workflows",
  registerTools() {
    return {
      hello: helloTool,
    };
  },
});

Public repositories

Section titled “Public repositories”