Agentic Toolkit

Reusable infrastructure for building agentic systems with multi-model councils, hierarchical sub-agents, and provenance-tracked tool loops.

Lifted from production code (Brandling, 2026 BytePlus Seedance Beta hackathon) and hardened with the lessons documented in that codebase's "what we'd change" appendix — depth caps enforced at the runner level, provenance required at the type level, per-model knobs lifted into the registry, secretarial summaries to combat context explosion in nested spawn trees.

This is a reference TypeScript package, not a tested library. The point is to save a week of plumbing per new agentic project (groot-finance, yf-hazop, tutorial-gen, …) by shipping the five things every Brandling-style system ends up re-implementing.

What's in here

agentic-toolkit/
├── .claude-plugin/
│   └── plugin.json
└── src/
    ├── gateway.ts               # multi-model gateway adapter
    ├── models-registry.ts       # per-role model registry with knobs
    ├── sub-agent-runner.ts      # depth + spawn + timeout enforced runner
    ├── events.ts                # typed AgentSseEvent + formatSseEvent
    ├── provenance.ts            # required _source tag + helpers
    └── council-state-machine.ts # generic foreman with mandatory start/end

The five components

1. Gateway adapter (gateway.ts). A thin createGateway({ baseURL, apiKey, name? }) wrapper around @ai-sdk/openai-compatible. Keep one provider for Claude / GPT / Gemini behind a unified endpoint (TokenRouter, OpenRouter, LiteLLM, Vercel AI Gateway). The registry is the single seam where "Opus is suddenly expensive" turns into a 1-character edit.

2. Models registry (models-registry.ts). A typed ModelsRegistry binding role names to { model, knobs } entries. Per-model knobs (e.g. noToolChoiceRequired: true for GPT-class models that infinite-loop on toolChoice: 'required') live in the registry, not at every call site. Ships with defaultBrandlingRegistry showing the 8-role marketing council as a starting template.

3. Sub-agent runner (sub-agent-runner.ts). runSubAgent with depth cap, per-parent spawn cap, wall-clock timeout, and a typed SubAgentResult ('ok' | 'failed' | 'depth_exceeded' | 'timeout'). Ported from Brandling's runSubAgent and hardened: Brandling tracked depth in events only; this runner refuses to spawn beyond maxDepth so prompt regressions can't blow past the limit.

4. Events (events.ts). The full AgentSseEvent typed union (phase_change, phase_status, agent_step with depth + parentAgent, agent_error, mutation_field) plus formatSseEvent. AgentTraceRole and AgentPhase are generic so HAZOP / finance / tutorial-gen pipelines can name their roles and phases without forking the file.

5. Provenance (provenance.ts). GenerationSource ('live' | 'cached'

assertProvenance runtime guard. _source is required at the type level — Brandling shipped it optional and got bitten by demo data masquerading as live output downstream.

The council state machine

6. Council state machine (council-state-machine.ts). A generic foreman runner. Pass a persona palette, a mandatoryStartTool, a mandatoryEndTool, revision/step caps, and an assembleResult callback; the runner handles the tool-loop, SSE events, revision bookkeeping, partial-state fallback, and the shared stopWhen: [hasToolCall(end), stepCountIs(cap)] invariant. Distilled from Brandling's marketing-domain runDebateAgentic (council-foreman.ts:41).

Hello world

import { createGateway } from './gateway';
import { defineRegistry } from './models-registry';
import { runCouncil } from './council-state-machine';
import { withProvenance, type Provenanced } from './provenance';
import type { AgentSseEvent } from './events';
import { z } from 'zod';

// 1. Wire the gateway once.
const gateway = createGateway({
  baseURL: process.env.GATEWAY_BASE_URL!,
  apiKey: process.env.GATEWAY_API_KEY!,
});

// 2. Register the roles.
const MODELS = defineRegistry({
  foreman: { model: gateway('anthropic/claude-opus-4.7') },
  cfo: { model: gateway('anthropic/claude-sonnet-4.6') },
  auditor: {
…

Design constraints (read these before extending)

These are lifted from Brandling Appendix A. They override convenience.