SDK Overview

@agento/sdk is the official, open-source TypeScript framework for extending Agento. It allows developers to author custom tools, configure human-in-the-loop approval gates, inject boot-time pre-flight checks, and provide custom mode-aware system instructions.

Installation

Install @agento/sdk along with the Vercel AI SDK into your plugin project:

# Using Bun
bun add @agento/sdk ai zod

# Using npm
npm install @agento/sdk ai zod

# Using pnpm
pnpm add @agento/sdk ai zod

---

Extension Capabilities

With @agento/sdk, you can extend Agento across four key dimensions:

1. Custom Deterministic Tools: Inject custom tools into the agent’s toolset using standard AI SDK tool() definitions with Zod schema validation.
2. Approval Policies: Attach interactive human confirmation requirements to sensitive actions (such as deploying to staging or executing database migrations).
3. Boot Setup Tasks: Run pre-flight checks during application startup (e.g. verifying container health or checking API connectivity).
4. Mode-Aware Instructions: Provide specialized system instructions tailored for Plan Mode versus Act Mode.

---

Plugin Architecture

A plugin is defined using the definePlugin() helper, which validates your plugin’s configuration and metadata:

import { definePlugin } from "@agento/sdk";

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 {
      // AI SDK Tool definitions
    };
  },

  registerSubsystems() {
    return [
      // Custom Subsystems
    ];
  },
});

---

Zero Runtime Footprint

The @agento/sdk package contains pure TypeScript interfaces and contracts. It has zero closed-source runtime dependencies, allowing you to develop, test, and publish plugins independently.