Agentic Workflows Execution

Overview

This documentation provides comprehensive instructions for executing agentic workflows within the Arcanna platform. Agentic workflows enable automated agent-based processing of data and events through four primary execution methods: on-demand execution, direct API calls, pipeline integration via code blocks within Flows, and MCP (Model Context Protocol) Server integration.

Prerequisites

Before executing agentic workflows, ensure you have:

Access to the Arcanna platform with appropriate permissions
Created at least one agentic workflow in the system
For programmatic/API access:
- A valid Management API Key
- The workflow ID of the target workflow

Execution Methods

Method 1: On-Demand Execution

On-demand execution allows users to manually trigger and interact with agentic workflows through the Arcanna user interface.

Steps to Execute On-Demand

Access the "Agentic Workflows" page from the main navigation
Access the Sessions Page
- Upon clicking a workflow card, you will be redirected to the Sessions page
- The Sessions page provides a comprehensive view of workflow executions
Managing Sessions
- Left Panel: Historical sessions list
  - Displays all saved sessions by their unique Session ID
  - Sessions are listed chronologically
  - Click on any session ID to view the complete chat history with agents that you can also continue
- Main Chat Area: Active session interface
  - Start a new session by clicking the "New Session" button
  - View real-time responses from the agentic workflow
  - Continue conversations of previously saved sessions
Reviewing Past Sessions
- Click on any session ID in the left panel
- View the complete conversation history

Method 2: Direct API Execution

Direct API execution allows you to trigger agentic workflows programmatically from any external system or application that can make HTTP requests. This method provides the most flexibility for integration with third-party systems.

Setup Requirements

Management API Key
- Navigate to API Keys in Arcanna
- Generate a new Management API Key with appropriate permissions
- Store the key securely for authentication
Workflow ID
- Obtain the unique identifier of the agentic workflow you want to execute
- This ID is typically visible in the workflow URL or can be retrieved from the workflows list
Agentic API Endpoint
- Identify your Arcanna agents exposer API instance URL
- The base URL format: http://<ARCANNA_VM_IP>:9888/

API Reference

Endpoint

POST /api/v1/agents-workflow/run/{workflow_id}

Headers

Header	Type	Required	Description
Content-Type	string	Yes	Must be `application/json`
Accept	string	Yes	Must be `application/json`
X-Arcanna-Api-Key	string	Yes	Your Management API Key

Request Body

{
  "session_id": "string (optional)",
  "input": "string or object",
  "wait_for_completion": false
}

Parameters Explained

session_id: Optional. If provided, the workflow will continue an existing session; otherwise, a new session will be created.
input: The data or prompt to be processed by the agentic workflow.
wait_for_completion: Synchronous execution flag. If set to true, the API will wait for the workflow to complete before returning a response. If false, it will return the session id immediately but not the events.

Response

{
  "session_id": "uuid-string",
  "workflow_result": "null / [ /* array of SessionEvent objects, may be empty */ ]"
}

Example

curl -X POST "http://<ARCANNA_VM_IP>:9888/api/v1/agents-workflow/run/10" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Arcanna-Api-Key: your-management-api-key" \
  -d '{
    "input": {
      "alert_type": "phishing", 
      "severity": "high",
      "description": "Suspicious email detected"
    },
    "wait_for_completion": false
  }'

Method 3: Pipeline Integration via Code Blocks

Pipeline integration enables automated workflow execution within Arcanna use cases through code blocks in the Flows page. This method is specifically designed for integrating agentic workflows into your data processing pipelines, allowing for automated triggering based on specific conditions or events during the flow execution.

info

This method utilizes the Direct API Execution approach (Method 2) within the Arcanna pipeline context. For detailed API reference, parameters, and response formats, refer to Method 2 documentation above.

Setup Requirements

Identify Workflow ID and API Key
- Follow the same setup requirements as outlined in Method 2
- Ensure you have the workflow ID and Management API Key ready
Configure Environment Variables

In your Arcanna environment, ensure the following variables are configured:
```
ARCANNA_MANAGEMENT_KEY = "your-management-api-key"
AGENTIC_URL = "http://<ARCANNA_VM_IP>:9888/"
```

Implementation Steps

Navigate to Flows Page
- Go to your specific use case
- Navigate to the Flows page within that use case
- This is where you'll integrate the agentic workflow into your data processing pipeline
Create a Code Block in Your Flow
- Add a new code block at the appropriate stage in your flow
- Position it where you want the agentic workflow to be triggered based on your pipeline logic

Implement the Pipeline Integration Code

Below is a complete example implementation for pipeline integration:

def transform(input_record):
    """
    Pipeline integration function that processes input records and triggers 
    agentic workflow based on specific conditions within the data flow.
    
    Args:
        input_record: The incoming data record from the pipeline
        
    Returns:
        The original input_record (pass-through pattern for pipeline continuation)
    """
    
    # Define your pipeline trigger condition 
    # Example: Execute workflow when Arcanna detects phishing
    if input_record.get_arcanna_fields()["result_label"] == "Phishing":
        
        # Use the same API approach as Method 2
        headers = {
            "accept": "application/json",
            "Content-Type": "application/json",
            "X-Arcanna-Api-Key": env_variables.get("ARCANNA_MANAGEMENT_KEY")
        }
        
        # Construct the workflow endpoint URL
        workflow_id = '16'  # Your agentic workflow ID
        url = env_variables["AGENTIC_URL"] + f'/api/v1/agents-workflow/run/{workflow_id}'
        
        # Prepare the pipeline data for the workflow
        alert = {k: v for k, v in input_record.items()}
        
        # Configure the request payload (see Method 2 for detailed parameter explanations)
        data = {
            "input": alert,
            "wait_for_completion": False  # Recommended for pipeline performance
        }
        
        # Execute the workflow within the pipeline
        try:
            response = requests.post(url, headers=headers, json=data)
            print(f"Agentic workflow triggered from pipeline: {response.json()}")
        except Exception as e:
            print(f"Pipeline workflow execution error: {str(e)}")
            # Continue pipeline processing even if workflow fails
            pass
    
    # Always return the input record to continue the pipeline flow
    return input_record

Pipeline-Specific Considerations

Performance Impact: Use wait_for_completion: False to avoid blocking the pipeline
Error Handling: Implement robust error handling and/or fallback behaviour
Conditional Execution: Only trigger workflows when specific pipeline conditions are met

Method 4: MCP (Model Context Protocol) Server Integration

MCP Server integration enables AI models and applications to execute agentic workflows through the Model Context Protocol standard. This method provides a standardized interface for AI assistants, agents, and other AI-powered applications to interact with Arcanna workflows.

MCP Tools Available

The Arcanna MCP Server exposes the following tools related to agentic workflows:

Tool: run_agentic_workflow
Tool: list_agentic_workflows

Best Practices

1. Error Handling

Always implement try-catch blocks for workflow executions

2. Performance Optimization

Use asynchronous execution (wait_for_completion: false) for high-volume processing

3. Security

Store API keys in secure environment variables
Never hardcode API keys in your code

4. Data Handling

Validate input data before sending to workflows
Implement data sanitization where necessary

Overview​

Prerequisites​

Execution Methods​

Method 1: On-Demand Execution​

Steps to Execute On-Demand​

Method 2: Direct API Execution​

Setup Requirements​

API Reference​

Example​

Method 3: Pipeline Integration via Code Blocks​

Setup Requirements​

Implementation Steps​

Pipeline-Specific Considerations​

Method 4: MCP (Model Context Protocol) Server Integration​

MCP Tools Available​

Best Practices​

1. Error Handling​

2. Performance Optimization​

3. Security​

4. Data Handling​

Overview

Prerequisites

Execution Methods

Method 1: On-Demand Execution

Steps to Execute On-Demand

Method 2: Direct API Execution

Setup Requirements

API Reference

Example

Method 3: Pipeline Integration via Code Blocks

Setup Requirements

Implementation Steps

Pipeline-Specific Considerations

Method 4: MCP (Model Context Protocol) Server Integration

MCP Tools Available

Best Practices

1. Error Handling

2. Performance Optimization

3. Security

4. Data Handling