Subsystems and boot tasks

A subsystem packages related tools, approval rules, mode instructions, and startup setup tasks into a single unit.

Authoring subsystems with defineSubsystem()

@agento/sdk exports defineSubsystem() and defineSetupTask() to author subsystems:

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

export const redisSubsystem = defineSubsystem({
  id: "com.myorg.redis",
  name: "Redis Cache Subsystem",
  setupTasks: [
    defineSetupTask({
      id: "redis:ping",
      name: "Redis Server Health Check",
      description: "Checks if local Redis instance is responding to PING",
      required: false,
      run: async (ctx) => {
        ctx.emitProgress("Pinging Redis at localhost:6379...");
        const response = await pingRedis({ signal: ctx.signal });
        if (response !== "PONG") {
          throw new Error("Redis failed to respond to PING.");
        }
        ctx.emitProgress("Redis online and healthy.");
      },
    }),
  ],
  instructions: {
    plan: "REDIS: In Plan Mode, inspect cache keys before planning mutations.",
    act: "REDIS: In Act Mode, ensure all new keys specify TTLs.",
  },
  dispose: async () => {
    await redisClient.quit();
  },
});

Authoring boot setup tasks

Boot setup tasks run during application launch before entering the interactive chat UI. They allow plugins to verify required system binaries, validate credentials, or check service health.

Both Promise and Effect runtimes are supported:

Standard promise task

defineSetupTask({
  id: "docker:check",
  name: "Docker Daemon Status",
  run: async (ctx) => {
    ctx.emitProgress("Checking Docker daemon...");
    await checkDockerSocket(ctx.signal);
    ctx.emitProgress("Docker ready.");
  },
});

Effect task

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

defineSetupTask({
  id: "env:verify",
  name: "Environment Validation",
  run: (ctx) =>
    Effect.gen(function* () {
      ctx.emitProgress("Validating environment variables...");
      yield* Effect.void;
      ctx.emitProgress("Environment verified.");
    }),
});

Resource disposal

When an Agento session closes or resets, Agento calls dispose() on all active subsystems to cleanly close network sockets, background workers, or child processes.