Add an extraction agent

An extraction agent reads a document you give it and returns structured data — a JSON object whose fields you define in advance. Instead of chatting, it fills in a schema: you describe the fields you want, and the agent pulls those values out of each document.

Agents live in your workspace and are created from the New Agent card on the workspace overview (or the + next to Agents in the left sidebar). Choosing the Extraction type is what makes the agent extract data rather than hold a conversation.

How an extraction agent works

You define the fields to capture on the Output tab (for example title and summary) and write Instructions telling the agent what to extract. When the agent runs on a document, it returns one JSON object matching those fields. An extraction agent has three configuration tabs — General, Model and Output — no conversation or greeting settings — and each tab saves on its own (the editor warns you before you leave a tab with unsaved changes).

The full flow at a glance

The walkthrough below replays every step in the real interface. Use Prev / Next to move at your own pace; each step highlights the button to click and the area to watch.

Step by step

1. Open the New Agent dialog

On the workspace overview, find the New Agent card and click Create (you can also use the + next to Agents in the left sidebar).

2. Choose the Extraction type

In the New Agent dialog, under Agent type, select Extraction. The type determines what the agent does, so pick it before continuing.

3. Name the agent and create it

Type a Name (at least 3 characters) in the Name field, then click Create. Your agent is created with sensible defaults and opens in the editor.

4. Set the basics on General

The editor opens on the General tab. Set the:

• Name — how the agent appears in your workspace.
• Locale — the language the agent works in.
• Instructions — what the agent should extract from each document.

Click Save.

5. Pick the model on Model

Open the Model tab and choose the Model that powers the agent, and a Temperature (lower values give more consistent, literal extractions). Save.

6. Define the output on Output

Open the Output tab and build the fields to extract visually — no JSON required. Click Add field and, for each field, set:

• Field name — the key it’s stored under (e.g. title).
• Type — Text, Number, Yes / No, List, or Choice. Number offers an optional min/max range, and Choice lets you define the allowed values.
• Description — the hint the agent uses to decide what to put there.
• Required — toggle on for fields the agent must fill.

Remove a field with its trash icon. Prefer to edit the schema by hand? Click Advanced mode (top right) to switch to a raw JSON editor, and Visual editor to switch back. Click Save.

7. Save each tab

Because each tab is its own form, click Save on every tab you change (or Cancel to discard a tab’s edits). The extraction agent is then ready to run on documents — see Run an extraction.

Version history

Every save creates a new version of the agent. Open History (top right of the editor, showing the current v number) to browse past versions in a side panel, compare what changed (Changes in this version or Compare with current), and Restore this version — which copies those settings as a new current version without deleting anything. See Version history for the full walkthrough.

Tips

• Keep field descriptions in the schema clear — the agent uses them to decide what to put in each field.
• Use a low Temperature (for example 0.2) for extraction: you want faithful, repeatable output rather than creative answers.
• Mark only genuinely mandatory fields as Required; the agent returns null for a required value it can’t find.
• The visual editor offers Text, Number, Yes / No, List and Choice fields. For nested objects, switch to Advanced mode and edit the JSON.

Troubleshooting

• The Create button is disabled — the Name must be at least 3 characters.
• I don’t see the field type I need — the visual editor covers Text, Number, Yes / No, List and Choice; use Advanced mode (raw JSON) for nested objects.
• My schema won’t save in Advanced mode — it must be a valid JSON object; the editor shows Output JSON schema must be a valid JSON object and keeps you in Advanced mode until you fix it.
• I don’t see an Output tab — only non-conversation agents have one. Make sure you created an Extraction agent (conversation agents chat instead).
• The extracted values look wrong — refine the field descriptions and the Instructions, then click Save and try again.