UiPath Documentation
maestro
latest
false

Maestro user guide

Agent

What it does​

Runs an AI agent that you author on the canvas. You give it a model, instructions, tools, and context, and it reasons over your data to complete a task and return a result.

The node is labeled Autonomous Agent in the palette. Use it for AI-powered decisions, content generation, classification, extraction, or any step that benefits from reasoning rather than fixed logic.

An Autonomous Agent reasons in a loop. It reads the prompts, decides whether to call a tool or consult its context, incorporates what comes back, and repeats until it has an answer or reaches its iteration limit. You shape that loop with the model, prompts, and the resources you connect to the node's handles.

When to use this vs BPMN process​

SituationUse
You want to define the agent's model, prompts, and tools directly in this flowAutonomous Agent
You want to invoke an agent that's already published in your organizationBPMN process
You need a fixed, rule-based branch with no reasoningDecision or Switch

An Autonomous Agent is authored inline: its configuration lives on the node and travels with the flow. A BPMN process is a reference to an agent that's versioned and deployed separately.

Adding an agent​

Add the node, then configure it in the properties panel.

  1. Select the + button on an output handle, or open the node palette from the bottom toolbar.
  2. Select the Agent category, then Autonomous Agent. Flow adds the node and opens its properties panel.
  3. Configure the model and prompts as described below.

Result: The Autonomous Agent node is added to the canvas with its properties panel open, ready to configure.

Configuration reference​

FieldRequiredDefaultDescription
ModelNoOrganization default agent modelThe large language model (LLM) the agent uses. Select a model from the picker, which lists the models available to your organization.
System promptYesNoneThe agent's role and standing instructions: who it is and how it should behave. Write durable guidance that applies to every invocation, such as the agent's persona, constraints, and output expectations.
User promptYesNoneThe task for this invocation. Reference workflow data with expressions, for example $vars.start.output.request.
TemperatureNo0Sampling randomness, from 0 to 1. Lower values make responses more deterministic; higher values make responses more varied or creative.
Max. tokens per responseNo16384Maximum length of each model response. The ceiling depends on the selected model.
Max. iterationsNo25Maximum number of reasoning and tool-calling steps before the agent stops. Accepts values from 1 to 100.
GuardrailsNoNoneRules that constrain the agent's behavior and outputs, such as blocking disallowed content or keeping the agent within a defined scope. Guardrails apply to the agent as a whole.

Input and output variables​

Declare the data the agent exchanges with the rest of the flow in the Variables tab of the properties panel.

  • Input variables are values you pass into the agent and bind to workflow data. The agent can reference them while reasoning. New agents start with no input variables.
  • Output variables are the structured fields the agent returns. Every agent starts with one output variable, content, which holds the response text. Add more output variables to have the agent return structured data.

Each output variable you declare becomes a field on the agent's output object. Give each one a name and a type, then instruct the agent in the system prompt to populate it. The agent returns all declared fields together in a single structured output.

Resources​

An Autonomous Agent composes with resource nodes you connect to its handles. The node has three resource handles, each with its own label in the canvas: Tools, Context, and Escalations. Connect a resource to a handle, then configure that resource in its own properties panel. The resources travel with the flow.

Each handle accepts only its matching resource type. The canvas blocks connections that don't fit, so you can't, for example, wire a tool to the context handle.

Tools​

Connect tools to the Tools handle to give the agent capabilities it can call while reasoning. The agent decides during its loop whether and when to call each connected tool. Each tool carries a description that tells the agent what the tool is for, so write clear descriptions when a tool exposes one.

The tool types you can connect are:

  • Built-in tools, three ready-made tools described below.
  • Connector tools, which let the agent call an Integration Service operation, for example sending an email or creating a record in a downstream system.
  • RPA Workflow and API function tools, which let the agent invoke a published RPA process or API workflow as a tool.
  • Model Context Protocol (MCP) server tools, which expose the tools published on an MCP server.
Built-in tools​

Three built-in tools ship with Flow. Each is a self-contained resource you connect to the Tools handle and configure in its own panel.

  • Analyze Files: analyzes one or more files with an LLM to extract, synthesize, or answer questions about their content. Describe the files the agent will pass in and the analysis task to run on them.
  • Batch Transform: processes and transforms a CSV file row by row. Provide the source file, describe the per-row task, and define the output columns the tool adds. You can enable or disable web search grounding for the transformation.
  • Summarize: produces a synthesis across documents (up to 1,000 pages) with citations. Provide the source, describe what to synthesize, and choose the file extension. When the source is a PDF, you can turn citations on or off.

Context​

Connect a context resource to the Context handle to ground the agent in your data. The agent draws on this grounding data while reasoning instead of relying on the model alone. A context resource points at a context index in your organization.

Configure how the agent retrieves from the index, including the retrieval mode (semantic, structured, DeepRAG, or batch transform), the query, the number of results to return, a relevance threshold, and whether to include citations. To create a new context index, use the Create new Context action on the handle's add panel, which opens index creation in a new tab.

Escalation​

Connect the Escalations handle to route to a person when the agent reaches a case it shouldn't decide alone. The agent pauses, a human acts on the escalation, and the agent resumes with the outcome. You can attach either of two escalation resources:

  • Escalation: routes to an action app task. Configure the action app, recipients, notifications, the inputs passed to the app, and how the app's outcome maps back to the agent.
  • Action App Escalation: routes to a coded action app, with the same recipients, notification, input, and outcome-mapping configuration.

Both escalation resources are configured the same way. Choose Action App Escalation when your escalation target is a coded action app rather than a standard action app. Attaching either resource requires version 1.2 or later of the Autonomous Agent node.

Inputs and outputs​

Input​

The agent receives data from the upstream node through its input handle, and from any input variables you declare.

Output​

The agent returns an output object containing the output variables you declared. The default field is content, the response text. Access a field with $vars.<node>.output.<field>, for example:

$vars.agent1.output.content
$vars.agent1.output.content

If the agent fails, the node populates an error object instead. Refer to Error handling for the error shape and how to route on it.

{
  "output": {
    "content": "string. The agent's response text, plus any output variables you declared."
  },
  "error": "object. Populated only on failure. See Error handling."
}
{
  "output": {
    "content": "string. The agent's response text, plus any output variables you declared."
  },
  "error": "object. Populated only on failure. See Error handling."
}

Branching on the result​

Follow the agent with a Decision to route on what it returned:

Autonomous Agent → Decision ($vars.agent1.output.content.includes("approved"))
  → True:  continue processing
  → False: escalate or terminate
Autonomous Agent → Decision ($vars.agent1.output.content.includes("approved"))
  → True:  continue processing
  → False: escalate or terminate

Read a declared output field in a downstream Script node:

return $vars.agent1.output.content;
return $vars.agent1.output.content;

Examples​

Example 1: Classify an incoming request​

What it does: classifies a support request as a refund, a complaint, or a question, and returns the label as structured output.

System prompt:

You are a support triage assistant. Classify each request into exactly one category: refund, complaint, or question. Respond with only the category.
You are a support triage assistant. Classify each request into exactly one category: refund, complaint, or question. Respond with only the category.

User prompt:

Classify this request: $vars.start.output.request
Classify this request: $vars.start.output.request

Declare an output variable category (string). The agent returns:

{
  "output": {
    "category": "refund"
  }
}
{
  "output": {
    "category": "refund"
  }
}

Route on $vars.agent1.output.category with a downstream Switch.

Example 2: Resolve an invoice query end to end​

What it does: answers a customer's invoice question by reading the invoice, grounding the answer in policy, calling a workflow when it needs to act, and escalating when the amount exceeds a threshold.

Wire the agent's handles:

  • Context: a context index holding your billing policy, so the agent grounds its answer in approved guidance.
  • Tools: an Analyze Files built-in tool to read the attached invoice, and an RPA Workflow tool that issues a refund in the billing system.
  • Escalations: an Escalation resource that routes high-value cases to a reviewer in an action app.

System prompt:

You are a billing support agent. Use the billing policy in your context to answer invoice questions. Read the attached invoice before answering. If a refund is warranted and the amount is at or below 200, issue it with the refund workflow. If the amount exceeds 200, escalate for review instead of acting. Always return a structured result.
You are a billing support agent. Use the billing policy in your context to answer invoice questions. Read the attached invoice before answering. If a refund is warranted and the amount is at or below 200, issue it with the refund workflow. If the amount exceeds 200, escalate for review instead of acting. Always return a structured result.

User prompt:

Resolve this customer query: $vars.start.output.query
Invoice: $vars.start.output.invoiceFile
Resolve this customer query: $vars.start.output.query
Invoice: $vars.start.output.invoiceFile

Declare output variables resolution (string), refundIssued (boolean), and amount (number). A resolved case returns:

{
  "output": {
    "resolution": "Refund issued for duplicate charge.",
    "refundIssued": true,
    "amount": 48.5
  }
}
{
  "output": {
    "resolution": "Refund issued for duplicate charge.",
    "refundIssued": true,
    "amount": 48.5
  }
}

Follow the agent with a Decision on $vars.agent1.output.refundIssued to branch between a confirmation message and a follow-up path. The agent handles the over-threshold case itself by escalating, so that branch doesn't need extra logic in the flow.

Common issues​

An input validation error appears before you can debug. The Model, System prompt, and User prompt are all required. The node reports a validation error until each one is set.

An expression for a loop item doesn't resolve inside the agent. When you reference the current item of a Loop in a prompt, use the loop's current-item expression, for example $vars.loop1.currentItem.<field>. Referencing the wrong scope leaves the value unresolved at runtime.

The agent returns text when you expected structured data. By default the agent returns only content. Declare an output variable for each structured field you want, and instruct the agent in the system prompt to populate them.

A connected Batch Transform tool reports a validation error. Batch Transform requires at least one output column. Define the columns the tool should add before you debug the flow.

You can't connect an Action App Escalation to the agent. Action App Escalation requires version 1.2 or later of the Autonomous Agent node. Upgrade the node if the connection is blocked.

Was this page helpful?

Connect

Need help? Support

Want to learn? UiPath Academy

Have questions? UiPath Forum

Stay updated