Creating a Plugin: Step-by-Step Guide

Agento makes plugin authoring instant with the agento plugin init command, which scaffolds a complete TypeScript project equipped with example AI SDK tools, human approval gates, boot-time pre-flight checks, and AI assistant rules (AGENTS.md).

1. Scaffold the Plugin

Run agento plugin init to generate a new plugin workspace:

agento plugin init @my-org/agento-plugin-database ./agento-plugin-database
cd agento-plugin-database

This creates the following package-manager-agnostic structure:

agento-plugin-database/
├── package.json             # Scripts (build, typecheck) & peer dependencies
├── tsconfig.json            # Strict TypeScript configuration
├── README.md                # Human developer guide
├── AGENTS.md                # AI agent instructions for coding assistants
└── src/
    ├── index.ts             # Entrypoint exporting definePlugin()
    ├── tools/
    │   └── example.ts       # AI SDK tool with Zod schema
    └── subsystems/
        └── example.ts       # Subsystem with SetupTask & Approval gate

---

2. Install Dependencies

Install dependencies using your preferred package manager:

# npm
npm install

# pnpm
pnpm install

# bun
bun install

---

3. The AGENTS.md Advantage

The scaffolded AGENTS.md file defines the working rules and @agento/sdk conventions for AI coding assistants (such as Antigravity, Cursor, Claude Code, or GitHub Copilot).

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 tool() and zod.
• How to implement the Subsystem interface.
• How to attach "user-approval" gates to sensitive actions.
• Verification commands (npm run typecheck, npm run build).

---

4. Customizing Tools and Subsystems

Defining a Custom Tool (src/tools/query.ts)

import { tool } from "ai";
import { z } from "zod";

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

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

import type { Subsystem, AgentMode } from "@agento/sdk";

export const databaseSubsystem: Subsystem = {
  id: "com.myorg.database.subsystem",
  name: "Database Subsystem",

  registerSetupTasks() {
    return [
      {
        id: "db:preflight",
        name: "Database Connection Pre-Flight",
        description: "Verifies database connectivity at boot",
        required: false,
        async run(ctx) {
          ctx.emitProgress("Testing connection...");
          ctx.emitProgress("Connected.");
        },
      },
    ];
  },

  registerApprovals() {
    return {
      run_migration: "user-approval",
    };
  },

  getInstructions(mode: AgentMode): string | null {
    if (mode === "plan") {
      return "DATABASE: You are in Plan Mode. Inspect schema before planning migrations.";
    }
    return "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.