Skip to content

AI agent

How-to9 minExpert

Before you start

An AI agent step sends your instructions, and a file, web page or list, to a language model. It brings the answer back as data. Use it to pull the vendor name and total out of an uploaded purchase order.

When should I use an AI agent?

Section titled “When should I use an AI agent?”

Use it for documents and text that do not follow a fixed layout. For data that already has a clear shape, use the JSON parser or the CSV parser. The model can be wrong, so follow it with a Decision or an Approval task when the result matters.

Add an AI agent

Section titled “Add an AI agent”
  1. Click + and choose AI agent. It sits in the Data group.
  2. Under Model, choose the Provider and the Model, and paste your API key.
  3. Under What it reads, choose A file field, A web address, A list from this workflow or Nothing, and fill in what the choice asks for.
  4. Under Instructions, tell the model what to do. Use Insert data for values.
  5. Under It answers with, choose Text, Yes or no, A number or Fields, objects and lists.
  6. Under Result, type a name in Name it.
An AI agent step selected, with OpenAI and GPT-4.1 mini chosen, a saved API key, and the source set to a file field.
    Choose a Provider and a Model.
    What it reads offers four sources.
    For a file field, pick the field that holds the file.

What do the settings do?

Section titled “What do the settings do?”
SettingWhat it does
ProviderOpenAI, Anthropic, OpenRouter (any model) or Google
ModelThe models offered for that provider. For OpenRouter, type the model name
API keyYour key from the provider. Stored securely and never shown again
What it readsA file field (PDF, Word, Excel, PowerPoint, text or HTML), A web address, A list from this workflow, Nothing
InstructionsWhat to do. Start each instruction with # to list them as separate steps
It answers withText, Yes or no, A number, or Fields, objects and lists
Name itThe name of the result

The models offered are OpenAI GPT-4.1 mini and GPT-4.1, Anthropic Claude Sonnet, Opus and Haiku, and Google Gemini 2.5 Pro and Gemini 2.5 Flash.

How do I get fields back?

Section titled “How do I get fields back?”

Choose Fields, objects and lists and describe the answer’s shape, the same way as in the JSON parser. You can also paste a sample. The model is told to answer in exactly that shape. A text, yes or no, or number answer arrives as one field named agent_result.

The It answers with section of an AI agent step set to Fields, objects and lists, showing an order_details list of objects with quantity, product_id and unit_price.
    Choose the kind of answer: Text, Yes or no, A number or Fields, objects and lists.
    Each field has a name and a type. List every field that later steps need.
    Name it names the result.

Worked example: read an uploaded purchase order

Section titled “Worked example: read an uploaded purchase order”

A customer uploads a PO as a PDF. Layla chooses A file field and picks Original PO. The instructions say to return the customer name, order date and lines. She chooses Fields, objects and lists, adds those fields, and names the result poData. A Loop then goes over the lines.

What should I watch for?

Section titled “What should I watch for?”

For a CSV file, use the CSV parser. For other documents, give the agent a PDF, Word, Excel, PowerPoint, text or HTML file.

  • The key is saved per step. Leave API key empty to keep the saved one.
  • List every field you want later steps to use under It answers with.
  • In a Loop, each round sends its own instructions and file.

Check yourself

An AI agent is set to answer with a Number. How do later steps read it?
Show the answer

As a field named after the result, then agent_result. A text, yes or no, or number answer arrives as one field named agent_result, under the result name you chose.

Which file kind does the AI agent read from a file field?
Show the answer

A PDF. The file field source reads PDF, Word, Excel, PowerPoint, text or HTML files.

What's next

JSON parserTurn JSON text, from a webhook or a field, into data that later steps can read, by describing its shape.DecisionSplit a workflow into a Yes path and a No path, based on conditions about the record or a list.

Last checked