---
name: multi-agent-workflow-execution
version: 1.0.0
description: Execute multi-agent AI workflows defined in YAML blueprints by creating
  sessions, submitting user prompts, and polling for completion until final answers
  are returned.
inputs:
- Blueprint ID or name (to identify the workflow to execute)
- User shortcut (authentication identifier for the user)
- User question or prompt (input to the workflow)
- Base URL of the UnifAI API (endpoint for session management)
- Polling interval (seconds between status checks during execution)
steps:
- Resolve the blueprint ID from either direct ID or name lookup via the API, handling
  cases where the blueprint is not found or not unique
- Create a new session from the resolved blueprint using the session creation endpoint
- Submit the session with the user's prompt to start the multi-agent workflow execution
- Poll the session status at regular intervals until the session completes, fails,
  or is cancelled
- Retrieve and return the final answer from the completed workflow
outputs:
- Final workflow result or answer (text or structured data)
- Session status (completed, failed, or cancelled)
- Error details if the workflow execution fails or times out
tags: []
metadata:
  source_repo: https://github.com/redhat-community-ai-tools/UnifAI.git
  extracted_at: ''
  confidence: 0.95
---

# multi-agent-workflow-execution

Execute multi-agent AI workflows defined in YAML blueprints by creating sessions, submitting user prompts, and polling for completion until final answers are returned.

## Setup

**Dependencies:**

```text
pip install requests urllib3 python-langgraph temporalio
```

**Setup steps:**

1. Install Python 3.11+ and required packages (requests, langgraph, temporalio)
1. Configure API base URL and user credentials in environment variables or config
1. Define or select a blueprint from the available workflows in the system
1. Run the execution_workflow.py script with blueprint ID/name and user prompt

## Key Files

- `scripts/execution_workflow.py - Main workflow execution script`
- `multi-agent/lib/mas/engine/ - LangGraph-based orchestration modules`
- `multi-agent/lib/mas/elements/ - Node definitions (custom_agent_node, merger_node, etc.)`
- `multi-agent/lib/mas/blueprints/ - Blueprint resolution and validation logic`

## Steps

1. Resolve the blueprint ID from either direct ID or name lookup via the API, handling cases where the blueprint is not found or not unique
2. Create a new session from the resolved blueprint using the session creation endpoint
3. Submit the session with the user's prompt to start the multi-agent workflow execution
4. Poll the session status at regular intervals until the session completes, fails, or is cancelled
5. Retrieve and return the final answer from the completed workflow

## Implementation Details

```python
resolve_blueprint_id() - Resolves blueprint by ID or name lookup with error handling
```

```python
create_session() - Creates a new session from a blueprint via POST /user.session.create
```

```python
submit_session() - Submits user prompt to start workflow via POST /user.session.submit
```

```python
poll_session_status() - Polls session.stream.status at configurable intervals
```

```python
get_final_answer() - Retrieves final output via GET /session.chat.get
```

## Inputs

- Blueprint ID or name (to identify the workflow to execute)
- User shortcut (authentication identifier for the user)
- User question or prompt (input to the workflow)
- Base URL of the UnifAI API (endpoint for session management)
- Polling interval (seconds between status checks during execution)

## Outputs

- Final workflow result or answer (text or structured data)
- Session status (completed, failed, or cancelled)
- Error details if the workflow execution fails or times out

## Failure Modes

- Blueprint not found or not unique - script exits with an error listing available blueprints
- Session creation fails - may be due to invalid blueprint ID, authentication issues, or rate limiting
- Session submission fails - could be due to network issues, invalid parameters, or API rate limits
- Polling loop times out - session may be stuck in a long-running state without progress
- Final answer retrieval fails - could be due to session cleanup or network issues after completion

## Source

Extracted from: [https://github.com/redhat-community-ai-tools/UnifAI.git](https://github.com/redhat-community-ai-tools/UnifAI.git)
Confidence: 0.95