AI Integration
Enable AI assistants to intelligently select and execute your automation workflows
Overview
Qontinui Runner can be controlled by AI assistants like Claude through the MCP (Model Context Protocol) server. For AI to make intelligent decisions about which workflows to run and in what order, your workflows need rich, structured descriptions.
This guide explains how to write workflow descriptions that AI can understand, enabling autonomous development workflows where AI verifies code changes by running your automation.
Why Workflow Descriptions Matter
When you ask an AI assistant to “verify the login feature works,” it needs to understand:
- 1.Which workflows are relevant to login
- 2.What order to run them in
- 3.What prerequisites must be met
- 4.How to know if the verification succeeded
Good descriptions enable AI to autonomously run the right workflows, analyze results, and even fix issues it discovers.
Description Format
Use the existing description field in your workflow. No additional fields are needed. Structure your description with these sections:
[One-line summary of what this workflow does] Use when: [Conditions that indicate this workflow should be run] Verifies: [What features/functionality this workflow tests] Prerequisites: [What must be true before running] Produces: [What state changes or outputs result from running] Depends on: [Other workflows that must run first, if any] Success indicators: [How to know the workflow succeeded] Failure indicators: [Signs that something went wrong]
| Field | Required | Description |
|---|---|---|
| Summary | Yes | First line, brief description of the workflow's action |
| Use when | Yes | Conditions/situations when this workflow is appropriate |
| Verifies | Recommended | Features or functionality being tested |
| Prerequisites | Recommended | Required state before running (apps open, logged in, etc.) |
| Produces | Optional | Side effects or outputs (new data, state changes) |
| Depends on | Optional | Other workflow names that must run first |
| Success indicators | Optional | How to verify success (visible elements, data created) |
| Failure indicators | Optional | Signs of failure (error messages, missing elements) |
Examples
Example 1: Navigation Workflow
Clicks Build > State Machine in the website navigation menu to open the State Machine Builder page. Use when: Need to test or verify the State Machine Builder feature, or after making changes to state machine related code. Verifies: Navigation menu works, State Machine Builder page loads, canvas renders correctly. Prerequisites: Website running on localhost:3001, user logged in to the application. Success indicators: State Machine canvas is visible, no console errors, page title shows "State Machine". Failure indicators: 404 error, blank page, console errors, navigation menu not responding.
Example 2: Data-Producing Workflow
Opens the runner's extraction panel and performs a new web extraction on the currently visible application. Use when: Need to create new extraction data for testing, or to verify the extraction feature works after code changes. Verifies: Runner extraction panel opens, screenshot capture works, element detection runs, states are identified. Prerequisites: Qontinui Runner is running, target application is visible on screen, a project is loaded. Produces: New extraction data (states, images, elements) in the current project configuration. Success indicators: Extraction completes without errors, at least one state is detected, images are captured. Failure indicators: Extraction hangs, no states detected, "0 items found" in logs, screenshot capture fails.
Example 3: Workflow with Dependencies
Navigates to the Web Extraction page in the website and verifies that extraction data is displayed correctly. Use when: After creating new extraction data, need to verify it appears correctly in the web interface. Verifies: Web Extraction page loads, extraction data is displayed, images render correctly, state list is populated. Prerequisites: Website running, user logged in, extraction data exists in the project. Depends on: "Start New Web Extraction" (if no extraction data exists yet) Success indicators: Extraction data visible in the UI, images load, state count matches expected. Failure indicators: Empty state list, broken images, "No extractions found" message, API errors.
Multi-Workflow Sequences
For complex verification tasks, AI assistants can chain multiple workflows together. The Depends on field helps AI understand the correct order.
Example: End-to-End Extraction Verification
When you ask AI to “verify web extraction works end-to-end,” it will:
- 1Load the workflow configuration and read all descriptions
- 2Find relevant workflows: “Start New Web Extraction” and “Navigate to Web Extraction Page”
- 3Check dependencies: Page verification depends on extraction data existing
- 4Run “Start New Web Extraction” first, then “Navigate to Web Extraction Page”
- 5Analyze results using success/failure indicators and report findings
Best Practices
Do
- Write the summary as a clear, action-oriented first line
- Be specific about prerequisites (which services must be running)
- List concrete success/failure indicators AI can verify
- Use consistent terminology across workflows
- Reference specific UI elements, page names, and features
- Include the workflow name in “Depends on” exactly as written
Don't
- Leave descriptions empty or vague (“Tests stuff”)
- Assume AI knows your application's structure
- Forget to mention required login state
- Use ambiguous terms without context
- Skip the “Use when” field - it's essential for AI selection
- Omit failure indicators - AI needs to know what went wrong
How AI Uses These Descriptions
When you ask an AI assistant like Claude to run automation, it follows this process:
Load Configuration
Reads the workflow configuration file to see all available workflows
Parse Descriptions
Extracts "Use when" and "Verifies" fields to understand each workflow's purpose
Match Request
Compares your request against workflow purposes to find relevant matches
Check Dependencies
Reads "Depends on" fields to determine correct execution order
Execute Workflows
Runs workflows in sequence via the MCP server
Verify Results
Checks success/failure indicators in logs and screenshots
Report or Fix
Reports findings and can autonomously fix issues discovered during verification
MCP Server Integration
AI assistants interact with Qontinui Runner through the MCP (Model Context Protocol) server. The key commands are:
# Load a workflow configuration
mcp__qontinui__load_config("/path/to/config.json")
# Check what workflows are available
mcp__qontinui__get_loaded_config()
# Run a specific workflow
mcp__qontinui__run_workflow("Navigate to State Machine Builder")
# Run on a specific monitor
mcp__qontinui__run_workflow("My Workflow", monitor="left")The MCP server is available as qontinui-mcp on PyPI and works with Claude Desktop, Claude Code, Cursor, and other MCP-compatible tools.
Next Steps
Ready to enable AI-powered automation? Here's how to get started:
- 1.Review your existing workflows and add structured descriptions (see guide)
- 2.Install the MCP server:
pip install qontinui-mcp - 3.Configure your AI assistant to use the MCP server
- 4.Ask AI to “verify [feature] works” and watch it run the right workflows