Node deep dive: AI Agent

The AI Agent node lets you run an LLM call inside a workflow. Use it for transforming, classifying, summarizing, or generating content at any step. Where the Data Extractor is purpose-built for "document → structured data," the AI Agent is general-purpose.

When to use the AI Agent

• Classify an item into one of several categories ("Is this email an invoice, a receipt, or marketing?")
• Summarize a long text into a few sentences
• Translate content between languages
• Generate a tailored message (a customer-facing email body based on context)
• Reformat / clean messy data ("Normalize this address into US standard format")
• Decide the next branch of a workflow (combine with a Switch node)

For "extract structured fields from a document," prefer Data Extractor — it's tuned for that case and returns predictable JSON.

When NOT to use it

• You need deterministic output. The AI Agent is probabilistic. For deterministic transformations (string manipulation, math), use a JS Code node or formula.
• You're extracting fields from a document. Use Data Extractor.
• You need very fast, very cheap calls at high volume. AI Agent calls cost money per token. For millions of trivial calls, use code.
• You want to enforce a strict schema. Possible but more work — Data Extractor is easier here.

Configuration

Output: text vs. JSON

Plain text

The model's reply is a string. Use for summaries, generated content, classifications where the answer is one word.

Output: "Invoice"

Downstream nodes reference it as {{$item.previous.data.output}}.

JSON

The model's reply is parsed as a JSON object. Use when you need multiple fields back from one call.

Prompt example:

Classify this email and extract the urgency level. Reply with JSON:
{
  "category": "...",   // one of: invoice, receipt, marketing, support
  "urgency": "..."     // one of: low, medium, high
}

Email:
{{$item.data.subject}}
{{$item.data.body}}

Downstream nodes reference fields directly: {{$item.previous.data.category}}.

If the model returns invalid JSON, the node errors. Use the error output to handle gracefully (route to a "needs human review" branch).

Prompt patterns that work

Classification

Classify the following email into exactly one category:
- invoice
- receipt
- marketing
- support
- other

Reply with only the category name, nothing else.

Email:
Subject: {{$item.data.subject}}
Body: {{$item.data.body}}

Set Temperature to 0. Set Max Tokens low (10).

Summarization

Summarize the following document in 2 sentences for an executive audience.
Focus on key decisions and dollar amounts.

{{$item.previous.data.text}}

Temperature 0.3.

Reformat / normalize

Convert the following address into the US Postal Service standard format.
Return only the formatted address; no preamble, no explanation.

Input: {{$item.data.address}}

Temperature 0.

Decision routing (combine with Switch)

Decide which department this support ticket should go to.
Reply with only the department name. Options:
- billing
- technical
- onboarding
- sales

Ticket:
{{$item.data.subject}}
{{$item.data.body}}

Wire the output to a Switch node with branches for each department.

Choosing a model

The AI Agent node lets you choose from several enterprise model families that Lido supports under zero-retention agreements. The exact list is visible inside the model dropdown in the node — pick the model family that fits your task.

Practical guidance:

• Default to a strong, recent model for any task that touches customer data. The cost difference per call is usually irrelevant compared to the cost of a wrong answer.
• For very high volume, low-stakes classification, smaller/faster models can be a 10x cost savings.
• For long-context tasks (summarizing a 100-page document), pick a model with a large context window.
• Be consistent within a workflow. Switching models for a tiny cost saving creates inconsistent behavior across nodes.

Combining with Data Extractor

Common pattern: extract structured fields with Data Extractor, then run an AI Agent to do additional reasoning over those fields.

Data Extractor → produces {Vendor, Total, Date, ...}
   ↓
AI Agent → "Given this invoice, what's the appropriate GL category?"
   ↓
Spreadsheet → write GL category alongside extracted fields

This separation makes the pipeline more debuggable than asking one node to do both.

Cost and rate limits

AI Agent calls go to upstream model providers under Lido's contracts. Each call is metered by tokens (input + output). High-volume workflows can rack up significant cost — monitor usage.

Rate limits are enforced by the upstream provider. If you hit them, the node errors with a rate-limit response; configure retries with backoff.

Error handling

The AI Agent node has an error output, like every other node. Common error cases:

• Invalid JSON output when JSON format is required.
• Model rate limit (429 from upstream).
• Model temporarily unavailable (5xx from upstream).
• Output too long for downstream consumer.

Wire the error output to a sensible fallback: a default value, a notification to a human, or a retry with a different model.

Tips

• Test the prompt in the spreadsheet UI first. The AI formulas (GPT, CLAUDE, etc.) take the same prompt — iterate there until the output is right, then port the prompt into the workflow node.
• Be specific in the prompt. "Reply with only the category name, nothing else" prevents the model from adding "Sure! Here's the category: invoice."
• Use Temperature 0 for classification and structured output. Use higher temperature only when you want variation.
• Use System Prompt for stable persona/role. Keep User Prompt focused on the per-item task.
• Cap Max Tokens to bound cost on runaway responses.
• Validate JSON output downstream. Even strict prompts occasionally return malformed JSON.

Common mistakes

• Prompt that mixes data and instruction: "Look at this email: ... and decide the category." The model can get confused which is which. Separate them clearly with markers ("Email follows below:", "===") and put the instruction first.
• No constraint on output format. "Categorize this email" returns "Sure, this email is about pricing, which is..." Add "Reply with only the category name."
• Long context with no summarization upstream. Sending the entire document text every time is slow and expensive. Pre-process if possible.
• Temperature 1 on classification. Random outputs ensue.
• Trusting the output without downstream validation. Especially in JSON mode — always handle malformed responses.
• Using AI Agent for things a formula could do. Not every problem needs an LLM.

Related articles

• AI columns and formulas (the spreadsheet equivalent of this node)
• Improve extraction accuracy
• Build your first workflow
• Error handling and retries
• Node deep dive: Data Extractor

Updated on: 16/04/2026