> Source: https://builder.ema.ai/v2/agent-reference/extraction
> Title: Data Extractor Agent

# 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`.

```json
{
  "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" }
          }
        }
      }
    }
  }
}
```

Field

Required

Purpose

`output_schema`

Yes

JSON Schema the extracted output must conform to. Injected into the Instructions and used to validate the result.

`default_instructions`

No

Human-written extraction guidelines appended after the schema (for example, "Dates are in DD/MM/YYYY format"). Wrapped in a clear boundary so they can't be confused with the schema or system directives.

`system_prompt`

No

Overrides the base Instructions entirely. Use when you need full control over the prompt.

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**

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

**Output**

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

```json
{
  "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](/builder/v2/agent-reference#long-running-async-execution).

## 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](/builder/v2/agent-reference) — how agents work, the catalog, the four builder groups, and the shared execution engine.
-   [Rule Validator Agent](/builder/v2/agent-reference/rule-validation) — validate documents and data against business rules.
-   [Code Agent](/builder/v2/agent-reference/code-agent) — reshape or transform data programmatically with TypeScript.