> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# BPMN integration

> Trigger AI agents from BPMN workflow nodes for automated document processing, decisions, and content generation.

Integrate AI agents directly into your BPMN processes to automate document processing, make intelligent decisions, and generate content without user interaction.

## Overview

BPMN integration allows you to:

* **Automate document processing** in the background
* **Make AI-powered decisions** at process gateways
* **Generate content** automatically within workflows
* **Validate data** using AI analysis

## Integration methods

### Method 1: Start Integration Workflow action

Use the **Start Integration Workflow** action to call an AI agent from any BPMN node.

**1. Add a Service Task**

Add a Service Task node to your process where you want to trigger the agent.

**2. Configure the action**

Add a **Start Integration Workflow** action and select your agent workflow.

**3. Map input data**

Configure which process data to send to the agent (documents, text, parameters).

**4. Handle the response**

Map the agent's response back to process variables.

> [card] [Start Integration Workflow](https://docs.flowx.ai/6.x/docs/building-blocks/actions/start-integration-workflow.md)
>
> Detailed configuration reference

### Method 2: Custom Agent Node

For complex agent interactions, use the Custom Agent Node in Integration Designer:

| Feature | Start Integration Workflow | Custom Agent Node |
| - | - | - |
| **Setup complexity** | Simple | More complex |
| **Flexibility** | Standard call/response | Full workflow control |
| **Error handling** | Basic | Advanced |
| **Best for** | Single agent calls | Multi-step AI workflows |

> [card] [Custom Agent Node](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/custom-agent-node.md)
>
> Integration Designer agent configuration

## Common patterns

### Document extraction

Extract data from uploaded documents and continue the process with structured data.

```
User uploads document → Service Task calls extraction agent →
Agent returns structured data → Process continues with data
```

**Configuration:**

* Input: Document file ID or content
* Output: Extracted fields mapped to process variables
* Error handling: Route to manual review if confidence is low

### Automated decisions

Use AI to make or recommend decisions at process gateways.

```
Process reaches gateway → Service Task calls decision agent →
Agent returns recommendation → Gateway routes based on result
```

**Configuration:**

* Input: All relevant process data
* Output: Decision result and confidence score
* Human override: Optional review step for low-confidence decisions

### Content generation

Generate documents, emails, or reports automatically.

```
Process collects data → Service Task calls generation agent →
Agent produces content → Content stored/sent
```

**Configuration:**

* Input: Template reference and data to include
* Output: Generated content (text, HTML, or document)
* Review: Optional human approval before sending

## Input/Output mapping

### Sending data to agents

Map process variables to agent input in the Start Integration Workflow action's **Input Mapping**: select each process data attribute as the source path for an agent workflow input, for example `uploadedDocument.fileId` to `documentId`.

With **Legacy mapping** turned on, the input is a JSON template. Placeholders name process data paths from the root of the process data, with no prefix:

```json theme={"dark"}
{
  "documentId": "${uploadedDocument.fileId}",
  "applicantName": "${application.fullName}",
  "extractionType": "loan_application"
}
```

### Receiving agent responses

Map agent output back to process variables on a **Receive Message Task** after the node that starts the agent. In its **Data Stream**, set the source to **Workflow** and select the agent workflow, then map each End node's output with **Output Mapping**, for example to `extraction`. With **Legacy Mapping** turned on, set a single **Key Name** instead.

## Error handling

> [accordion] Timeout handling
>
> Configure timeouts for agent calls. If an agent doesn't respond in time, route to a fallback path or retry.

> [accordion] Low confidence results
>
> Check confidence scores in gateway conditions. Route low-confidence results to human review.

> [accordion] Agent failures
>
> Use boundary error events to catch agent failures and handle them gracefully.

## Best practices

> [card] Async processing
>
> Use async patterns for long-running agent tasks to avoid blocking the process

> [card] Idempotency
>
> Design agent calls to be safe to retry in case of failures

> [card] Monitoring
>
> Track agent call metrics (latency, success rate, confidence scores)

> [card] Fallbacks
>
> Always have a fallback path for when agents fail or return uncertain results

## Related resources

> [card] [Passing data between nodes](https://docs.flowx.ai/6.x/docs/building-blocks/process/passing-data-between-nodes.md)
>
> How node outputs land in process variables and how downstream nodes read them

> [card] [Chat interface](https://docs.flowx.ai/6.x/ai-platform/using-agents/chat-interface.md)
>
> User-facing agent interaction

> [card] [Integration Designer](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/integration-designer.md)
>
> Build complex integration workflows

> [card] [Agent Builder](https://docs.flowx.ai/6.x/ai-platform/agent-builder/overview.md)
>
> Create custom agents

> [card] [Service Tasks](https://docs.flowx.ai/6.x/docs/building-blocks/node/task-node.md)
>
> BPMN task configuration


## Related topics

- [Passing data between nodes](https://docs.flowx.ai/6.x/docs/building-blocks/process/passing-data-between-nodes.md)
- [Using AI agents](https://docs.flowx.ai/6.x/ai-platform/using-agents/overview.md)
- [AI in FlowX](https://docs.flowx.ai/6.x/ai-platform/ai-in-flowx.md)
- [Chat interface](https://docs.flowx.ai/6.x/ai-platform/using-agents/chat-interface.md)
- [Process nodes (BPMN)](https://docs.flowx.ai/6.x/docs/building-blocks/node/node.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.