AI Agent

1. Overview

The AI Agent component (ai-agent) runs an artificial intelligence agent inside the flow, capable of reasoning about one or more tasks, deciding what to do, and, if needed, using other platform components as "tools" during execution. It's suited for steps that need to interpret natural language, make more flexible decisions, or combine several sub-tasks with the help of a language model (LLM).

Use it when the logic can't be solved with fixed rules alone (Choice, ForEach, etc.) and benefits from the flexibility of an AI model — for example, interpreting a free-text request, summarizing documents, or orchestrating multiple context-dependent sub-tasks. Don't use it for simple deterministic logic, where traditional components are more predictable, cheaper, and faster.

It supports any language model compatible with the configured URL (allows pointing to custom/compatible providers via the modelUrl field), in addition to the provider's default model.

2. Prerequisites

A valid API key (apiKey) for the chosen AI model provider.
Knowledge of the exact model identifier to use (model).
If a custom or compatible provider is used (not the default one), the base URL of that service (modelUrl) is needed.
At least one task (tasks) defined with a name, description, and instruction.

3. Authentication and Connection

Field	Required	Type	Description	Example
`apiKey`	Yes	Expression	Authentication key used to access the AI model.	An expression that fetches the key from a secure variable
`model`	Yes	Text	Identifier of the AI model to use.	`"gpt-4o"`
`modelUrl`	No	Text	Custom base URL of the model provider, used when not hitting the default endpoint (e.g., a self-hosted compatible provider). If not informed, uses the model provider's default.	`"https://my-provider.example.com/v1"`

4. Configuration / Supported Operations

The AI Agent has a single operation: run the agent with an input prompt and return the generated response.

Agent configuration (defined once, when the flow starts)

Field	Required	Type	Description	Example
`name`	Yes	Text	Agent name.	`"SupportAgent"`
`description`	Yes	Text	Description of the agent's role, used internally to guide its behavior.	`"Agent responsible for handling customer questions"`
`taskOrchestration`	Yes	Text: `SEQUENTIAL`, `PARALLEL`, `LOOP`, or `DYNAMIC`	Defines how the configured tasks will run: sequentially, in parallel, in a loop, or dynamically (the agent itself decides the order and delegates tasks). Unrecognized values automatically fall back to `SEQUENTIAL`.	`"DYNAMIC"`
`tasks`	Yes	List of objects	List of tasks the agent can execute (see table below). Cannot be empty.	See practical example
`instructionPlanTasks`	No	Text	Additional instructions on how to coordinate tasks, used only in `DYNAMIC` mode. Default value: empty.	`"Prioritize tasks related to payments"`
`temperature`	No	Text (decimal number)	Controls the creativity/randomness of the model's responses. Default value: `"0.7"`. The closer to 0, the more deterministic; the closer to 1, the more creative.	`"0.3"`
`memoryType`	No	Text: `NO_MEMORY` or `IN_LOCAL_MEMORY`	Defines whether the agent remembers previous conversations from the same user. `NO_MEMORY` (default): each run is isolated. `IN_LOCAL_MEMORY`: keeps history in memory during the session.	`"IN_LOCAL_MEMORY"`
`sessionTimeoutMinutes`	No	Text (number)	Time, in minutes, that a memory session stays active without use. Default value: `"30"`.	`"60"`
`maxMessages`	No	Text (number)	Maximum number of messages kept in the session history. Default value: `"0"` (no limit in the default example).	`"20"`
`maxOutputTokens`	No	Text (number)	Limit on the size of the model's generated response, in tokens. Default value: `"4192"`.	`"2000"`
`returnTokens`	No	Text ("true"/"false")	If `true`, includes token consumption info in execution monitoring. Default value: `"false"`.	`"true"`

Each item in the `tasks` list

Field	Required	Type	Description	Example
`name`	Yes	Text	Task name (in `DYNAMIC` mode, matches the name of the agent that runs it).	`"summarizeDocument"`
`description`	Yes	Text	Description of what the task does.	`"Summarizes the content of a document"`
`instruction`	Yes	Text	Detailed instruction on how the task should be carried out (the task's "prompt").	`"Read the submitted text and produce a summary of up to 5 lines"`
`outputKey`	No	Text	Name of the key where this task's result is stored, so other tasks can reference it.	`"summary"`
`componentTools`	No	List of objects	Platform components the agent can use as tools during this task. Each item defines a component description, a body description, and the component's own configuration.	A database lookup component made available as a tool

Execution input (on each call to the agent during the flow)

Field	Required	Type	Description	Example
`prompt`	Yes	Expression	Text/question sent to the agent in this run.	`"What is the status of order 123?"`
`userId`	No	Expression	User identifier, used to keep memory per user when `memoryType` is enabled. If not informed, uses the step name as the identifier.	`"customer-456"`
`files`	No	Expression (JSON)	List of files to send along with the prompt (e.g., for multimodal tasks). Each item needs `name` (the name of the message property where the file is) and `mimeType` (the file's type).	`[{"name": "receipt", "mimeType": "application/pdf"}]`

Error behavior: if any required field is missing (name, model, API key, description, orchestration, tasks), the flow fails right at startup, before processing any run. If prompt is not informed in a run, that run fails. If a file referenced in files doesn't exist in the message, the run fails.

5. Practical Examples

Simple example: a single agent, with SEQUENTIAL orchestration and one task called "answerQuestion", configured to answer free-text customer questions. On each run, the flow sends the customer's question text in the prompt field and receives the response generated by the agent.

Component configuration (defined once, when the flow starts):

{
  "componentName": "ai-agent",
  "configurations": {
    "name": "SupportAgent",
    "model": "gpt-4o",
    "apiKey": "{$.secrets.openaiApiKey}",
    "description": "Agent responsible for handling customer questions",
    "taskOrchestration": "SEQUENTIAL",
    "tasks": [
      {
        "name": "answerQuestion",
        "description": "Answers general customer questions",
        "instruction": "Answer the customer's question clearly and politely"
      }
    ]
  }
}

Input (on each run, within the flow):

{
  "question": "What is the delivery time for zip code 01310-000?"
}

In this run, the component's prompt field is configured pointing to the question text:

{
  "prompt": "{$.body.question}"
}

Response:

{
  "question": "What is the delivery time for zip code 01310-000?",
  "response": "The estimated delivery time for that zip code is 3 to 5 business days."
}

Advanced example: an agent with DYNAMIC orchestration and three tasks ("lookupOrder", "checkStock", "generateResponse"), each with its own instruction. The "lookupOrder" task has a tool configured in componentTools that points to an internal system lookup component. The agent receives a prompt in natural language (e.g., "when is my order 123 arriving?"), decides on its own which tasks to run and in what order, using the configured tool when needed, and returns the final consolidated response. In this scenario, a file (files) with the customer's proof of purchase is also sent, for the agent to consider in its analysis.

Component configuration:

{
  "componentName": "ai-agent",
  "configurations": {
    "name": "SupportAgent",
    "model": "gpt-4o",
    "apiKey": "{$.secrets.openaiApiKey}",
    "description": "Agent responsible for checking orders and stock and replying to the customer",
    "taskOrchestration": "DYNAMIC",
    "tasks": [
      {
        "name": "lookupOrder",
        "description": "Looks up an order's status",
        "instruction": "Use the order lookup tool to fetch the status by the given number",
        "outputKey": "orderStatus",
        "componentTools": [
          {
            "componentDescription": "Looks up orders in the internal system",
            "bodyDescription": "Receives the order number and returns status and delivery estimate",
            "component": { "componentName": "http", "configurations": { "url": "https://api.internal.example.com/orders" } }
          }
        ]
      },
      {
        "name": "checkStock",
        "description": "Checks stock availability",
        "instruction": "Check whether the order's product is available in stock"
      },
      {
        "name": "generateResponse",
        "description": "Builds the final response for the customer",
        "instruction": "Combine the order and stock information into a clear response for the customer"
      }
    ]
  }
}

Input (run):

{
  "question": "when is my order 123 arriving?",
  "receipt": "<proof-of-purchase file, made available by a previous step>"
}

Component execution fields:

{
  "prompt": "{$.body.question}",
  "files": "[{\"name\": \"receipt\", \"mimeType\": \"application/pdf\"}]"
}

Response:

{
  "question": "when is my order 123 arriving?",
  "response": "Your order 123 is on its way and the estimated delivery date is 07/25."
}

6. Points of Attention

Requires at least one task configured in tasks.
Memory (IN_LOCAL_MEMORY) lives in the application's local memory; it isn't persisted to a database, so it's lost if the application restarts or the session expires.
DYNAMIC mode depends on the chosen AI model's ability to correctly interpret task coordination — result quality varies by model.
maxOutputTokens limits the size of the generated response.
Files sent in files need to be available in the message as a file, byte sequence, or text.

7. Common Errors and Troubleshooting

Error / Symptom	Likely Cause	How to Fix
"Agent name is required" / "Agent model is required" / "ApiKey is required" / "Agent description is required" / "taskOrchestration is required"	A required agent configuration field wasn't filled in.	Fill in all required fields listed in the configuration section.
"Agent tasks are required"	The `tasks` field is empty or wasn't informed.	Configure at least one task in `tasks`.
"Task name are required" / "Task description are required" / "Task instruction are required"	One of the tasks in `tasks` is missing `name`, `description`, or `instruction`.	Fill in all required fields for each task.
"Prompt not found"	The `prompt` field wasn't informed in the run.	Make sure the `prompt` message/expression resolves to a non-empty value.
"Failed to parse 'files' as JSON array"	The resolved value of `files` isn't a valid JSON list.	Check the format of the expression used in `files`.
"File entry requires 'name'" / "File entry '[name]' requires 'mimeType'"	An item in the `files` list is missing `name` or `mimeType`.	Fill in both fields in each `files` item.
"File [name] not found inside the execution context."	The file referenced in `files` isn't present in the message under that name.	Confirm a previous step in the flow made the file available under that exact name.
"Unsupported file type for [name]: [type]. Expected File, byte\[\] or String."	The value of the property referenced in `files` isn't a file, byte sequence, or text.	Make sure the data available in the message is in one of the supported formats.

1. Overview​

2. Prerequisites​

3. Authentication and Connection​

4. Configuration / Supported Operations​

Agent configuration (defined once, when the flow starts)​

Each item in the tasks list​

Execution input (on each call to the agent during the flow)​

5. Practical Examples​

6. Points of Attention​

7. Common Errors and Troubleshooting​