# Agents

> An agent is a reusable persona: a system prompt, optionally its own model, plus delegation wiring, caps, and tool grants. Author agents on the Console's Agents page (Building blocks → Agents) or adopt them from the public catalog, select them into a config, and run a message as an agent by name. As of September 25, 2026, OpenEng AI isn't live yet.

An **agent** is a reusable persona: a system prompt, optionally its own
model, plus delegation wiring, caps, and tool grants. Author agents on the
Console's **Agents** page (Building blocks → Agents), or adopt them from the public catalog at
[agents.openeng.app](https://agents.openeng.app); select them into a config, publish, and activate
them by name on any machine.

> [!WARNING] Status on September 25, 2026: OpenEng AI isn't live yet
> The Console and Web Console interfaces load, but the OpenEng AI API routes and the Broker aren't
> deployed. Nothing can be saved or published, and no AI engine can register or connect. Pro,
> Enterprise and pay-as-you-go launch in Q4 2026 and can't be purchased yet. This page describes
> OpenEng AI as it works once those services are live ([status](ai.md)).

*Figure: Building blocks → Agents — the Mine and Catalog tabs; your agents open in the full-page editor with its explicit Save.*

## What it is, and when to use it

Agents turn "re-explain what I want every time" into "say its name." Define
one when you keep re-typing the same setup — a reviewer with a strict
checklist, a backend coder with your conventions, a note-taker. The list page
has two tabs:

- **Mine** shows every agent you own with its model, delegator count and grants summary; rows
  open the full-page editor, and each carries **Edit** and **Delete** actions (delete asks first;
  config versions you already published keep their frozen copy). **New agent** starts a blank one.
- **Catalog** browses the shipped agents: **1,092** as of September 25, 2026, 810 single agents and
  282 orchestrators. **Use** copies an agent into Mine as-is; **Customize** opens it in the editor
  to change before you save. Adopting an orchestrator copies it together with every sub-agent in
  its tree.

Configs don't create agents: a config's **Agents** step only selects from yours (see
[Using agents](#using-agents)).

### Single agents and orchestrators

Every catalog agent is a packaged operating brief (a system prompt plus a method), and comes in two
kinds:

- **Single** — a direct worker that does one focused job, such as checking pod health across a
  namespace.
- **Orchestrator** — plans a task, **delegates to sub-agents**, then synthesizes their results.
  Its level says how deep it goes: level 1 orchestrates single agents, and level 2 and up
  orchestrate other orchestrators. For example, the Kubernetes Inspector delegates to agents that
  check pod health, scan logs and review CPU and memory, and a level-2 Kubernetes Full Cluster Audit
  orchestrates the Inspector together with a security auditor and a cost optimizer.

A catalog agent's id is `agent_def_<slug>`, and its brief is published at
`https://agents.openeng.app/<slug>.md`, which is what the engine reads for it. Agents you own have
`agt_usr_…` ids.

## The agent editor, section by section

The editor saves **explicitly**: the header's **Save** button is the only
path to the server, disabled with the reason while the document is invalid
(an empty system prompt) or unchanged, with a toast on the result. Edits
mirror to the browser's local draft as you type — "Restore unsaved draft?"
on reopen — and a failed save keeps them. Background help (what the engine reads, and isolation)
sits behind the ⓘ in the header.

**Identity & prompt**

- **Name** — how you'll activate it; also the engine's lookup
  key.
- **Description** — for humans.
- **System prompt** — the persona, in a monospace editor with a live token
  estimate. This field is **required to save**: the engine silently drops an
  agent without a system prompt, so the editor refuses to let one through.

**Model binding** — one model from your [catalog](models.md), picked **by
name** from a dropdown listing every entry. This is the binding the engine
consumes today; leave it empty to use the role defaults.

**Template attachment** — attach a [template](templates.md) as the agent's
blueprint, picked from your own templates or the catalog (authored ahead — see
[What's real today](#the-preview-rail-whats-real-today)).

**Attachments** — files delivered with the agent into the engine's context, each up to 10 MB.
Only their metadata is stored with the agent and frozen into a published config.

**Delegator tree** — build the agent's delegation hierarchy interactively:
children are its delegators; grandchildren resolve from your other agents.
The picker is **cycle-proof** — it disables the agent itself and any
candidate whose own delegation already reaches back to this agent — and the
tree renders up to 6 levels deep. A typical shape:

```text
architect      (plans, delegates)
├── backend    (writes server code)
├── frontend   (writes UI code)
└── reviewer   (reads everything, reports problems)
```

> **Note:** The tree wears an honesty badge: today's engine runs agents without
> the delegator wiring (it's authored ahead and publishes with your config).
> Delegation *behavior* in autonomous runs comes from the engine's own agent
> loop.

**Per-role bindings** — override the model per role for this agent, across the eleven
[model roles](models.md#role-models) (`planner`, `agent`,
`reviewer` and the rest), with each role showing what it inherits from your account defaults on
**Govern → Defaults** when you leave it alone. That inherited value is display-only: the defaults
don't reach the engine, so an unbound role uses the config's binding. The dropdowns list your **entire catalog by name**
and store the stable id; `(unknown)` appears only for an id that no
longer exists.

**Iteration & token caps** — `Max iterations` and `Max tokens` for runs under this agent. Leave
them blank to inherit the config's resource caps.

**Tool grants** — pickers for MCP servers, cells (each marked read or write), and worker patterns
(e.g. `fs:*`, `shell:git-*`) this agent may use.

**What a planning request will contain** — a collapsible, read-only preview at the foot of the page
that shows the composed agent in the order the engine assembles it: attached template, system
prompt, model, delegators and tool grants.

## What's real today

The editor is honest about what the engine uses. Sections the engine doesn't read yet carry a
**"Not yet consumed by the engine"** badge, and the fields it does read carry **"Consumed by the
engine"**:

- **Consumed by the engine today:** name/id, system prompt, description, and the
  single model binding.
- **Authored ahead:** template attachment, delegator tree, per-role bindings,
  caps, tool grants — stored and published now; they take effect as engine
  support lands.

This split is deliberate: the Console never silently promises behavior the
runtime doesn't have yet.

## Using agents

1. Select the agent in the config's **Agents** step, which lists only your own agents. The step
   appears when the config's [execution flow](execution-flow.md) lets the agent spawn sub-agents or
   delegators (and always for a config with no authored flow).
2. Publish the config.
3. In the Web Console at [app.openeng.app](https://app.openeng.app), run a message as the agent:
   type `/agent <name>` before the message (the composer suggests the agents in the running
   config), or tick it in the component selector beside the composer.

The agent's system prompt then **replaces** the base system prompt for that message. Scoping a
message to more than one agent is allowed: the first one runs, and the others are added as context
it can delegate to. Scopes combine with templates and skills, for example
`/agent reviewer /template tpl_def_system-design review this design`. A name the engine can't
resolve shows a one-line notice, and the message runs without it.

For quick personal agents on one machine, a Markdown file in `~/.openeng/agents/<name>.md`
(YAML front matter with the `name`, `description` and `model`, then the prompt as the body) still
works: the engine's agent loop can hand a sub-task to a local agent by name. The folder moves with
`OPENENG_AGENTS_DIR`.

## Resource governance

Everything a run does — the agent, the agents it delegates to, and every sub-agent it spawns —
shares **one collective budget**, never a budget per agent. The budget comes from the config's
**Resources** step (CPU, GPU, memory and storage, 10% of the machine each by default). Agents queue
for a slot when the budget is in use rather than oversubscribing the machine, and the depth and
iteration limits guard against runaway loops.

## Plan & tier notes

Agents are open on **every plan** — authoring, adopting, publishing, and selecting them into
configs. The number of agents is not metered. Running them needs the `openeng` engine, which starts
only on an active Pro plan; some features an agent might lean on carry their own plan gates (see
[Plans & billing](account.md)).

## Troubleshooting

**My agent never shows up.** Three usual causes: the system prompt
was empty (the editor blocks saving — check the agent actually saved), the agent isn't selected in
the config the machine serves, or the session is still on an older version of the config (pick the
new version in the Web Console, or restart the engine if you rely on its default config).

**The agent runs but ignores its delegators.** Expected today — delegation
wiring is authored ahead (see [What's real today](#the-preview-rail-whats-real-today)). The agent's
prompt and model binding are what the engine consumes now.

**Activating an agent by name says not found, but the Console shows it.** Names are the
lookup key — check for a rename, and confirm the agent is selected in the
config this machine resolves: open that config and pick the agent in its Agents step
([Configs](configs.md)), then publish.

**The config has no Agents step.** The config's execution flow doesn't let the agent spawn
sub-agents or delegators, so there's nothing for the step to do. Turn on sub-agents or the delegator
on the flow's agent stage ([Execution flow](execution-flow.md#the-stages)).

**Saving fails with a plan message.** Agents themselves aren't metered;
the message will name the real gated domain (e.g. a scheduler you attached
elsewhere). The server's message carries the true used/limit figures.