Academy · Reference
Agent-builder field reference
This reference enumerates every field in the agent editor, tab by tab — for both the current tabbed builder and the legacy single-page editor it replaced. The concepts behind the fields (what each tab is for, how to build a working agent) are taught in Your first agent; come here when you need the exact name, type, range, or behavior of a control. Both layouts read and write the same agent object — the field names below are identical, only the arrangement differs. Save is always explicit (a Save Agent button, never autosave) and is disabled while the form is invalid.
Which layout am I looking at?
The editor renders one of two layouts, switched by the newAgentBuilder flag.
| Layout | Shown when | Shape |
|---|---|---|
| New tabbed builder (default) | newAgentBuilder ON — the shipped default |
8-tab builder pane + a split Playground pane. data-testid="agent-builder-new-shell". |
| Legacy single-page editor | newAgentBuilder OFF, or URL ?newBuilder=0 |
One scrolling 30% form on the left + 70% playground on the right. data-testid="agent-builder-legacy". |
Flag-gated (override). You can force a layout for one browser session with the URL query
?newBuilder=1(new) or?newBuilder=0(legacy). This is per-session and overrides the baked default. The separateagentHarnessflag changes only the Agents right-pane (the view-equals-edit mirror), not this editor — see Your first agent.
The current tabbed builder
The builder pane carries an 8-tab strip. Each tab below lists every form control, what it does, and what a builder should put there.
Tab 1 — Persona
Who the agent is and what it does, in plain language.
| Field | Type | What it does / what to put |
|---|---|---|
| Name | text (required) | The agent’s display name across Studio and lists. Keep it task-named: “Invoice Extractor”. |
| Description | textarea | One or two lines a teammate can scan. Surfaces in the Agents list row. |
| Instructions | 14-row textarea (required) | The system prompt / persona — the heart of the agent. Says who it is, what to do, how to behave, what to return. Supports global-variable placeholders {{scope.X}}. |
| Field co-pilot | inline button on Instructions | Type a one-line seed (“extract invoice fields and flag overdue ones”) and it expands a fuller draft you then edit. |
Tab 2 — Model
Which LLM powers the agent and how it reasons.
| Field | Type | What it does / what to put |
|---|---|---|
| LLM Model | multi-select | One or more of the project’s registered models. Multiple selections form a failover pool. |
| Agent Mode | select | Auto / Fast / Thinking. Auto is the first, default-selectable option — the agent routes per question (Fast for simple lookups, Thinking for analysis); routing is still maturing, so pick Fast or Thinking explicitly for predictable behavior. Fast = single-pass, low latency; Thinking = multi-step reasoning before answering. |
| Enable thinking budget | toggle | Caps how much reasoning the model may spend (Thinking mode). |
| Thinking budget | slider (−1 to 24576) | Token budget for reasoning. −1 = uncapped / model default; higher = more deliberation, more cost and latency. |
| Advanced sampling (expander) | — | Tune output randomness — leave default unless you have a reason. |
| ↳ Temperature | slider (0–2) | Higher = more varied wording. For extraction, keep low (0–0.3). |
| ↳ Top P | slider | Nucleus sampling cap. |
| ↳ Max tokens | number (0–4000) | Hard cap on answer length. |
| ↳ Frequency penalty | slider (−2 to 2) | Discourages repeated tokens. |
| ↳ Presence penalty | slider (−2 to 2) | Discourages repeating topics. |
| ↳ Seed | number | Fix for reproducible outputs while testing. |
Tab 3 — Knowledge
What the agent is allowed to read. Three source sub-tabs.
| Sub-tab / field | Type | What it does / what to put |
|---|---|---|
| Views ▸ View | select | A saved, filtered slice of a collection the agent may query. |
| Views ▸ Filter by view | toggle | Restrict the agent to only the documents inside that View. |
| Datasheets ▸ Datasheet | select | A SQL table the agent may query. |
| Knowledge collections ▸ select | multi-select (flag-gated) | Attach Knowledge-corpus collections (writes KnowledgeCollectionIdsStr). Shows the attached list and a readiness dot per collection. Visible only with the knowledgeCollections flag. |
| Knowledge lock | toggle | The agent answers only from attached knowledge — no general world knowledge. |
| Exact-match lock | toggle | Forces exact-match retrieval rather than semantic similarity. |
Tab 4 — Capabilities
What the agent can do — its tools, MCP connections, and skills.
| Section / field | What it does / what to put |
|---|---|
| Tools — + Add tool | Opens the tool picker; selected tools render as cards (remove per card). A tool is a callable: SQL search, a retriever, a custom API. |
| MCP servers — + Add MCP server | Menu of registered MCP servers (each tagged with a scope badge — From Environment / From Subscription). Cards show the connection. |
| Skill Packs — + Pin pack | Pin a reusable skill bundle. Cards show “Pack”, N skills, scope badge. |
| Skills — + Pin skill | Pin individual skills. Cards show a Pinned badge, the runtime, and an “also in pack X” collision badge if a pinned skill is already in a pinned pack. |
| Restrict this agent to pinned skills only | Checkbox. When on, the agent may use only pinned skills — it ignores otherwise-discoverable in-scope skills. |
| Ghost list | A faint list of auto-discoverable in-scope skills, each with a Pin button — promote a discovered skill to a pinned one. |
Tab 5 — Output
The shape of what the agent returns. Five mode cards at the top (toggles).
| Field | Type | What it does / what to put |
|---|---|---|
| Table output | mode toggle | Return rows/columns rather than prose. |
| Standardization | mode toggle | Normalize values to a canonical form (single-agent only). |
| Structured output | mode toggle (permission-gated) | Extract typed fields against a schema — turns on the sub-form below. This is the invoice/extraction mode. See Schema for building the schema itself. |
| Section classification | mode toggle | Classify each section of the document. |
| Auto-annotate document | mode toggle | Write extracted values back as annotations on the source document. |
Taxonomy / Learner (LearnerId) |
searchable select | (Structured) the schema whose Labels/Fields the agent fills. |
| Without Hierarchy / Select All labels | checkboxes | (Structured) shortcuts for flat schemas / extracting every label. |
| Process unit | segmented (Page / Section / Image) | (Structured) the chunk the agent reasons over at a time. |
| Merge pages | toggle | (Structured) treat multi-page docs as one unit. |
| Images per batch / Parallel batches | numbers | (Structured, image unit) throughput controls. |
| Send text with images | toggle | (Structured, image unit) include OCR text alongside page images. |
| Quality check agent | toggle + instructions | (Structured) a second pass that QC-checks the extraction. |
| Labels list — Add / Add all | rows | (Structured) per-field rows: Label select + Description (the per-field instruction that most improves accuracy). |
| Enable Reasoning / Confidence Score / References | toggles | (Structured) return the why, a 0–1 confidence per field, and source citations. Confidence drives “needs review” routing. |
Limit rows (NoOfRows) |
number | Cap rows returned (table/structured). |
| Use download filename | toggle | Name exports from the source filename. |
Tab 6 — Governance
The rules the agent must obey, and where a human signs off.
| Section / field | What it does / what to put |
|---|---|
| Guard rails — + Add | Attach named policy objects (chips, removable). |
| Approvals ▸ Tools (n) | Per-tool rows: approval state (Approval required / Auto), a settings icon to tune the HITL prompt (type Form / Multi-Select + approval-card text), and an enable toggle. |
| Approvals ▸ Team agents (n) | Per-member approval toggle. Disabled unless the agent has team members (Subagents tab). |
Tab 7 — Context (Context Kernel)
Fine control over what context gets assembled into each prompt. Advanced — the Profile template default is fine for most agents.
| Section / field | What it does / what to put |
|---|---|
| Profile template | A named context recipe; editing any field flips it to “Custom”. |
| Sources table | Per provider: On checkbox, Source, Tier (1/2/3), Priority (0–100). Tier-1 sources are spent first. |
| Variables allowed | Scope chips (checkboxes) — which {{scope.X}} variables the agent may read. |
| Token budgets | Per-tier token caps (Tier 1/2/3 number inputs). |
| Truncation | Strategy (auto / last_messages / summary_compact), Max prompt tokens, Recent turns kept, History rows fetched, Summariser model (when summary_compact). |
| Preview — Run preview | Renders the final assembled instructions, spend-by-tier, and which blocks were kept or dropped — before you ever run the agent. |
Tab 8 — Subagents
Turning this agent into a team coordinator that delegates to member agents.
| Section / field | What it does / what to put |
|---|---|
| Coordination mode | Select (shown when at least one subagent exists) — how the leader sequences members. |
Subagents list (AgentTeams form array) — + Add subagent |
Per row: Agent select (team-tagged agents), Prefix instructions textarea (member-specific guidance), Reasoning toggle, remove. |
| Empty state | No subagents = a normal single agent. Adding the first subagent makes it a coordinator. |
Save footer, persistence, and keyboard
- Save Agent — disabled when the form is invalid; shows “Saving…” while in flight. No autosave.
- Active tab and pane-collapse states persist in
localStorage(agent-builder.activeTab,.playgroundState,.builderState). - *Ctrl/Cmd + * toggles the Playground pane; *Ctrl/Cmd + Shift + * toggles the builder pane (never both collapsed at once).
The shared Playground pane
A two-tab group — Playground | Task & metrics — identical in both layouts.
Playground tab
| Control | What it does |
|---|---|
| Chat transcript | Markdown answers, tables, charts, thinking blocks, tool-attachment download links. |
| HITL approval panels | When a tool/step needs sign-off: Reject / Review (leave feedback) / Approve & Execute. |
| Input Type radios | Text / Document / Project — what the agent runs against. |
| Agent Mode menu (legacy playground only) | Fast / Thinking — override per run while testing. The new-builder playground pane has no mode control; set the mode on the Model tab instead. |
| Enable Chat History | Toggle — carry prior turns into context. |
| Document picker / Page Numbers | (Document input) pick a doc and optional page range. |
| Attachment (+) | Attach photos and files inline. |
| Question textarea | Your prompt. Enter to send. |
| Send | Runs the agent and streams the answer. |
Task & metrics tab
| Section | What it does |
|---|---|
| Input & Output Formats (accordion) | Sample Input + Sample Output + Validate (checks the output conforms). |
| Evaluation Rule Setup | Freeze Task & Metrics toggle; Task select + Auto-Detect (analyses your agent and proposes a task); Metrics grouped Primary / Optional / Irrelevant checkboxes with descriptions. Feeds the Evaluation surface. |
The legacy single-page editor (newAgentBuilder OFF)
Same object, one scrolling left-hand form (about 30%) + the playground (about 70%). Field order, top to bottom:
| Field / section | Notes (maps to which new tab) |
|---|---|
| Name (required), Description | → Persona |
Select the LLM Model (LlmModel, multi-select) |
→ Model |
(Multi-agent) Mode select + Agent Team (AgentTeams form array) |
→ Subagents. Each row: Reasoning toggle, optional Human-approval card (approval-card text via the settings icon), Agent dropdown (grouped Agents / Multi Agents), Prefix textarea, add/remove. |
Instructions (expandable, required, {{scope.X}} menu) |
→ Persona |
| Tools Configuration — Add Tools | → Capabilities. Selected tools = cards with a per-tool HITL/approval control. |
| Guard Rails Configuration — + Add (permission-gated) | → Governance. Shield chips, dashed empty state. |
| MCP Servers — Add MCP Server | → Capabilities. Cards show status dot, URL/command, transport + scope badges. |
| Knowledge Base Configuration (tabs Views / Datasheet) | → Knowledge. Hidden when structured-output / multi-agent / standardization. |
| Toggles: Filter By View, Table Output, Standardization (single), Structured Output (permission-gated) | → Knowledge / Output |
| Structured Output sub-form | → Output. Taxonomy (LearnerId), Without Hierarchy / Select All, LabelList (Label + Description), Process Unit (Page/Section/Image) + Merge Pages, Images per batch / Parallel batches + Quality Check button, Send Text With Images, Enable Reasoning / Confidence Score / References, Section Classification Agent toggle. |
| Knowledge Lock / Exact Match Lock toggles | → Knowledge |
Advanced Settings accordion (AdvancedConfig) |
→ Model. Temperature (0–0.9), Maximum Length (0–4000), Top P, Frequency/Presence Penalty (−2 to 2), Relevant Docs / Number of Shards (standardization), Seed, Limit rows (NoOfRows), Use download filename, Update Index, Enable Thinking Budget + Thinking Budget slider (−1 to 24576). |
| Save Agent (sticky, permission-gated, disabled when invalid) | Footer. |
Watch out. The legacy form caps Temperature at 0–0.9; the new builder’s Advanced sampling allows 0–2. Same underlying field — the new UI just exposes the wider range.
HITL approvals — one dialog, two homes
Human-in-the-loop approvals are configured by the same approval-card dialog in two places: the legacy per-tool cards and the new Governance ▸ Approvals tab. Either way you set: Request approval (enable), Approval type (Form / Multi-Select), and the Approval card text the reviewer sees. At run time the agent pauses at that step and surfaces a Reject / Review / Approve & Execute panel in the Playground (and in the live consumer run).
botHelpInfo anchor codes
Nearly every field carries a stable botHelpInfo code (e.g. ABA01, ABT04, AB003) used for in-app help. They make durable cross-references; if a label is renamed in a release, the code is the stable identifier.
Prefer learning inside the product? The same academy lives in the platform's Learn menu — every screen links to the chapter that explains it.
See the platform live