Hooks & Guardrails - Agentium

In plain terms

Three ways to attach your own code:

Thing	Job	Example
`hooks`	Watch. Log. Count.	”Print when a run starts.”
`guardrails`	Block.	”Refuse if the user says a password.”
`loopHooks`	Steer inside the tool loop.	”Skip `delete_all` and pretend it failed.”

The event bus is also for watching. Prefer hooks when you already have the agent object. Prefer onAny for tracers.

hooks — the four doorbells

Hook	When
`beforeRun`	Right before the model is called
`afterRun`	After a successful answer
`onToolCall`	A tool is about to run
`onError`	Something threw

hooks: {
  beforeRun: async (ctx) => console.log("start", ctx.runId),
  afterRun: async (ctx, output) => console.log(output.usage.totalTokens, "tokens"),
  onToolCall: async (ctx, name, args) => console.log("tool", name, args),
  onError: async (ctx, err) => console.error(err.message),
}

These cannot skip a tool. For that, use loopHooks.beforeToolExec.

Guardrails — teachers who can send you back

Input runs before the model sees the question. Fail → the run throws. Output runs after the answer. Fail → the run throws (and a cached answer is dropped).

guardrails: {
  input: [{
    name: "no-secrets",
    validate: async (input) => {
      const text = typeof input === "string" ? input : "";
      if (text.includes("sk-")) return { pass: false, reason: "looks like an API key" };
      return { pass: true };
    },
  }],
}

loopHooks — the steering wheel

Full page: Loop hooks.

loopHooks: {
  beforeToolExec: async (name) => {
    if (name === "drop_database") return { skip: true, result: "blocked" };
  },
  onRoundtripComplete: async (n, tokens) => {
    if (tokens.totalTokens > 50_000) return { stop: true };
  },
}