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 at agents.openeng.app; select them into a config, publish, and activate them by name on any machine.

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).

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, 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 as the agent's blueprint, picked from your own templates or the catalog (authored ahead — see What's 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:

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

Per-role bindings — override the model per role for this agent, across the eleven model roles (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 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, 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).

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 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), 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).

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.