Data Extractor Agent

The Data Extractor Agent (extraction) turns unstructured input into structured JSON. You give it a JSON Schema describing the record you want; it reads the input and returns data that conforms to that schema. Use it to pull fields out of invoices, contracts, emails, support tickets, or any free-form text that a downstream node needs in a predictable shape.

What makes extraction reliable is that the agent validates its own output against your schema and, on a violation, feeds the validation errors back to the model and retries — so a near-miss gets corrected automatically instead of failing the run or passing malformed data downstream.

The Data Extractor Agent belongs to the Frequently Used group in the agent library.

Configuration

You configure the agent through agent_config.type_config. The required field is output_schema.

{
  "output_schema": {
    "type": "object",
    "required": ["invoice_number", "total"],
    "properties": {
      "invoice_number": { "type": "string" },
      "total": { "type": "number" },
      "line_items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "description": { "type": "string" },
            "amount": { "type": "number" }
          }
        }
      }
    }
  }
}

The catalog's type-config schema for extraction requires only output_schema; the agent will reject a node that omits it with a validation error.

Inputs and output

The agent expects the source text on the instructions input key.

Input

{ "instructions": "Invoice #A-1043 — Total due: $4,200.00. ..." }

Output

The output is whatever your output_schema describes. For the schema above:

{
  "invoice_number": "A-1043",
  "total": 4200.00,
  "line_items": [ ... ]
}

Because the shape is builder-defined, the extraction type has no implicit default output schema in the catalog — the schema lives in your node's type_config.output_schema. Downstream nodes reference your fields via {{node_<id>.output.<your-field>}}.

Validation and the self-correcting retry

After the model responds, the agent:

1. Strips any markdown code fences and parses the response as JSON.
2. Confirms the result is a JSON object (not an array or primitive).
3. Validates it against your output_schema.

If any step fails, the agent returns a corrective prompt to the model describing the exact error (invalid JSON, wrong type, missing required field) and retries. The output-retry budget defaults to two self-corrections (override with type_config.max_output_retries); if the output still doesn't conform after the budget is spent, the run fails with AGENT_OUTPUT_INVALID.

The chunked extraction path

For document work the Agent splits the input into chunks, extracts each chunk in parallel, then merges the per-chunk results into one record that conforms to your output_schema. You configure the Agent the same way and get the same output shape.

This is not a size threshold. The chunked path runs whenever the Agent receives document content: a file input, a content string, or an instructions string. A one-page PDF takes it just as a 200-page one does. It is skipped when the Agent also has Tools, Knowledge Bases or forms attached, or when it receives conversation history, a context summary, persistent memory, or user context. In those cases the Agent falls back to a single pass. Inputs larger than roughly 25 MB are rejected with PAYLOAD_TOO_LARGE.

The distinction matters because this path adds a confidence score to every extracted value, and that changes which field names you can use.

Confidence scores and reserved field names

On the chunked path the Agent asks the model for a confidence score alongside every extracted value, then keeps the highest-scoring value for each field when it merges the chunks. Scoring is on by default.

The score is an integer from 1 to 5:

• 5: the value appears word for word in the source.
• 1: the value was heavily inferred, or the field was absent from the source.

Reserved field names

The Agent wraps every scalar value in its own metadata, so a few property names in your output_schema are reserved. A scalar field you name one of these ends up nested inside the platform's field of the same name, and the model has to guess which one you meant.

Only scalar fields collide. An object or an array named confidence is fine, because the Agent looks inside those rather than wrapping them.

Saving or publishing an AI Employee whose schema claims one of these names returns an advisory warning naming the exact field. Rename it, for example extraction_confidence instead of confidence, and your own values pass through untouched.

To turn scoring off, set type_config.map_reduce.disable_confidence_scoring to true. That releases value and confidence. Source highlighting still reserves its four names.

Source highlighting

Set agent_config.source_highlighting_enabled to true and the Agent grounds every extracted value in the source document: the verbatim span the value came from, a short surrounding context window, the page number, and the file name. Reach for this before writing your own evidence fields, because you get page numbers and exact spans without spending any of the reserved names.

The Workflow Run turns that evidence into highlight regions and stores them in the run's source_highlights array. A reviewer who opens the document sees each extracted value highlighted where it was found.

Source highlighting is off by default. When it is off, the output is exactly what it would have been without the feature, and there is no added token cost.

Long-running execution

Because extraction over large documents can take a while, an extraction node can run on the asynchronous execution path (POST /internal/execute-async): the agent returns a job handle immediately and posts the result back when it finishes. This avoids holding a synchronous connection open for the full run. See the Agent Reference overview.

Notes and limits

• Keep your output_schema as specific as you can — required fields and types are what the self-correcting retry checks against, so a tighter schema yields more reliable extractions.
• The conventional input key is instructions, but input_mapping keys are free-form; wire whatever upstream field holds the source text.
• Before you add your own confidence or evidence fields, check whether the platform already gives you what you need. Confidence is scored for you, and source highlighting supplies page numbers and exact spans.

What's next

• Agent Reference overview — how agents work, the catalog, the four builder groups, and the shared execution engine.
• Rule Validator Agent — validate documents and data against business rules.
• Code Agent — reshape or transform data programmatically with TypeScript.