Buildouts

What is a buildout?

A buildout is a versioned bundle of three things:

• A manifest — the static declaration of tools, retrieval sources, approval policies, and metadata.
• An agent body — the planning loop, prompts, and any custom step handlers that make decisions at runtime.
• An eval suite — the deterministic test cases that gate every promotion. A version cannot leave QA without clearing the suite’s threshold.

The planner UI

Authoring starts at /dashboard/buildouts/new, a guided form that walks through each section of the manifest and validates input before letting you continue. Once the buildout exists, the planner board at /dashboard/buildouts shows every version moving through a four-stage pipeline: Planning → Building → QA → Publishing. Each card surfaces the owner, the current state, and timestamps for the most recent transitions.

Step types

The runtime supports a small, composable set of step types so most logic stays declarative:

• llm — call a model with a prompt and (optionally) tool schemas.
• tool — invoke a registered tool, gated by the agent’s approval policy.
• retrieval — fetch chunks from a knowledge source, citation-tagged.
• checkpoint — persist the workflow’s state so a crash or pause can resume cleanly. See /docs/workflows.
• human — pause for a named human (e.g. an approver) with a hash-pinned preview.

Tools and schemas

Every tool declares a Zod schema for its arguments and its return value. The dispatcher validates both at runtime and short-circuits the call with a structured error when either side fails the schema. Schemas double as the public contract the model sees.

// src/agents/sales-followup/tools.ts
import { z } from "zod";
import { tool } from "@/lib/agents/tools";

export const sendFollowup = tool({
  name: "sales.send_followup",
  description: "Email a follow-up to a stalled deal contact.",
  args: z.object({
    contact_id: z.string(),
    template: z.enum(["check_in", "deck_share", "deal_review"]),
  }),
  result: z.object({ message_id: z.string() }),
  policy: "approve",
});

Eval-gated promotion

Each buildout ships with an eval suite — a YAML or TypeScript bundle of named test cases, each with inputs and expected outputs (or scoring rubrics). The build stage runs the suite; QA refuses to advance a version whose pass rate falls below the threshold declared on the buildout. Promotion to publishing requires clearing the release-gate panel — which inspects the eval results, the diff against the prior version, and any open audit findings.

Quick start

1. Open /dashboard/buildouts/new and create the manifest.
2. Author the agent body in the editor or import a template.
3. Add at least three eval cases — happy path, edge case, abuse case.
4. Click Build; the pipeline moves to QA when the build succeeds.
5. Review eval results, click Promote to publishing, and the buildout is available to install in your workspace (or, if you opt in, the public marketplace).