Creating a plugin

Agento scaffolds plugin projects using the agento plugin init command. This creates a TypeScript project equipped with example tools, human approval gates, boot-time pre-flight checks, and coding assistant rules (AGENTS.md).

1. Scaffold the plugin

Run agento plugin init to generate a new plugin workspace:

# Standard starter with custom tools, subsystems, and approval gates
agento plugin init @my-org/agento-plugin-database ./agento-plugin-database

# Minimal single-file plugin
agento plugin init my-tools --flavor minimal

# Effect-native plugin
agento plugin init worker --flavor effect

# MCP server bridge
agento plugin init postgres-mcp --flavor mcp-bridge

Available template flavors

Flavor	Best for	Description
standard	Full plugins (default)	Includes custom tools, subsystems, boot tasks, and approval gates.
minimal	Fast tool distribution	Single-file TypeScript entrypoint with zero boilerplate.
effect	Functional runtimes	Effect-first architecture with Effect.gen and typed Schemas.
mcp-bridge	External integrations	Bridges Model Context Protocol (MCP) tool servers to Agento.

The generated project structure (for standard flavor):

agento-plugin-database/
├── package.json             # Scripts (build, typecheck) and peer dependencies
├── tsconfig.json            # Strict TypeScript configuration
├── README.md                # Human developer guide
├── AGENTS.md                # Coding assistant rules
└── src/
    ├── index.ts             # Entrypoint exporting definePlugin()
    ├── tools/
    │   └── example.ts       # Deterministic tool with Zod schema
    └── subsystems/
        └── example.ts       # Subsystem with SetupTask and approval gate

2. Install dependencies

Install dependencies using your preferred package manager:

# npm
npm install

# pnpm
pnpm install

# bun
bun install

3. Working with AGENTS.md

The scaffolded AGENTS.md file defines the working rules and @agento/sdk conventions for AI coding assistants.

When you open your plugin project in an AI-assisted environment, the assistant reads AGENTS.md to understand:

• How to define type-safe tools with defineTool() and z.
• How to implement the Subsystem interface via defineSubsystem().
• How to attach "user-approval" gates to sensitive actions.
• Verification commands (npm run typecheck, npm run build).

4. Customize tools and subsystems

Defining a custom tool (src/tools/query.ts)

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

export const dbQueryTool = defineTool({
  description: "Execute a read query against the database",
  parameters: z.object({
    query: z.string().describe("SQL SELECT query to execute"),
  }),
  execute: async ({ query }) => {
    return {
      result: "Query executed successfully",
      timestamp: new Date().toISOString(),
    };
  },
});

Implementing the subsystem (src/subsystems/database.ts)

import { defineSubsystem, defineSetupTask } from "@agento/sdk";

export const databaseSubsystem = defineSubsystem({
  id: "com.myorg.database.subsystem",
  name: "Database Subsystem",
  setupTasks: [
    defineSetupTask({
      id: "db:preflight",
      name: "Database Connection Pre-Flight",
      description: "Verifies database connectivity at boot",
      run: async (ctx) => {
        ctx.emitProgress("Testing connection...");
        ctx.emitProgress("Connected.");
      },
    }),
  ],
  approvals: {
    run_migration: "user-approval",
  },
  instructions: {
    plan: "DATABASE: You are in Plan Mode. Inspect schema before planning migrations.",
    act: "DATABASE: You are in Act Mode. Execute approved migrations.",
  },
});

5. Local testing with Agento

1. Build the plugin:

   npm run build # or pnpm build / bun run build

2. Link the package locally:

   npm link # or bun link / pnpm link --global

3. In your target repository, link and register the plugin in .agento/config.json:

   npm link @my-org/agento-plugin-database

   In .agento/config.json:

   {
     "plugins": ["@my-org/agento-plugin-database"]
   }

4. Launch agento and verify that your plugin tools and startup tasks appear in the interactive session.