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

# Ai prompt node

# AI Prompt Node

The **AI Prompt Node** lets you interact with large language models (LLMs) directly from your workflow. Use it to parse conversation transcripts, extract structured data from unstructured text, classify intent, or generate dynamic content.

> [!NOTE]
>
> The AI Prompt Node uses the same technology that powers Liberate's Voice AI - you can leverage LLM capabilities for both real-time conversations and backend workflow processing.

## Overview

Use an AI Prompt Node when you need to:

* Parse Voice AI transcripts into structured JSON
* Extract entities (names, dates, policy numbers) from text
* Classify customer intent or claim type
* Summarize long conversations
* Generate dynamic responses or content
* Validate or interpret unstructured input

***

## When to Use AI Prompt vs. Other Nodes

| Task | Best Node |
| - | - |
| Parse unstructured text into JSON | **AI Prompt Node** ✅ |
| Transform structured JSON to different format | Mapping Node |
| Simple field extraction with known structure | Mapping Node |
| Complex text interpretation | **AI Prompt Node** ✅ |
| Call external API | Task Node |
| Conditional logic with clear rules | Decision Table Node |
| Fuzzy matching or intent detection | **AI Prompt Node** ✅ |

> [!TIP]
>
> Use AI Prompt Node for unstructured-to-structured transformations. Use Mapping Node for structured-to-structured transformations.

***

## Configuration

Click on an AI Prompt Node to open its configuration panel.

### Basic Settings

| Setting | Description |
| - | - |
| **Title** | Descriptive name for the node |
| **Prompt** | The instruction sent to the LLM |
| **Output Property** | Where to store the AI response in context |

### Writing Effective Prompts

Your prompt should include:

1. **Clear instruction** — What you want the AI to do
2. **Input data** — Reference to context variables (e.g., `{{context.transcript}}`)
3. **Output format** — Specify the exact structure you expect
4. **Examples** (optional) — Help the AI understand edge cases

***

## Prompt Structure

### Basic Template

```
[INSTRUCTION]
Describe what you want the AI to do.

[INPUT]
Reference the data to process: {{context.variableName}}

[OUTPUT FORMAT]
Specify the exact JSON structure you expect.

[ADDITIONAL RULES]
Any special handling instructions.
```

### Referencing Context Variables

Use double curly braces to inject context data into your prompt:

| Syntax | Description |
| - | - |
| `{{context.transcript}}` | Insert the transcript field |
| `{{context.claimant.firstName}}` | Insert nested field |
| `{{context}}` | Insert entire context object |

***

## Insurance Examples

### Parse FNOL Transcript

Extract structured claim data from a Voice AI conversation.

**Prompt:**

```
Parse the following insurance claim call transcript and extract all relevant information as a JSON object.

Extract these fields:
- claimType (water, fire, theft, auto, wind, other)
- claimDescription (brief description of what happened)
- callerFirstName
- callerLastName
- policyNumber (format: XX-XXXXXXXX)
- dateOfLoss (YYYY-MM-DD format)
- timeOfLoss (HH:MM format, 24-hour)
- propertyAddress (full address if mentioned, null if not)
- contactPhone (digits only, null if not mentioned)
- injuriesReported (true/false)

Transcript:
{{context.transcript}}

Respond with ONLY the JSON object, no additional text or explanation.
```

**Sample Input (transcript):**

```
Assistant: Thank you for calling Acme Insurance. How can I help you today?
User: Hi, I need to file a claim. My basement flooded this morning.
Assistant: I'm sorry to hear that. I can help you with that. May I have your policy number?
User: Yes, it's HO-12345678.
Assistant: Thank you. And your name?
User: John Smith.
Assistant: Got it, John. When exactly did the flooding occur?
User: Around 6 AM this morning.
Assistant: Was anyone injured?
User: No, thankfully everyone is fine.
```

**AI Output:**

```json theme={null}
{
  "claimType": "water",
  "claimDescription": "Basement flooded",
  "callerFirstName": "John",
  "callerLastName": "Smith",
  "policyNumber": "HO-12345678",
  "dateOfLoss": "2025-02-17",
  "timeOfLoss": "06:00",
  "propertyAddress": null,
  "contactPhone": null,
  "injuriesReported": false
}
```

***

### Classify Claim Type

Determine the type of claim from a description.

**Prompt:**

```
Classify the following claim description into exactly one category.

Categories:
- water (flooding, pipe burst, water damage, leak)
- fire (fire damage, smoke damage, electrical fire)
- theft (burglary, stolen property, break-in)
- auto (car accident, vehicle damage, collision)
- wind (storm damage, hurricane, tornado, fallen tree)
- liability (injury on property, lawsuit, third-party claim)
- other (anything that doesn't fit above categories)

Description: {{context.claimDescription}}

Respond with ONLY a JSON object in this format:
{
  "category": "category_name",
  "confidence": "high/medium/low",
  "reasoning": "brief explanation"
}
```

**Sample Input:**

```
"A tree fell on my car during last night's storm"
```

**AI Output:**

```json theme={null}
{
  "category": "wind",
  "confidence": "high",
  "reasoning": "Storm-related tree damage to vehicle indicates wind/storm claim"
}
```

***

### Extract Policy Information from Email

Parse an incoming email to extract key details.

**Prompt:**

```
Extract policy and customer information from the following email.

Email content:
{{context.emailBody}}

Extract:
- customerName (full name)
- policyNumber (if mentioned)
- requestType (quote, claim, billing, policy_change, cancellation, general_inquiry)
- urgency (high, medium, low)
- summary (one sentence describing the request)
- actionRequired (what needs to be done)

Respond with ONLY the JSON object.
```

**Sample Input:**

```
Subject: URGENT - Need to add new driver to policy

Hi, 

My name is Sarah Johnson and I need to add my daughter to my auto policy 
immediately. She just got her license and needs to drive to school starting 
Monday. My policy number is AU-98765432.

Please call me back ASAP at 555-123-4567.

Thanks,
Sarah
```

**AI Output:**

```json theme={null}
{
  "customerName": "Sarah Johnson",
  "policyNumber": "AU-98765432",
  "requestType": "policy_change",
  "urgency": "high",
  "summary": "Customer needs to add new driver (daughter) to auto policy before Monday",
  "actionRequired": "Add new driver to policy AU-98765432 and call customer at 555-123-4567"
}
```

***

### Summarize Conversation for Agent Handoff

Create a summary for warm transfer to human agent.

**Prompt:**

```
Summarize the following customer conversation for a human agent handoff.

Include:
- customerName: Name of the caller
- reason: Why they called (one sentence)
- keyDetails: Bullet points of important information gathered
- customerSentiment: positive, neutral, frustrated, or angry
- recommendedAction: What the agent should do next

Transcript:
{{context.transcript}}

Respond with ONLY the JSON object.
```

**AI Output:**

```json theme={null}
{
  "customerName": "John Smith",
  "reason": "Filing a water damage claim for basement flooding",
  "keyDetails": [
    "Policy: HO-12345678",
    "Incident: Basement flooded this morning around 6 AM",
    "Cause: Unknown, possibly pipe burst",
    "No injuries reported",
    "Damage extent not yet assessed"
  ],
  "customerSentiment": "neutral",
  "recommendedAction": "Complete FNOL intake and schedule adjuster visit"
}
```

***

### Validate and Correct Data

Check extracted data for errors and inconsistencies.

**Prompt:**

```
Review the following extracted claim data for errors or inconsistencies.

Data to validate:
{{context.extractedClaim}}

Check for:
1. Policy number format (should be 2 letters, dash, 8 digits)
2. Date of loss is not in the future
3. Phone numbers have 10 digits
4. Required fields are not null (claimType, policyNumber, dateOfLoss)

Respond with:
{
  "isValid": true/false,
  "errors": ["list of errors found"],
  "correctedData": { corrected version if fixable, null if not },
  "needsHumanReview": true/false
}
```

***

## Output Handling

### Storing AI Response

Configure the **Output Property** to specify where the AI response is stored:

| Setting | Result |
| - | - |
| Output Property: `parsedClaim` | Response stored at `context.parsedClaim` |

### Accessing Output in Subsequent Nodes

After the AI Prompt Node, reference the output in Mapping or Task nodes:

```jsonata theme={null}
{
  "claimType": $.parsedClaim.claimType,
  "policyNumber": $.parsedClaim.policyNumber
}
```

### Handling JSON Responses

When you instruct the AI to respond with JSON, the output is automatically parsed. You can access nested fields directly:

```jsonata theme={null}
{
  "fullName": $.aiResponse.callerFirstName & " " & $.aiResponse.callerLastName
}
```

***

## Prompt Engineering Best Practices

### Be Specific About Output Format

**❌ Vague:**

```
Extract the claim information from this transcript.
```

**✅ Specific:**

```
Extract claim information as a JSON object with these exact fields:
- claimType (string): water, fire, theft, auto, wind, or other
- dateOfLoss (string): YYYY-MM-DD format
- policyNumber (string): format XX-XXXXXXXX

Respond with ONLY the JSON object, no additional text.
```

### Include Edge Case Instructions

```
If a field cannot be determined from the transcript, set it to null.
If the policy number format doesn't match XX-XXXXXXXX, include it anyway 
and set "policyNumberFormatValid": false.
```

### Use Examples for Complex Parsing

```
Example input: "It happened last Tuesday around noon"
Example output: { "dateOfLoss": "2025-02-11", "timeOfLoss": "12:00" }

Example input: "I'm not sure exactly when, sometime last week"
Example output: { "dateOfLoss": null, "timeOfLoss": null, "dateUncertain": true }
```

### Constrain Response Length

For classification tasks, enforce brevity:

```
Respond with ONLY the category name, nothing else.
```

For structured data:

```
Respond with ONLY a valid JSON object. Do not include markdown code blocks, 
explanations, or any text outside the JSON.
```

***

## Error Handling

### AI Response Errors

The AI Prompt Node can fail if:

* The LLM service is unavailable
* The prompt is malformed
* The response doesn't match expected format

### Branching on Errors

Like other nodes, AI Prompt Node has success and error paths:

```
AI Prompt Node (Parse Transcript)
    ├── Success → Mapping Node → Task Node
    └── Error → Fallback Handler → Escalate to Human
```

### Validating AI Output

Add a Mapping Node after AI Prompt to validate the response:

```jsonata theme={null}
{
  "isValidResponse": $exists($.parsedClaim.claimType) and $exists($.parsedClaim.policyNumber),
  "parsedClaim": $.parsedClaim
}
```

Then use a Decision Table or conditional logic to handle invalid responses.

***

## Best Practices

### Use AI Prompt for Unstructured Data Only

If your input is already structured JSON, use a Mapping Node instead—it's faster and more predictable.

### Keep Prompts Focused

One AI Prompt Node should do one thing well:

| ❌ Bad | ✅ Good |
| - | - |
| Parse transcript AND classify claim AND generate summary | AI Prompt 1: Parse transcript |
| | AI Prompt 2: Classify claim type |
| | AI Prompt 3: Generate summary |

### Test with Edge Cases

Test your prompts with:

* Incomplete information
* Misspellings and typos
* Unusual formats
* Multiple languages (if applicable)
* Very short or very long inputs

### Monitor Output Quality

Regularly review AI Prompt outputs in production:

* Are extractions accurate?
* Are classifications correct?
* Are there patterns in failures?

Refine prompts based on real-world performance.

***

## Common Issues

### AI Returns Extra Text

**Symptom:** Response includes explanations or markdown instead of just JSON.

**Fix:** Add explicit instructions:

```
Respond with ONLY the JSON object. 
Do not include any explanations, markdown formatting, or text outside the JSON.
```

### Inconsistent Output Format

**Symptom:** Sometimes returns `"date": "02/17/2025"`, sometimes `"date": "2025-02-17"`.

**Fix:** Specify exact format in prompt:

```
dateOfLoss (string): Must be in YYYY-MM-DD format. Example: "2025-02-17"
```

### Null Values Not Handled

**Symptom:** AI omits fields instead of setting them to null.

**Fix:** Explicitly instruct:

```
If any field cannot be determined, include the field with value null.
Never omit fields from the response.
```

### Slow Response Times

**Symptom:** AI Prompt Node takes several seconds.

**Fix:**

* Shorten the prompt
* Reduce input data size (truncate long transcripts)
* Use async workflow execution

***

## Next Steps

> [card] [Voice AI Workflows](https://docs.liberate.ai/workflows/voice-ai-workflows.md)
>
> See AI Prompt in action parsing transcripts

> [card] [Mapping Node](https://docs.liberate.ai/workflows/nodes/mapping-node.md)
>
> Transform AI output for external systems

> [card] [Task Node](https://docs.liberate.ai/workflows/nodes/task-node.md)
>
> Send parsed data to your systems

> [card] [Decision Table Node](https://docs.liberate.ai/workflows/nodes/decision-table-node.md)
>
> Route based on AI classifications


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.