# The agent builder

> An agent that builds agents: describe what you want in a conversation, watch it take shape on a page, test it live, and hand the finished draft to an admin to install.

Source: https://openap.org/docs/agent-builder

The agent builder is an OAP agent whose job is to build *other* agents. You describe what you want in
plain words; it interviews you, finds and connects the tools the job needs, settles what the new agent may do
on its own and what it must ask about, builds it, and lets you **test it live** — all on one page,
in one conversation. What you get at the end is a saved, portable copy of the agent, and the option to have a
platform admin install it for real.

[Video: One build, end to end: describe the agent, answer its questions, approve the stage once, test it live on the page, and keep the draft.](https://openap.org/media/builder-first-agent.mp4)

## What it is, and what it is not

The builder is itself an ordinary agent — an `AgentClass` named `agent-builder`, installed by `oap install` when you
name who may start it. It runs under the same guardrails as everything else here: a plan it must declare, stages you
approve, tools it calls through the platform, an audit trail. What makes it different is where it works and what
it produces.

- **It works in a workshop.** Every build runs inside its own isolated space, created for that session and torn
  down when the session ends. The draft agent lives there, is tested there, and never touches the cluster's other
  agents until an admin installs it.
- **It produces a draft, not a deployment.** The output of a build is a `.oap` bundle — the same portable format
  every agent here ships as. You keep it. Nothing runs anywhere until someone with the right to install agents
  says so.
- **It never asks you for a key.** The platform connects accounts itself: your own accounts through your
  accounts page, a shared account through a secure card the builder sends. If an agent would need a credential
  the builder cannot arrange, it says so and stops.

## The six stages

The workshop page shows a timeline of six stages. The builder moves through them in order and paints the page
as it goes, so you always see where it is and what has been settled.

| Stage | What happens |
| --- | --- |
| **Intake** | You describe the agent in your own words. The builder restates what it understood, records what is settled, and asks one clarifying question at a time. |
| **Tools** | For each service the job needs, it finds the least-code way to reach it — a connector the cluster already offers first — validates it, and tries it. |
| **Permissions** | A plain-language interview: what the agent may do on its own, what it must ask about first, what it can never do. The page keeps a "will / will ask / won't" summary. |
| **Build** | It composes the agent from everything gathered, applies it, and keeps fixing it until the platform reports it valid. |
| **Test** | You start a real session of the new agent, embedded on the page, and the builder watches what it actually does — its tool calls and results, not its prose. |
| **Deliver** | It saves a portable copy of exactly what you tested, and offers to install it for real. |

Each stage that changes the draft is something you approve **once**, on a card the builder raises before it
starts. Every change inside that stage then runs without another card; a stage the builder never planned for
raises a fresh one. The details are in [Your first custom agent](https://openap.org/docs/agent-builder-first-agent).

## Who can use it

Access is set when the builder is installed: `oap install --builder-starters` names the people and groups who
may start it. Anyone else does not see it in the session picker at all. See
[Turn on the agent builder](https://openap.org/docs/agent-builder-install).

A person may have a small number of workshops open at once — three by default. Starting a fourth is refused
with the list of the ones still open and a way out: open one of them and ask it to close the others. A finished
build releases its workshop on its own. See [Workshops and limits](https://openap.org/docs/agent-builder-workshops).

## What an admin sees

"Install for real" does not install anything. It records a request that a platform admin reviews in the
[admin console](https://openap.org/docs/admin-dashboard): the suggested name, who asked, and the draft as tested. The admin installs it
into the namespace it belongs in, or declines it, and the person is told either way. The saved draft is the
person's regardless — they can hand it to someone else, or ask again later.

> **Security: Why it is built this way**
>
> The builder has broad reach inside its workshop and none outside it. Its tools are keyed on the draft it is
> building, so an approval covers that draft and nothing else; the workshop is namespaced away from everything
> running for real; and the one action that crosses that line — installing — is a separate permission held by
> admins, decided in the console, never by the builder. Testing runs the new agent as a real session under the
> same guards as any other, so what you watch in the test is what would happen after install.

## In this section

- **[Turn on the agent builder](https://openap.org/docs/agent-builder-install)** — the one `oap install` flag, and how to find your
  identity.
- **[Your first custom agent](https://openap.org/docs/agent-builder-first-agent)** — a full build, stage by stage, with the page as
  it changes.
- **[Testing, delivery, and install](https://openap.org/docs/agent-builder-deliver)** — what the test card tells you, what the saved
  draft is, and how an admin installs it.
- **[Workshops and limits](https://openap.org/docs/agent-builder-workshops)** — the per-person limit, closing workshops, and what
  releases one.
