Your first agent

In one line. The Agents page and the agent editor, end to end: every tab, the playground, and how to wire an agent to a Collection so it actually does work. You’ll be able to. Build a real, working agent from a blank form, test it live in the playground, and hand it a collection of documents to process. Where this lives. Studio ▸ Agent Builder ▸ Agents — route /studio/.../agent_builder/agents

Why it matters

An agent is the unit of work on this platform: a configured AI worker you assemble from plain-language instructions, a model, some knowledge, a few tools, and the rules it must obey. You don’t program it; you describe it. Everything else in this pillar (tools, skills, MCP, guard rails, teams, pipelines) is just deepening one of the tabs you’ll meet here. Learn this surface well and the rest is detail.

We’ll do three things: tour the Agents page, build an agent tab by tab, and test it in the playground, then point it at a Collection so it starts processing documents.

Under the hood. The Agents page is unified: it lists single Agents, Multi-Agent teams, XFlows, and Meshes in one gallery. They’re different kinds of “runnable”, but you find and open all of them here. This page focuses on the single Agent; teams and meshes get Teams & mesh, pipelines get XFlows & pipelines.

The Agents page

┌─ Studio ▸ Agent Builder ▸ Agents ───────────────────────────────────────────────────────────┐
│ ┌─ L2 LIST (left) ──────────────────────┐ │ ┌─ DETAIL / RUN PANE (right) ─────────────────┐ │
│ │ Agents          [Kind ▾] [↕] [search] │ │ │  (selected agent)                  [ ⋮ ]    │ │
│ │  Kind: All / Agent / Multi-Agent /    │ │ │  ┌ Persona Model Knowledge Capabilities … ┐ │ │
│ │        XFlow / Mesh                   │ │ │  │  read-only projection of each tab      │ │ │
│ │ ───────────────────────────────────── │ │ │  └─────────────────────────────────────────┘ │ │
│ │ [A] Invoice Extractor      V3 ▾       │ │ │  [ Playground | Runs | Evaluation ]          │ │
│ │     extracts + flags overdue …        │ │ │  ┌─────────────────────────────────────────┐ │ │
│ │     ▸ 2 Past Versions                 │ │ │  │  chat with the agent, see tool calls,   │ │ │
│ │ [A] Policy Q&A             V1         │ │ │  │  metrics, HITL approval cards …         │ │ │
│ │ [X] Nightly Filings Pipeline          │ │ │  └─────────────────────────────────────────┘ │ │
│ │ [M] Claims Mesh                       │ │ │                                              │ │
│ │ ───────────────────────────────────── │ │ │                                              │ │
│ │                        [ + Agent ▾ ]  │ │ │                                              │ │
│ └───────────────────────────────────────┘ │ └──────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────────────────────────────┘

The left L2 list is the gallery; the right pane shows whichever item you select. Click an agent and the right pane shows its config tabs plus a live Playground; click an XFlow or Mesh and the right pane swaps to the embedded pipeline designer instead.

What every control does

Control	What it does	Notes
Kind filter (`mat-select`)	Filters the list to All / Agent / Multi-Agent / XFlow / Mesh	“Agent” is the default unit of work.
Sort toggle (↕)	Cycles latest → A-Z → Z-A
Kind badge (left of each row)	A = agent or team, X = xflow, M = mesh	Hover for the full kind.
Version chip (`V3 ▾`)	A dropdown of the agent’s saved versions (V1, V2 … plus “Load more…”, paged 10)	Only appears once an agent has more than one version.
“N Past Versions” expander	Lazily loads and lists prior versions as clickable rows	A spinner shows while it fetches.
+ Agent (footer ▾)	The create picker: Agent / XFlow / Mesh	Permission-gated.
Row ⋮ menu	Publish / Edit / Delete / Import (from Hub)	See below.
Load More	Appears only when the project has ≥ 1000 items

Tip. The list auto-selects the first Agent when the page loads, so you usually land straight in a working agent. The moment you click a row yourself, that choice sticks; a late server refresh can’t yank you elsewhere.

+ Agent opens the create picker: Agent (a single AI worker, opens the editor below), XFlow (a visual pipeline, XFlows & pipelines), or Mesh (a durable multi-stage pipeline, Teams & mesh).

Row action	What it does	Notes
Publish	Pushes the agent to a Hub so other projects can install it	Hubs & solutions.
Edit	Opens the agent editor in edit mode	Permission Edit Agent / Edit Multi Agent.
Delete (red)	Confirm dialog, then removes the agent	Permission-gated. Destructive.
Import	Brings an agent in from a Hub

Behaviours to know

Live sync. The list re-fetches in place when anyone (a teammate, another tab, an automation) creates, edits, or deletes an agent; you see a small change toast. (Flag realtimeResourceSync.)
Deep links. Selecting a row rewrites the URL to agents/:kind/:id; that link is shareable and bookmarkable. The Collection workspace’s “Open in Agent Builder” button lands you here.

Flag-gated (the right pane). When the agentHarness flag is on (the shipped default), the right pane is the Agent Harness: a “view = edit” mirror of the builder with read-only Persona / Model / Knowledge / Capabilities / Output / Governance / Context / Team tabs (each with an edit control that jumps into the real editor), plus operational Playground / Runs / Evaluation tabs. With the flag off, the right pane is the older three-tab view (Details / Runs / Evaluation). Either way, + Agent and Edit open the same editor described next.

Building an agent — the editor, tab by tab

Click + Agent ▸ Agent (or Edit on a row). The editor opens as a full-window dialog: an 8-tab builder pane on the left, a live playground pane on the right, so you build and test without leaving the dialog. The divider collapses either pane (*Ctrl/Cmd + * hides the playground; *Ctrl/Cmd + Shift + * hides the builder), and your active tab and collapse state are remembered next time.

Two layouts exist. The default is the new tabbed builder (newAgentBuilder flag, on by default). The older single-page editor (one long scrolling form) is still reachable; force it for a session with the URL query ?newBuilder=0. Both edit the same agent; only the arrangement differs. This page teaches the default tabbed builder. The full legacy field order is in the Agent Builder field reference.

Watch out. There is no autosave here. Your work lives only in the form until you click Save Agent (disabled while anything required is missing). Save before you close.

The exhaustive field-by-field list, every slider and range, is in the Agent Builder field reference; here is what each tab means and what to put there.

Tab 1 — Persona

Who the agent is. Set the Name, a one-line Description, and the Instructions: the system prompt that is the soul of the agent. Write it like a job brief: who it is, what to do, how to behave, and what to return. A field co-pilot sits on the Instructions box; type a one-line seed and it drafts a fuller prompt you then refine. You can drop global variables with {{scope.X}}. This single field does more for quality than any slider.

Tab 2 — Model

What powers it, and how hard it thinks. Pick one or more LLM Models (several = a failover pool; register models on the LLMs page). Choose the Agent Mode: Auto, Fast, or Thinking (table below). If you pick Thinking, you can set a thinking budget. An Advanced sampling expander hides Temperature, Top P, Max tokens, and penalties; leave them at defaults unless you know why you’re changing them (for extraction, keep Temperature low).

Tab 3 — Knowledge

What the agent may read. Three sources, on sub-tabs: a View (a saved slice of a collection), a Datasheet (a SQL table), and, with the knowledgeCollections flag, Knowledge collections (whole indexed corpora, with a readiness dot so you know the index is built). Two locks tighten retrieval: Knowledge lock (answer only from attached knowledge) and Exact-match lock (exact rather than semantic matching). Scoping knowledge here is what stops an agent from “leaking” information it was never given.

Tab 4 — Capabilities

What the agent can do. Four sections: Tools (callables — SQL search, retrievers, your own APIs; Tools & functions), MCP servers (MCP servers), Skill Packs and Skills (Skills & skill packs). You pin the skills you want; a ghost list shows auto-discoverable in-scope skills with a Pin button, and a “Restrict to pinned skills only” checkbox locks the agent to exactly what you pinned.

Tab 5 — Output

The shape of the answer. Mode cards at the top: Table output, Standardization, Structured output, Section classification, Auto-annotate document. Structured output is the extraction workhorse: switch it on and a sub-form appears where you pick the Taxonomy/Learner (the schema whose Fields to fill), choose the Process unit (Page / Section / Image), add Labels with per-field Descriptions, and turn on Reasoning / Confidence Score / References. Confidence per field is what later routes a document to human review. This is the tab that turns a chatty agent into a data extractor.

Tab 6 — Governance

The rules and the sign-offs. Attach Guard rails (named policy objects; Guard rails) and configure Approvals: per-tool and per-team-member human-in-the-loop checkpoints (see HITL below).

Tab 7 — Context (Context Kernel)

Advanced: what context gets assembled into each prompt. A Profile template plus a Sources table (tiers + priorities), per-tier token budgets, a truncation strategy, and a Run preview that shows the final instructions and where the token budget was spent before you run anything. Most agents are fine on the default template; reach for this when an agent is over- or under-fed on context.

Tab 8 — Subagents

Turning this agent into a team leader. Add subagents (member agents) and a coordination mode, and this agent becomes a coordinator that delegates. Leave it empty and it stays a single agent. Full coverage in Teams & mesh.

When the form is valid, click Save Agent (the footer shows “Saving…”).

Auto, Fast & Thinking mode

The Agent Mode (set on the Model tab) decides how the agent reasons:

Mode	What it is	Pick it when
Auto	The default selectable option. The agent decides per question: Fast for simple/greeting/lookup messages, Thinking for analysis or multi-step work.	You want the best of both and don’t need to guarantee one path. Routing is still maturing; pick Fast or Thinking explicitly when you need predictable behaviour.
Fast	A single pass; the model answers directly. Lowest latency and cost.	High-volume, well-bounded work: field extraction, classification, short answers. Most production agents.
Thinking	The model reasons step-by-step (optionally with a thinking budget) before answering.	Multi-step problems, analysis, judgement calls, anything where the reasoning path matters or quality beats speed.

Tip. Build and tune in Thinking mode to see the agent’s reasoning, then switch to Fast for production once you trust it: same instructions at a fraction of the latency. (The legacy playground lets you flip the mode per run to compare; in the new builder, set the mode on the Model tab and re-save.)

HITL — human-in-the-loop approval

Some steps shouldn’t run unsupervised: posting to an external system, sending an email, anything costly or irreversible. HITL makes the agent pause at that step and wait for a person.

You configure it on Governance ▸ Approvals (per tool, and per team member). For each tool you set Request approval (on/off), the Approval type (Form or Multi-Select), and the Approval card text the reviewer reads. At run time the agent stops and surfaces a card with three choices: Reject, Review (leave feedback and send back), or Approve & Execute. You’ll see those exact cards in the playground while testing, which is the whole point: rehearse the approval flow before any real user meets it.

The Playground — how you test and iterate

The right pane is where a builder actually works. It has two tabs.

Playground tab

A live chat with the agent you’re building. It uses the current, unsaved form state, so you can tweak a tab and immediately see the effect.

Choose an Input Type: Text (just chat), Document (run against a picked document, with optional Page Numbers), or Project.
Optionally toggle Enable Chat History or attach files with +. (Set the Agent Mode on the Model tab; the new-builder playground has no per-run mode override — that lives in the legacy playground.)
Type your prompt in the question box and press Enter (or Send).
Watch the answer stream: tool calls as the agent invokes them, thinking blocks in Thinking mode, rendered tables and charts, and download links for attachments.
If a step needs approval, the HITL card appears right here (Reject / Review / Approve & Execute), so you can test the whole approval loop.

This tight loop — change a tab, re-run, read the result — is how you iterate an agent to “good”.

Task & metrics tab

Set up measured testing: provide a Sample Input and Sample Output and Validate the agent conforms; then in Evaluation Rule Setup pick a Task (or hit Auto-Detect to have the platform propose one) and choose the Metrics (Primary / Optional / Irrelevant) that define “good” for this agent. That feeds the Evaluation surface, so you can score the agent objectively rather than by eyeballing chats.

Connecting the agent to a Collection

A great agent does nothing until it’s given work. You hand it a stream of documents by making it a Collection’s intake agent, assigned from the Agents pane of the collection workspace:

Go to the collection (Studio ▸ Data Model ▸ Collections, or its workspace) and open its Agents tab.
Assign your agent as the collection’s intake/processing agent.
From now on, every document that lands in the collection — uploaded, pasted, or pulled in by a connector — is run by that agent automatically, filling the schema’s Fields and entering the lifecycle.

Tip. The collection’s Agents tab also has an “Open in Agent Builder” link that deep-links straight back to this editor for the assigned agent, so you can jump between tuning the agent and watching it process documents without losing your place.

That’s the heartbeat from the platform in one picture: the collection holds the work, the agent does it, and you watch it happen live.

Try it yourself — build an “Invoice Extractor”

Open the editor. Studio ▸ Agent Builder ▸ Agents → + Agent ▸ Agent.
Persona tab. Name: Invoice Extractor. Description: Extracts header fields from vendor invoices and flags overdue ones. For Instructions, use the field co-pilot with the seed “Extract the key fields from a vendor invoice and flag it if the due date has passed”, then edit the draft to read roughly: You are an invoice-processing assistant. For each invoice, extract the vendor name, invoice number, invoice date, due date, and total amount. If the due date is in the past, set is_overdue to true. Return only what the document supports; never invent a value.
Model tab. Pick your project’s LLM Model. Set Agent Mode = Thinking for now, so you can watch its reasoning while testing. Leave Advanced sampling at defaults.
Output tab. Turn on Structured output. Choose your invoice Taxonomy/Learner, set Process unit = Page, and add Labels for vendor_name, invoice_number, invoice_date, due_date, total_amount, is_overdue, each with a short Description (e.g. “The grand total including tax”). Turn on Confidence Score and References.
Governance tab (optional). If your invoices feed an external system later, add an approval on the relevant tool so a human signs off before anything posts.
Save. Click Save Agent.
Test in the playground. Set Input Type = Document, pick a sample invoice (and a page if needed), press Enter. Watch the Thinking block, the extracted fields, the confidence per field, and the References back to the page. Then flip Agent Mode = Fast and re-run the same invoice: same fields, much quicker. That’s your production setting.
Iterate. Wrong field? Sharpen its Description on the Output tab, re-run, repeat. When a few invoices come out clean, the agent is ready to be assigned to a collection. You’ll wire it to a real invoice collection in Invoice processing.

You just built and validated a working extraction agent: no code, all configuration.

Where to go next

Tools & functions — the Capabilities tab’s tools.
Guard rails — the Governance tab’s rules.
LLMs & services — register the models the Model tab lists.
Invoice processing — put this agent to work end to end.