Custom Tools & Approvals

Plugins can export custom tools that the AI agent can invoke during conversations and task execution.

Defining Custom Tools

Agento uses the standard Vercel AI SDK tool format. Tools are defined using tool() and typed with Zod schemas:

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

export const queryDatabaseTool = tool({
  description: "Execute a read-only SQL query against the development database",
  inputSchema: z.object({
    query: z.string().describe("SQL SELECT statement to run"),
    limit: z.number().optional().default(50).describe("Maximum rows to return"),
  }),
  execute: async ({ query, limit }) => {
    // Validate that the query is strictly read-only
    if (!query.trim().toUpperCase().startsWith("SELECT")) {
      throw new Error("Only SELECT queries are permitted in query_database.");
    }

    const rows = await runDbQuery(query, limit);
    return {
      rowCount: rows.length,
      rows,
    };
  },
});

---

Attaching Human Approval Gates

For tools that perform destructive actions, external deployments, or irreversible data changes, you can enforce Human-in-the-Loop Approval.

In your plugin’s subsystem implementation:

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

export const deploymentSubsystem: Subsystem = {
  id: "com.myorg.deployment",
  name: "Deployment Subsystem",

  registerApprovals() {
    return {
      // Requires user confirmation dialog before tool executes
      "deploy_to_production": "user-approval",
      "drop_table": "user-approval",
    };
  },

  registerTools() {
    return {
      deploy_to_production: deployTool,
      drop_table: dropTableTool,
    };
  },
};

When the agent attempts to call a tool registered for "user-approval", Agento pauses execution and displays an interactive modal in the OpenTUI terminal, asking the user to review the parameters and press y to approve or n to reject.