Custom tools and approvals

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

Defining custom tools

@agento/sdk exports defineTool(), which supports standard asynchronous functions and Effect programs:

Standard tool definition

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

export const queryDatabaseTool = defineTool({
  description: "Execute a read-only SQL query against the development database",
  parameters: 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 }) => {
    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,
    };
  },
});

Effect-native tool definition

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

export const calculateMetricsTool = defineTool({
  description: "Compute metrics with pure Effect pipelines",
  parameters: z.object({
    datasetId: z.string(),
  }),
  execute: ({ datasetId }) =>
    Effect.gen(function* () {
      const data = yield* fetchDatasetEffect(datasetId);
      return { totalCount: data.length };
    }),
});

Attaching human approval gates

For tools that perform destructive actions or external deployments, you can enforce human confirmation.

Register approval gates in your plugin’s subsystem definition:

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

export const deploymentSubsystem = defineSubsystem({
  id: "com.myorg.deployment",
  name: "Deployment Subsystem",
  approvals: {
    "deploy_to_production": "user-approval",
    "drop_table": "user-approval",
  },
  tools: {
    deploy_to_production: deployTool,
    drop_table: dropTableTool,
  },
});

When the agent calls 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 approve or reject.