AgentNexus Documentation
Workflow System

Workflow System

Workflow System

The workflow system is one of the most powerful features of AgentNexus, enabling you to build sophisticated multi-step interactions that guide users through complex processes while maintaining state between steps.

What Are Workflows?

Workflows are structured, multi-step processes that coordinate user interactions, agent actions, and state management. They’re perfect for complex tasks that require:

  • Multiple steps to complete
  • User input at various stages
  • State preservation across steps
  • Dynamic UI updates
  • Branching based on user choices

Key Workflow Capabilities

Creating Workflows
Define multi-step processes with transitions
Step Handlers
Implement workflow step behavior
State Management
Preserve and manage state across steps
UI Integration
Connect UI components to workflows
Session Management
Handle persistence and timeouts

Workflow Example

Here’s a simple workflow that illustrates the core concepts:

from agentnexus.base_types import Workflow, WorkflowStep, WorkflowStepType

# Define a multi-step workflow
USER_REGISTRATION = Workflow(
    id="user_registration",
    name="User Registration",
    description="Register a new user with personal information and preferences",
    steps=[
        WorkflowStep(id="basic_info"),
        WorkflowStep(id="address"),
        WorkflowStep(id="preferences"),
        WorkflowStep(id="review"),
        WorkflowStep(id="complete", type=WorkflowStepType.END)
    ],
    initial_step="basic_info"
)

Each step is implemented with the workflow_step decorator:

from agentnexus.workflow_manager import workflow_step
from agentnexus.base_types import WorkflowStepResponse

@workflow_step(
    agent_config=registration_agent,
    workflow_id="user_registration",
    step_id="basic_info",
    name="Basic Information",
    description="Collect basic user information",
    ui_components=[basic_info_form, instructions]
)
async def handle_basic_info_step(input_data) -> WorkflowStepResponse:
    """Handle the basic information step."""
    # Extract context and form data
    context = getattr(input_data, 'context', {}) or {}
    form_data = getattr(input_data, 'form_data', None)

    # Process form submission
    if form_data and form_data.get("action") == "submit":
        values = form_data.get("values", {})
        name = values.get("name", "")
        email = values.get("email", "")

        # Move to next step
        return WorkflowStepResponse(
            data={"status": "basic_info_complete"},
            ui_updates=[],
            next_step_id="address",
            context_updates={
                "user_name": name,
                "user_email": email
            }
        )

    # Initial step load
    return WorkflowStepResponse(
        data={"status": "ready"},
        ui_updates=[
            UIComponentUpdate(
                key="basic_info_form",
                state={"values": {
                    "name": context.get("user_name", ""),
                    "email": context.get("user_email", "")
                }}
            )
        ],
        context_updates={}
    )

When to Use Workflows

Workflows are ideal for:

  • User Onboarding: Guide users through setup processes
  • Multi-Step Forms: Break complex forms into manageable steps
  • Wizards: Create step-by-step configuration interfaces
  • Interactive Tutorials: Guide users through learning experiences
  • Decision Trees: Implement branching logic based on user input
  • Complex Analysis: Process data through multiple stages

Benefits of Workflows

  • User Guidance: Help users navigate complex processes
  • State Persistence: Maintain context between steps
  • Progress Tracking: Show users where they are in the process
  • Error Isolation: Handle errors at specific steps without losing progress
  • Flexible Navigation: Allow users to move forward, backward, or branch based on choices
  • Consistent UI: Maintain a cohesive interface throughout the process

Best Practices

  • Clear Step Purpose: Each step should have a single, well-defined purpose
  • Consistent Navigation: Provide clear navigation between steps
  • Progress Indication: Show users where they are in the workflow
  • Comprehensive Context: Store all relevant data in the context
  • Error Handling: Handle errors gracefully at each step
  • Validation: Validate inputs before proceeding to the next step

Next Steps

Creating Workflows →

Learn how to define workflows with steps and transitions.

Workflow Concepts →

Review the core concepts of the workflow system.