agent-task-executor/docs/architecture.md

Architecture Overview

Core Components

TaskExecutor

The TaskExecutor is the base class for all task implementations. It provides:

1. Task Step Management

   • Sequential step execution
   • State tracking
   • Checkpoint creation
   • Error handling

2. LLM Integration

   • Asynchronous API calls
   • Retry mechanisms
   • Response validation

Configuration System

1. Config Loader

   • YAML configuration files
   • Environment variable support
   • Configuration validation

2. Secure Configuration

   • Encrypted storage for sensitive data
   • Key management
   • Secure API key handling

Task Implementation

Step Definition

Each task is defined as a series of steps:

self.task_steps = [
    {
        "id": "step_id",
        "name": "Step Name",
        "required_info": ["required_data"],
        "instruction": "Step instruction for LLM"
    }
]

Step Handlers

Step handlers are implemented as async methods:

async def handle_step_id(self, step_input: dict) -> dict:
    # 1. Process input
    processed_data = self.preprocess(step_input)
    
    # 2. Call LLM if needed
    llm_response = await self.llm_call(
        instruction=step_input["instruction"],
        context=processed_data
    )
    
    # 3. Process response
    result = self.postprocess(llm_response)
    
    return {"result": result}

Execution Flow

1. Initialization

   executor = TaskExecutor(llm_model="model_name")
   

2. Task Setup

   executor.task_steps = [...]
   

3. Execution

   result = await executor.execute(input_data)
   

4. Step Processing

   • Validate input
   • Execute step handler
   • Create checkpoint
   • Handle errors
   • Move to next step

5. Completion

   • Return final result
   • Clean up resources

Error Handling

1. Retry Mechanism

   • API call retries with exponential backoff
   • Configurable retry limits

2. Error Types

   • TaskExecutionError: General execution errors
   • StepValidationError: Input validation failures
   • LLMError: LLM API related errors

3. Recovery

   • Checkpoint-based recovery
   • State restoration
   • Partial results handling

Best Practices

1. Task Design

   • Keep steps atomic and focused
   • Clear step instructions
   • Proper input validation
   • Comprehensive error handling

2. LLM Usage

   • Clear and specific prompts
   • Response validation
   • Handle token limits
   • Consider cost and latency

3. Testing

   • Unit tests for each step
   • Integration tests for full flow
   • Mock LLM calls in tests
   • Test error scenarios

4. Security

   • Secure API key handling
   • Input sanitization
   • Output validation
   • Access control

Extension Points

1. Custom Step Handlers

   • Implement custom logic
   • Add new capabilities
   • Integrate external services

2. LLM Providers

   • Support multiple providers
   • Custom response parsing
   • Provider-specific optimizations

3. Monitoring & Logging

   • Custom metrics
   • Logging handlers
   • Performance monitoring