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 one self-correction; if the output still doesn't conform after the budget is spent, the run fails with AGENT_OUTPUT_INVALID.

Large inputs: automatic map-reduce

When the input is large enough to exceed the chunk size (about 30,000 tokens), the extraction path automatically switches to a map-reduce strategy:

• The input is split into chunks and each chunk is extracted in parallel.
• A final reduce step merges the per-chunk results into one record that conforms to your output_schema.

This is transparent — you configure the agent the same way and get the same output shape. Map-reduce activates only for a plain extraction node: no Tools, no conversation history, no persistent memory, and no user context. If any of those are present, the agent falls back to the standard single-pass loop. Inputs larger than roughly 25 MB are rejected with PAYLOAD_TOO_LARGE.

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.

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.