- Introduction
- Getting started
- Process modeling
- Process implementation
- Process operations
- Process monitoring
- Process optimization
- Reference information
Maestro user guide
Agents are represented in Maestro BPMN workflows as Service Tasks. When your process calls a Service Task, Maestro invokes the corresponding agent with the required input parameters for the specific process instance.
Agents return output data to Maestro, which is used to determine the next steps in the workflow. You can configure agents to report the tools used, decisions made, and trace data to support debugging and transparency.
Agents can be:
- Built directly within the UiPath Platform (low-code or coded)
- Connected via external APIs or Integration Service
- Triggered through events or signals based on workflow logic
Watch a real-world example: UiPath Maestro: The brain behind seamless, transparent loan automation.
- Prebuilt connectors for services like Salesforce, Microsoft 365, and Google Workspace
- Custom connector builder to expose any REST API to UiPath Platform
- Unified credential and connection management
Use Integration Service to enable Maestro to send/receive data from agents or systems not natively hosted in UiPath. Learn more about Integration Service.
Maestro is vendor-neutral. You can orchestrate work across your preferred external AI agents—without rebuilding your processes—by using UiPath Integration Service connectors.
You can orchestrate:
- Proprietary AI services
- External decision engines
- Microservices or bots hosted on other platforms
Maestro invokes these agents by calling REST endpoints and expects a response payload with structured data.
At design time, add a Service task, choose Start and wait for external agent, and configure the agent activity from the selected connector. At runtime, Maestro sends the prompt and context to the agent and waits for the response. You map that response to variables to drive gateways, assignments, and subsequent actions.
Prefer Integration Service connectors when they exist. Use API workflows when you need API-level connectivity (early APIs, evolving schemas, or streaming responses). Define requests and outputs declaratively, parse JSON without custom code, and pass results into your Maestro process.
- Connector: Supported system, stable schema, managed authentication, best long-term choice.
- API Workflow: New or unsupported API, changing response shapes, or streaming-only output.
- Snowflake Cortex - API workflow: Handle the Cortex Agent’s streaming output, assemble it into a usable response, and return structured JSON for downstream automation.
- Databricks Genie - API workflow: Start a conversation, poll message status until COMPLETED, extract the generated SQL (attachment_id), execute it, and return the answer.
In Maestro, agents are treated as participants in a business process. Within a BPMN workflow, agents are represented using Service tasks, which can invoke both UiPath-hosted and external agents. Each agent task can be configured with specific input and output parameters, which allow Maestro to pass context-aware data to the agent and receive structured results in return.
Refer to Tasks in BPMN modeling for an overview of Service Tasks in Maestro.
Agent execution modes
Agent behavior is defined in the Properties panel of a Service task. You can configure the task to call a UiPath agent or an external agent, depending on your business needs.
Start and wait for agent
Use this option to invoke an agent deployed in your UiPath tenant. This includes:
- Low-code agents created using tools like Agent Builder.
- Coded agents developed in Python or other languages and deployed to Orchestrator.
Start and wait for external agent
Use this option to connect to third-party or external systems. You must specify:
- Connector: The integration target (e.g., CrewAI, Salesforce, or another service)
- Connection: A configured instance
of the connector, representing either a specific agent or a context-specific credential
set.
Note: You can use the same agent with different permissions or behaviors by defining multiple connections.
Inputs and outputs
Inputs and outputs for agents are configured in the same way as other Maestro task types.
- Inputs: Variables or expressions passed to the agent at runtime.
- Outputs: Variables populated from the agent’s JSON response.
{
"key1": "value1",
"key2": "value2"
}{
"key1": "value1",
"key2": "value2"
}
The agent must return a JSON response using the same parameter names expected by Maestro. These values are mapped to process variables using the Output > Response section in the task's Properties panel.
Input and output examples
Example Inputs (from Maestro to Agent):
| Parameter | Description |
|---|---|
role | Role or context for the task (e.g., validation vs. summarization) |
prompt | Instruction provided to the agent, often including process-specific data |
tools | List of tools the agent may use to complete the task |
user_id | Unique identifier shared between the process and the agent context |
Example prompt:"Complete loan validation for {loan_application_number}. Respond in JSON format using the parameter 'loan_application_status'."
Example outputs (from agent to Maestro)
| Parameter | Description |
|---|---|
conversation_id | Reference to the dialogue or interaction session |
loan_application_status | Status result returned by the agent |
tokens_used | Metadata about resource usage |
