> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retoneai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Extraction Stage

> Collect and validate information from callers

The **Data Extraction** stage systematically collects information from callers. Define the variables you need, and the AI asks for and validates each piece of data.

## Overview

Data Extraction nodes are ideal when you need to:

* Collect customer information (name, email, phone)
* Gather order details
* Capture booking requirements
* Validate input formats

<Info>
  Data Extraction nodes are colored **purple** on the canvas.
</Info>

## Configuration

### Extraction Method

| Method       | Description                                                        |
| ------------ | ------------------------------------------------------------------ |
| **Ask User** | The agent explicitly asks for each piece of information            |
| **Infer**    | The agent extracts information mentioned naturally in conversation |

<Tabs>
  <Tab title="Ask User">
    The agent asks for each variable directly:

    ```
    Agent: "May I have your full name, please?"
    Caller: "John Smith"
    Agent: "Thank you, John. And what's your email address?"
    ```

    Best for: Forms, registrations, structured data collection
  </Tab>

  <Tab title="Infer">
    The agent extracts data from natural conversation:

    ```
    Caller: "Hi, this is John Smith calling about order 12345"
    Agent: (internally captures: name="John Smith", order_number="12345")
    ```

    Best for: Conversational flows where users volunteer information
  </Tab>
</Tabs>

### Max Attempts

Number of times to retry if validation fails (default: 3).

After max attempts, the conversation continues without the variable (if not required) or triggers a fallback transition.

## Variables

Each variable defines a piece of information to collect:

### Variable Properties

| Property        | Description                                     |
| --------------- | ----------------------------------------------- |
| **Name**        | Identifier (snake\_case, e.g., `customer_name`) |
| **Type**        | Data type for validation                        |
| **Required**    | Whether collection can continue without it      |
| **Prompt**      | Question to ask the user                        |
| **Description** | Context for the AI about this field             |
| **Validation**  | Regex pattern for format validation             |
| **Options**     | Choices for `select` type                       |

### Variable Types

| Type        | Description         | Example                                           |
| ----------- | ------------------- | ------------------------------------------------- |
| `string`    | Short text          | Name, city                                        |
| `long_text` | Extended text       | Issue description                                 |
| `number`    | Numeric value       | Age, quantity                                     |
| `boolean`   | Yes/No              | Confirmation                                      |
| `select`    | Choice from options | Size (S/M/L)                                      |
| `date`      | Date value          | Appointment date                                  |
| `email`     | Email address       | [contact@example.com](mailto:contact@example.com) |
| `phone`     | Phone number        | +1-555-123-4567                                   |

### Validation Patterns

Use regex patterns to validate format:

```yaml theme={null}
# Order number: 2 letters + 6 digits
order_number:
  type: string
  validation: "^[A-Z]{2}[0-9]{6}$"
  prompt: "What's your order number? It starts with two letters followed by 6 digits."

# US Phone number
phone:
  type: phone
  validation: "^\\+?1?[0-9]{10}$"
  prompt: "What's your phone number?"

# Email
email:
  type: email
  validation: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
  prompt: "What's your email address?"
```

## Transitions

Data Extraction nodes support special transition types:

| Type              | Trigger                                       |
| ----------------- | --------------------------------------------- |
| **All Extracted** | All required variables collected successfully |
| **Timeout**       | User didn't respond in time                   |
| **Keyword**       | User said a specific trigger word             |

### All Extracted Transition

Automatically fires when all required variables have been collected:

```yaml theme={null}
Transitions:
  - Type: all_extracted
    Target: Process Order
```

## Example Configurations

<AccordionGroup>
  <Accordion title="Customer Contact Info">
    ```yaml theme={null}
    Extraction Method: Ask User
    Max Attempts: 3

    Variables:
      - name: customer_name
        type: string
        required: true
        prompt: "May I have your full name, please?"

      - name: email
        type: email
        required: true
        prompt: "What's the best email address to reach you?"

      - name: phone
        type: phone
        required: false
        prompt: "And a phone number in case we need to call you back?"

    Transitions:
      - all_extracted → Confirmation
      - keyword: "stop", "cancel" → End Call
    ```
  </Accordion>

  <Accordion title="Order Lookup">
    ```yaml theme={null}
    Extraction Method: Ask User
    Max Attempts: 3

    Variables:
      - name: order_number
        type: string
        required: true
        validation: "^[A-Z]{2}[0-9]{6}$"
        prompt: |
          What's your order number?
          It starts with two letters followed by six digits,
          like AB123456.

    Transitions:
      - all_extracted → Order Status
      - keyword: "don't have it", "don't know" → Alternative Lookup
    ```
  </Accordion>

  <Accordion title="Appointment Booking">
    ```yaml theme={null}
    Extraction Method: Ask User
    Max Attempts: 3

    Variables:
      - name: preferred_date
        type: date
        required: true
        prompt: "What date works best for your appointment?"

      - name: preferred_time
        type: select
        required: true
        options: ["Morning (9-12)", "Afternoon (12-5)", "Evening (5-8)"]
        prompt: "Do you prefer morning, afternoon, or evening?"

      - name: appointment_type
        type: select
        required: true
        options: ["Consultation", "Follow-up", "New Patient"]
        prompt: "Is this a consultation, follow-up, or new patient visit?"

    Transitions:
      - all_extracted → Calendar Booking
    ```
  </Accordion>
</AccordionGroup>

## Using Extracted Variables

Once collected, variables can be used in:

* **Subsequent prompts**: Reference as `{{variable_name}}`
* **If/Else conditions**: Branch based on values
* **Function calls**: Pass to external systems
* **Transfer briefings**: Include in human transfer context

```
Prompt: |
  Help {{customer_name}} with their order {{order_number}}.
  Their preferred contact is {{email}}.
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Ask One Thing at a Time" icon="1">
    Don't overwhelm callers. Collect variables sequentially.
  </Card>

  <Card title="Explain Format Requirements" icon="info">
    If validation is strict, tell callers the expected format upfront.
  </Card>

  <Card title="Make Optional Fields Optional" icon="square-check">
    Don't require information you don't actually need.
  </Card>

  <Card title="Handle Failures Gracefully" icon="shield">
    Set reasonable max attempts and provide fallback paths.
  </Card>
</CardGroup>

## Related

<CardGroup cols={2}>
  <Card title="If/Else Stage" icon="code-branch" href="/agent-builder/stages/if-else">
    Branch based on extracted data
  </Card>

  <Card title="Transitions" icon="arrow-right" href="/agent-builder/transitions">
    Configure extraction-based routing
  </Card>

  <Card title="Calendar Booking" icon="calendar" href="/agent-builder/stages/calendar-booking">
    Book appointments with extracted data
  </Card>
</CardGroup>