Browse documentation

Ask an agent

Hand a step of a workflow to an agent, and get its answer back as text or as typed records the next steps can save.

Most steps in a workflow run the same way every time. Some need judgment: read a prospectus extract and say what the ongoing charge is, explain why a NAV moved, classify a free-text comment. The Ask Agent action is where that judgment goes. It sends an instruction, and optionally the data the workflow has produced so far, to one of your workspace's agents, and passes the agent's answer on to the next step.

The answer comes back in one of two shapes:

  • Text, by default: one row holding the agent's reply.
  • Records, with Structured output on: one row per item the answer gives, with the columns you define, so a Save Record step can write them straight into a data object.

Add the step

  1. Open the workflow on the canvas.
  2. Add a node and type Ask Agent in the Search actions... box. It sits in the Custom group of the node picker.
  3. Select the node to open its side panel and fill in the fields below.
  4. Save the workflow.
ConfigureExecutionsAsk AgentCustomAsk an agent to work on the data and answerData Sources0 / 1Agent Id*ID of the agent to invoke.NAV Oversight AnalystUser Instruction*Instructions to send to the agent.List each share class in the KIID with its ongoing charge.Use Previous Action DataWhether to include data from the previous action in the message.Structured outputReturn the answer as records with the fields below, one for eachitem it gives. The agent answers as usual, then its answer is readinto the fields and checked.Output fields*Each field is a column of the step's output.Share Class*String · The share class, as the KIID names it.Ongoing ChargeNumber · The ongoing charge, in percent.Add field
The Ask Agent panel: agent, instruction, and whether to pass data and answer in fields.

Set up the step

FieldWhat it does
Agent IdThe agent that answers. Pick it from the list of your workspace's agents
User InstructionWhat you ask the agent to do, in plain language
Use Previous Action DataSends the output of the steps before this one to the agent along with the instruction
Structured outputReturns the answer as records with the Output fields you define, instead of as text

The agent receives one message built from these settings: your instruction first, then, with Structured output on, the list of fields to state for each item, and last, with Use Previous Action Data on, the previous steps' output as JSON. The agent runs as it does in a thread, with its own model, skills and tools, so an agent that can read files or query your data objects can do that here too.

The data passed from the previous steps is capped at 100,000 characters. A larger output is cut at that point, and the message tells the agent it was truncated. To ask about a large table, narrow it first with Filter Records, or let the agent read the data object itself with its own tools.

A new Ask Agent step starts with Use Previous Action Data off: turn it on when the agent should see the data from the steps before.

Get the answer as records

Turn on Structured output when the next step needs values rather than prose, for example to save what the agent found as records. The switch's own note sums it up: the agent answers as usual, then its answer is read into the fields and checked.

  1. Turn on Structured output. An Output fields list appears under it.
  2. Click Add field. The Add field dialog opens.
  3. Fill in the field:
    • Name: the column's name. To save the rows with Save Record, name it exactly as the target data object's attribute, for example Ongoing Charge.
    • Type: String, Number, Date, Boolean, Select or Multi-select, the same types as a data object attribute.
    • Description: what goes in the field. The model reads it, so say what to look for and in what form, for example The ongoing charge, in percent.
    • Options: for a Select or Multi-select, the values the field may take. At least one is required.
    • Required: fail the step when the answer does not state this field.
  4. Click Add. Repeat for each column you want.

Each field shows as a row with its type icon, its name and its description. Click a row to edit it in the Edit field dialog, or use its remove control (Remove field) to drop it.

AddCancelAdd fieldA column of the step's output, read from the agent'sanswer.Name*To save the rows with Save Record, name it as thedata object's attribute.Ongoing ChargeType*NumberDescription*What goes in the field. The model reads it, so saywhat to look for and in what form.The ongoing charge, in percent.RequiredFail the step when the answer doesn't state it.
Add field: name it as the attribute it will be saved to, pick a type and describe it.

How the answer becomes records

The answer is always read as a list: one record for each item the answer gives, and one record when the answer is about a single thing. Ask for "the ongoing charge of every share class in this KIID" and you get a row per share class; ask for "the fund's launch date" and you get one row.

  • The reading runs on the agent's own model, after the agent has answered, so it spends tokens like the agent's turn does.
  • A field the answer does not mention is left empty, unless it is Required.
  • When the answer does not fit the fields, for example a Required field is missing or a Select value is not one of its options, the step fails and its message names the field.
  • Each field must have its own name; two fields with the same name are rejected when you save.

With Structured output on, the step's output is a Table rather than Text, so it connects to Save Record and the other table steps without a type warning. See Action Inputs and Save records.

A common pattern for investment operations documents: File Received trigger, then Ask Agent with an agent that can read the file and Structured output fields named after your attributes, then Save Record into the target data object. The field names are what line the answer up with the attributes, so match them exactly.

Read the answer in a run

Open the run from the Executions tab and click the Ask Agent node. See Executions for how to open a run.

  • Agent activity shows the agent's reasoning and the tools it called. When the model reports it, a badge gives the step's total tokens, with the input and output split beside it.
  • Agent response shows the answer. A text answer renders as formatted text, the way it reads in a thread. A structured answer shows the agent's reply above the table of records it was read into, with a count such as 3 of 3 records.
  • When the reading failed, or the answer gave no items, the reply still shows above No data found, so you can see why no fields came back.

Good instructions

  • Say what the agent should look at and what it should return, not how to reason. The agent already has its own instructions.
  • With Structured output, put the detail in each field's Description rather than in the instruction. The descriptions travel with the fields to both the agent and the reading.
  • Keep each step to one question. Two Ask Agent steps in a chain are easier to read in a run than one that does two jobs.

Where to go next