> ## 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.

<Steps>
  <Step title="Add a Service Task">
    Add a Service Task node to your process where you want to trigger the agent.
  </Step>

  <Step title="Configure the action">
    Add a **Start Integration Workflow** action and select your agent workflow.
  </Step>

  <Step title="Map input data">
    Configure which process data to send to the agent (documents, text, parameters).
  </Step>

  <Step title="Handle the response">
    Map the agent's response back to process variables.
  </Step>
</Steps>

<Card title="Start Integration Workflow" icon="play" href="/5.9/docs/building-blocks/actions/start-integration-workflow">
  Detailed configuration reference
</Card>

### 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 title="Custom Agent Node" icon="robot" href="/5.9/docs/platform-deep-dive/integrations/custom-agent-node">
  Integration Designer agent configuration
</Card>

## 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:

```javascript theme={"system"}
// Example input mapping
{
  "documentId": "${processInstanceData.uploadedDocument.fileId}",
  "applicantName": "${processInstanceData.application.fullName}",
  "extractionType": "loan_application"
}
```

### Receiving agent responses

Map agent output back to process variables:

```javascript theme={"system"}
// Example output mapping
{
  "extractedData": "processInstanceData.extraction",
  "confidence": "processInstanceData.extractionConfidence",
  "processingTime": "processInstanceData.agentMetrics.duration"
}
```

## Error handling

<AccordionGroup>
  <Accordion title="Timeout handling" icon="clock">
    Configure timeouts for agent calls. If an agent doesn't respond in time, route to a fallback path or retry.
  </Accordion>

  <Accordion title="Low confidence results" icon="question">
    Check confidence scores in gateway conditions. Route low-confidence results to human review.
  </Accordion>

  <Accordion title="Agent failures" icon="triangle-exclamation">
    Use boundary error events to catch agent failures and handle them gracefully.
  </Accordion>
</AccordionGroup>

## Best practices

<CardGroup cols={2}>
  <Card title="Async processing" icon="clock">
    Use async patterns for long-running agent tasks to avoid blocking the process
  </Card>

  <Card title="Idempotency" icon="repeat">
    Design agent calls to be safe to retry in case of failures
  </Card>

  <Card title="Monitoring" icon="chart-line">
    Track agent call metrics (latency, success rate, confidence scores)
  </Card>

  <Card title="Fallbacks" icon="life-ring">
    Always have a fallback path for when agents fail or return uncertain results
  </Card>
</CardGroup>

## Related resources

<CardGroup cols={2}>
  <Card title="Passing data between nodes" icon="arrow-right-arrow-left" href="/5.9/docs/building-blocks/process/passing-data-between-nodes">
    How node outputs land in process variables and how downstream nodes read them
  </Card>

  <Card title="Chat interface" icon="comments" href="./chat-interface">
    User-facing agent interaction
  </Card>

  <Card title="Integration Designer" icon="diagram-project" href="/5.9/docs/platform-deep-dive/integrations/integration-designer">
    Build complex integration workflows
  </Card>

  <Card title="Agent Builder" icon="robot" href="../agent-builder/overview">
    Create custom agents
  </Card>

  <Card title="Service Tasks" icon="gear" href="/5.9/docs/building-blocks/node/task-node">
    BPMN task configuration
  </Card>
</CardGroup>