Skip to main content

Agent Builder

Agent Builder is the editor for designing or modifying an agent. You can build one from scratch, fork an existing platform agent to customize it, or open one already bound to a System hook to tune it for your workspace. Everything you change here gets versioned, so trying things is cheap.

📷 Screenshot: Agent Builder with an agent loaded — header dropdowns on top, steps list expanded below.

Picking an agent​

The header at the top of the tab has three dropdowns and an action menu:

  • Category — narrow the agent dropdown by category (Chat / Code / Documents / Email / etc.).
  • Agent — pick an agent to edit. The list shows root (platform-shipped) agents plus any workspace-custom agents you've created. The + option creates a fresh agent.
  • Version — every save creates a new version. The dropdown lets you flip between versions (and the small menu next to it lets you duplicate or delete a version).

Two action buttons on the right:

  • Optimize — opens the optimization-run modal. Optimization runs evaluate variants of the agent's prompts against test inputs and surface which variants performed best, so you can promote a tuned version without hand-iterating.
  • Publish — open the leaderboard / publish modal to push the agent to the public marketplace so other workspaces can fork it.

The header collapses into a thin bar once you scroll into the steps; click the divider's chevron to bring it back.

Anatomy of an agent​

An agent is composed of a small handful of pieces. The Configuration accordion at the top covers the cross-cutting bits, and the Steps list below it is where the actual work happens.

Configuration accordion​

Inside, four tabs:

  • Constants — fixed values reused across the agent (model name, target repo, default cwd, anything you don't want to type repeatedly).
  • Parameters — typed inputs the agent collects before it starts running. These are the questions the platform asks the user (or the calling agent, if this one is a sub-agent) right before kickoff.
  • Export Map — named outputs the agent produces. Other agents in a chain can read these by name without knowing where in this agent's run they were generated.
  • Settings — agent-level settings (default model, max iterations, what happens on failure, whether to write to the chat / execution log, etc.).

The header of the agent (above the configuration) also exposes the agent's display name, version metadata (created at, by whom, what changed), and a description field.

Steps and actions​

Below the configuration, the Steps and actions list is the agent's actual workflow.

  • Steps are the ordered phases the agent moves through. Each step has a name, an iterator (some steps loop over a list), and a body of actions.
  • Actions are the work each step performs. They come from the Available Actions library — file lookups, code grep, terminal commands, AI completions with structured output, document edits, sub-agent calls, branches and conditions, web search, image generation, and more. Drag an action from the library into a step to add it.

Each action card exposes its inputs (which can reference parameters, constants, prior action outputs, or the export map of a sub-agent), and its output schema (which defines what the next action can read).

Reordering is drag-and-drop:

  • Drag a step's handle to reorder steps.
  • Drag an action's handle to reorder actions within a step, or to move an action between steps.

Drag is disabled while any action has unsaved changes, so you don't accidentally lose edits while reorganizing.

Versioning​

Every save creates a new version of the agent — the previous version stays intact. The version dropdown in the header lets you flip between them, and the Duplicate Version menu item is the right way to spike a risky change: duplicate, edit on the duplicate, test it, and only swap which version is active once you're happy.

Deleting a version is hard-delete; if the version is currently bound to a System Agent hook or a Schedule, the binding falls back to the agent's primary version automatically.

Testing without saving​

The Test button (bottom right of the steps list) opens the test modal. Pick (or paste) sample parameter values, run the current draft against them, and watch the agent execute step-by-step in a sandbox. Test runs don't write to your workspace's chat, don't create execution-log entries on the agent's history, and don't get billed against your credit balance — they're cheap iteration.

When a test succeeds, the Save as new version button at the top of the test results commits the draft as a new version with the test inputs attached as a fixture for later regression checks.

Optimization runs​

Optimization is the systematic version of test. Define a set of evaluation inputs (with expected outputs or graders), pick which prompt(s) you want to vary, and run dozens of variants in parallel; the platform reports which variant performed best on each evaluation row and which had the best aggregate score. Useful when you've hit "this is fine" with hand-iteration and want to find the prompt the model actually likes.

Optimization results live on the agent's Leaderboard (the same modal as Publish), where you can see prior runs, compare variants, and promote a winner.