Agents

An agent is a specialist the primary harness can delegate to. Soubi preserves native subagents where possible and reports the fallback when a harness uses skills, tools, or instructions instead.

Define an agent in TypeScript

import { defineAgent } from "soubi";

export default defineAgent({
  description: "Review application code for correctness and regressions.",
  model: "sonnet",
  allowedTools: ["Read", "Grep", "Bash"],
  filePatterns: ["src/**/*.ts", "app/**/*"],
  instructions: "Trace affected callers and report actionable findings.",
});

The filename supplies the default name. Use name only when the model-facing identifier should differ.

Author a Markdown agent

Markdown agents map closely to harnesses that use frontmatter-based subagent files:

---
name: security-reviewer
description: Review authentication and secret-handling code.
model: sonnet
allowed-tools: [Read, Grep]
file-patterns: ["**/auth/**", "**/*secret*"]
---

Review trust boundaries, authorization checks, and secret exposure.

Soubi accepts .md agents as well as TypeScript and JavaScript modules.

Add agent-scoped hooks

TypeScript agents can carry hooks that apply only to that specialist:

import { defineAgent, defineHook } from "soubi";

export default defineAgent({
  name: "pr-reviewer",
  instructions: "Review the current change.",
  hooks: [
    defineHook({
      event: "Stop",
      handler: { type: "command", command: "./scripts/review-finished.sh" },
    }),
  ],
});

Soubi lifts the hook into the portable hook list with the agent scope attached. Each adapter emits that scope natively or reports the translation.

Handle target differences

Use harness for native settings such as mode, temperature, or maximum turns. Use onUnsupported: "fail" when the specialist is required for the plugin to function.

Read Fallback Tiers before making an agent load-bearing, and check Compatibility for the targets that translate agents.