Building blocks: agents
In short: with an agent step you have an AI agent of the account do work in the workflow: write the reply to a customer message (agent.reply), choose from your list of options (agent.choose), carry out a task with its own tools (agent.task), or process what the customer supplies into their cases (case.process). This article lists all inputs, exits and output fields for each block.
Where to find this
Account > Workflows, open a workflow, Add step, group Agents. In the editor, agent.reply, agent.choose and agent.task are one agent step: at the top you choose under Task what the agent does. Switching keeps the chosen agent and the task. Who: from the role Organisation admin.
An agent step in the workflow editor with the Task choice at the top (Write the reply, Choose from a list, Carry out a task), below it Agent, the input fields and for each exit the If choice.
Which agent works
Every agent block has the optional input agent (Agent): the id of an enabled AI agent of the account. If you leave it out (in the editor By the agent routing), this applies:
agent.reply: the agent working on the conversation (the agent that wrote the last reply), otherwise the agent named by the organisation’s answering workflows.agent.chooseandagent.task: the agent named by the organisation’s answering workflows.
By “the agent named by the answering workflows” aishaa means: of the active workflows that write replies, the oldest one whose agent.reply step names an enabled agent. You cannot delete an agent that is in a workflow step.
agent.reply: Write the reply
An AI agent writes the reply to the customer message, as a proposal in the ticket, as aishaa always does. If a person has allowed the agent to send by itself on the topic of the message and every guardrail holds, the reply goes out straight away.
Only works with the trigger message.understood. With a different trigger you cannot publish the workflow.
Input
| Name | Label | Type | Required | Explanation |
|---|---|---|---|---|
agent |
Agent | Agent | no | The id of the agent that writes. Left out: see “Which agent works”. |
instruction |
Extra instruction for this step | LongText | no | An extra instruction for this route only, in the organisation’s own words. At most 2,000 characters. |
send |
Send by itself | Choice | no | where_granted (default, Where the agent may (earned and allowed per topic)): a reply goes out by itself where a person allowed this agent to do so on the topic and every guardrail holds. propose (Never: always a proposal): every reply from this route stays a proposal. |
Exits
| Exit | Label | When |
|---|---|---|
drafted |
Draft written | The reply is in the ticket as a proposal. Also if it was sent by itself and you have not connected sent. |
sent |
Sent by itself | The reply went out by itself. Only if you connect this exit in the step. |
not_needed |
No reply needed | The message does not call for a reply. |
failed |
failed | No reply came: writing failed, or there was still no reply after six hours. |
Output fields
| Field | Label | Content |
|---|---|---|
draft |
Draft | The text of the proposed reply. |
replyNeed |
Reply needed | Required, NotRequired or Unclear. |
reason |
Reason | Why it ended this way (for example why it failed). |
sentByItself |
Sent by itself | true if the reply was sent by itself. |
heldBack |
Why it stayed a proposal | The reason why sending by itself did not go ahead, if that is the case. |
How the step runs
- The step starts the reply and waits until it is ready. It checks again by itself every 20 minutes and gives up after six hours (
failed). - If writing is waiting for an action that a colleague has to approve, the step keeps waiting.
- If the message is answered outside the workflow (for example by a colleague) before the step is finished, the run ends without an exit.
- If another workflow is already writing a reply to the same message, this step writes its own proposal next to it. Whoever sends sees that another workflow already wrote to the customer. So put all of the answering of a message in one workflow.
- A reply that would go out by itself still waits for a colleague if another workflow wrote to the customer about the same message.
When to use it: in every workflow that answers customer messages, at the end of every route that should get a reply. Give a route with its own emphasis an instruction instead of a separate agent. More about trust and sending by itself is in Trust and letting an agent send by itself.
When not to: for a fixed message that does not need to be written by an agent (an acknowledgement of receipt). Use message.send for that.
agent.choose: Choose from a list
An AI agent reads what the step gives it (by default the customer message) and chooses one of your options, or other. Every option is its own route. With labels the step immediately puts the label of the chosen option on the conversation: sorting and labelling in one step.
Input
| Name | Label | Type | Required | Explanation |
|---|---|---|---|---|
agent |
Agent | Agent | no | The agent that chooses; its instructions count. |
options |
Options | Cases | yes | The options, short words such as ["retour", "levering"]. 1 up to and including 30, each at most 80 characters, all different (capitals do not count), not other. Every option is an exit. |
explanations |
What each option means | CaseNotes | no | For each option what it means, at most 400 characters, for example {"retour": "wants to send something back"}. The agent chooses based on this. |
multiple |
May choose several | Boolean | no | true: the agent may choose every option that clearly applies (output choices). The route follows the best one. |
labels |
Label per option | CaseLabels | no | For each option the id of a label that is put on the conversation if that option is chosen, for example {"retour": 12}. |
instruction |
How to choose | LongText | no | How the agent should choose, in the organisation’s own words. |
input |
What the agent reads | LongText | yes | Usually {{trigger.message.text}}. At most the first 20,000 characters count. |
Exits: every value from options, plus other (other). The agent chooses other if no option fits well; a wrong route is worse than “other”. If input is empty, the step goes via other.
Output fields
| Field | Label | Content |
|---|---|---|
choice |
Choice | The chosen option, or other. |
choices |
All choices | A list of all chosen options, the best first. Without multiple only the choice; empty with other. |
reason |
Reason | Why, briefly, in the language of what the agent read. |
confidence |
How sure | 0 up to and including 100. |
Good to know
- Labels per option are only put on the conversation if the run is about a conversation; otherwise the step fails. A label that is already there stays.
- The agent treats what it reads as material, never as an instruction to itself.
- Works with every trigger, as long as
inputgives it something to read.
When to use it: to sort customer messages before you reply, label or forward per route. Keep the options short and give every option an explanation.
When not to: if you can route on a fixed value (channel, topic id, status). Use flow.switch or flow.condition then: they cost no AI and are always predictable.
agent.task: Carry out a task
An AI agent carries out one task with its own tools, such as “look up the order and prepare a refund if it arrived damaged”. What it looks up, it uses. An action it prepares is always a proposal for a colleague. Which tools the agent has depends on its skills.
Input
| Name | Label | Type | Required | Explanation |
|---|---|---|---|---|
agent |
Agent | Agent | no | The agent that carries out the task; its instructions and tools count. |
instruction |
The task | LongText | yes | The task in the organisation’s own words, at most 4,000 characters. |
input |
What the agent reads | LongText | no | What the agent works with, usually {{trigger.message.text}}. |
Exits
| Exit | Label | When |
|---|---|---|
done |
done | The task has been done. |
proposed |
Waiting for a colleague | The agent prepared one or more actions; a colleague decides on them in To do. The run does not wait for that. |
not_possible |
Not possible | The task could not be done. |
Output fields
| Field | Label | Content |
|---|---|---|
summary |
Summary | What the agent did, briefly. |
details |
Details | More explanation. |
actionIds |
Proposed actions | The ids of the proposed actions. |
Good to know
- Without an agent on the step and without an answering workflow that names an agent, the step fails. A disabled or deleted agent also makes the step fail.
- If the run is about a conversation, the agent works with that conversation and the trigger’s message.
When to use it: for work in which the agent has to find out for itself what is needed and can do so with its skills. When not to: if you know exactly which data you need and which action follows. Then build a fixed chain of plugin.read and plugin.action: more predictable and easier to check.
case.process: Update cases
Processes what the customer supplies (documents, details) into their open cases, against what each case still needs. Does nothing for a customer without open cases.
- Input: none.
- Exits: none; continues with
next. - Output fields: none.
- Only works with the trigger
message.understood. With a different trigger you cannot publish the workflow.
When to use it: in an organisation that works with cases, in the workflow that processes customer messages, at the point where you want supplied documents to go into the case.
Good to know
- On a trial run,
agent.chooseandagent.taskreally make an AI call (agent.choose) or let you choose how it ends (agent.task). For a message from the past,agent.replyshows what the agent proposed at the time and whether it would now have been sent by itself. - An
agent.replystep finishes the reply that belongs to the message that was read. It does not start a new analysis. - If a step goes wrong, decide for yourself what happens: connect
failed, or give the step anonError. A message that no workflow answers is for a colleague.