Multi-Agent Workflows

require 'raaf'

# Research agent - gathers and analyzes information
research_agent = RAAF::Agent.new(
  name: "Researcher",
  instructions: <<~INSTRUCTIONS,
    You are a research specialist who gathers comprehensive information on topics.
    Your role is to:

    - Search for relevant information
    - Analyze and synthesize data
    - Provide well-structured research summaries

    When your research is complete, hand off to the Writer for content creation.
  INSTRUCTIONS
  model: "gpt-4o"
)

# Writing agent - creates content based on research
writer_agent = RAAF::Agent.new(
  name: "Writer",
  instructions: <<~INSTRUCTIONS,
    You are a content writer who creates engaging, well-structured content.
    Your role is to:

    - Transform research into compelling narratives
    - Ensure clarity and readability
    - Maintain consistent tone and style

    When content is complete, hand off to the Editor for review.
  INSTRUCTIONS
  model: "gpt-4o"
)

# Editor agent - reviews and refines content
editor_agent = RAAF::Agent.new(
  name: "Editor",
  instructions: <<~INSTRUCTIONS,
    You are an editor who reviews and refines content for publication.
    Your role is to:

    - Check grammar, style, and clarity
    - Ensure factual accuracy
    - Optimize for target audience

    Provide final polished content ready for publication.
  INSTRUCTIONS
  model: "gpt-4o"
)

# Define reusable prompt templates
class ResearchAgentPrompt
  def initialize(domain:, research_depth:, sources: ["web", "academic"])
    @domain = domain
    @research_depth = research_depth
    @sources = sources
  end

  def system
    <<~SYSTEM
      You are a research specialist in #{@domain}.
      Research depth: #{@research_depth}
      Available sources: #{@sources.join(", ")}

      When research is complete, hand off to the Writer with:
      - Research summary
      - Key findings
      - Source citations
    SYSTEM
  end
end

class WriterAgentPrompt
  def initialize(content_type:, target_audience:, tone: "professional")
    @content_type = content_type
    @target_audience = target_audience
    @tone = tone
  end

  def system
    <<~SYSTEM
      You are a content writer creating #{@content_type} for #{@target_audience}.
      Writing tone: #{@tone}

      Transform research into compelling content.
      When complete, hand off to Editor for review.
    SYSTEM
  end
end

# Create prompt instances
research_prompt = ResearchAgentPrompt.new(
  domain: "quantum physics",
  research_depth: "comprehensive"
)

writer_prompt = WriterAgentPrompt.new(
  content_type: "blog post",
  target_audience: "tech professionals",
  tone: "engaging yet technical"
)

# Create agents with prompt templates
research_agent = RAAF::DSL::AgentBuilder.build do
  name "Researcher"
  prompt research_prompt
  model "gpt-4o"

  use_web_search
  use_file_search
end

writer_agent = RAAF::DSL::AgentBuilder.build do
  name "Writer"
  prompt writer_prompt
  model "gpt-4o"
end

# Run multi-agent workflow
runner = RAAF::Runner.new(
  agent: research_agent,
  agents: [research_agent, writer_agent, editor_agent]
)

result = runner.run("Research and write about quantum computing")

# Define the workflow: Research → Write → Edit
research_agent.add_handoff(writer_agent)    # Creates transfer_to_writer_agent tool
writer_agent.add_handoff(editor_agent)      # Creates transfer_to_editor_agent tool

# Create runner with all agents
runner = RAAF::Runner.new(
  agent: research_agent,  # Starting agent
  agents: [research_agent, writer_agent, editor_agent]
)

# Execute the workflow
result = runner.run("Create an article about sustainable energy technologies")

# The system works through explicit tool calls:
# 1. Research agent completes research
# 2. Research agent calls transfer_to_writer_agent tool
# 3. Writer agent creates article
# 4. Writer agent calls transfer_to_editor_agent tool
# 5. Editor agent performs final review

# Create customer service agent with clear handoff instructions
customer_service = RAAF::Agent.new(
  name: "CustomerService",
  instructions: <<~INSTRUCTIONS,
    Handle customer inquiries professionally. 

    For technical issues, bugs, or system problems: call transfer_to_technical_support
    For billing questions, payments, or account issues: call transfer_to_billing_agent

    You MUST use the transfer tools - simply mentioning transfers won't work.
  INSTRUCTIONS
  model: "gpt-4o"
)

# Create specialized agents
technical_support = RAAF::Agent.new(
  name: "TechnicalSupport", 
  instructions: "Handle technical issues and troubleshooting.",
  model: "gpt-4o"
)

billing_agent = RAAF::Agent.new(
  name: "BillingAgent",
  instructions: "Handle billing and payment inquiries.",
  model: "gpt-4o"
)

# Set up handoff capabilities (creates transfer tools)
customer_service.add_handoff(technical_support)  # Creates transfer_to_technical_support
customer_service.add_handoff(billing_agent)      # Creates transfer_to_billing_agent

runner = RAAF::Runner.new(
  agent: customer_service,
  agents: [customer_service, technical_support, billing_agent]
)

# The system will route to appropriate agent based on inquiry type
result = runner.run("I'm having trouble with the API integration")
# → Routes to TechnicalSupport

result = runner.run("I need help with my monthly subscription")
# → Routes to BillingAgent

class DataAnalysisOrchestrator
  def initialize
    # Create specialized analysis agents
    @statistical_agent = RAAF::Agent.new(
      name: "StatisticalAnalyst",
      instructions: "Perform statistical analysis and hypothesis testing",
      model: "gpt-4o"
    )

    @visualization_agent = RAAF::Agent.new(
      name: "VisualizationSpecialist", 
      instructions: "Create charts, graphs, and visual representations",
      model: "gpt-4o"
    )

    @insights_agent = RAAF::Agent.new(
      name: "InsightsAnalyst",
      instructions: "Extract business insights and recommendations",
      model: "gpt-4o"
    )

    @report_agent = RAAF::Agent.new(
      name: "ReportWriter",
      instructions: "Compile analysis into comprehensive reports",
      model: "gpt-4o"
    )
  end

  def analyze_dataset(dataset_path)
    # Phase 1: Parallel analysis
    analysis_futures = [
      run_agent_async(@statistical_agent, "Analyze statistical patterns in #{dataset_path}"),
      run_agent_async(@visualization_agent, "Create visualizations for #{dataset_path}"),
      run_agent_async(@insights_agent, "Extract business insights from #{dataset_path}")
    ]

    # Wait for all parallel analyses to complete
    statistical_result = analysis_futures[0].value
    visualization_result = analysis_futures[1].value
    insights_result = analysis_futures[2].value

    # Phase 2: Compile comprehensive report
    combined_context = {
      statistical_analysis: statistical_result.messages.last[:content],
      visualizations: visualization_result.messages.last[:content],
      business_insights: insights_result.messages.last[:content]
    }

    report_runner = RAAF::Runner.new(
      agent: @report_agent,
      context_variables: combined_context
    )

    report_runner.run("Create a comprehensive data analysis report")
  end

  private

  def run_agent_async(agent, message)
    Concurrent::Future.execute do
      runner = RAAF::Runner.new(agent: agent)
      runner.run(message)
    end
  end
end

# Usage
orchestrator = DataAnalysisOrchestrator.new
result = orchestrator.analyze_dataset("sales_data_2024.csv")

class ProjectManagementSystem
  def initialize
    # Supervisor agent coordinates the project
    @project_manager = RAAF::Agent.new(
      name: "ProjectManager",
      instructions: <<~INSTRUCTIONS,
        You coordinate software development projects.
        Break down tasks and delegate to appropriate team members:

        - Requirements analysis → BusinessAnalyst
        - Architecture design → TechLead  
        - Code implementation → Developer
        - Quality assurance → QAEngineer
        - Documentation → TechnicalWriter
      INSTRUCTIONS
      model: "gpt-4o"
    )

    # Specialized worker agents
    @business_analyst = create_business_analyst
    @tech_lead = create_tech_lead
    @developer = create_developer
    @qa_engineer = create_qa_engineer
    @technical_writer = create_technical_writer

    setup_delegation_hierarchy
  end

  def manage_project(requirements)
    # Project manager coordinates the entire workflow
    runner = RAAF::Runner.new(
      agent: @project_manager,
      agents: [
        @project_manager, @business_analyst, @tech_lead,
        @developer, @qa_engineer, @technical_writer
      ],
      context_variables: {
        project_requirements: requirements,
        project_phase: 'planning'
      }
    )

    runner.run("Please manage this software development project: #{requirements}")
  end

  private

  def create_business_analyst
    RAAF::Agent.new(
      name: "BusinessAnalyst",
      instructions: <<~INSTRUCTIONS,
        Analyze business requirements and create detailed specifications.
        When analysis is complete, hand back to ProjectManager.
      INSTRUCTIONS
      model: "gpt-4o"
    )
  end

  def create_tech_lead
    RAAF::Agent.new(
      name: "TechLead",
      instructions: <<~INSTRUCTIONS,
        Design system architecture and technical approach.
        When design is complete, hand back to ProjectManager.
      INSTRUCTIONS
      model: "gpt-4o"
    )
  end

  def setup_delegation_hierarchy
    # Each worker reports back to project manager
    [@business_analyst, @tech_lead, @developer, @qa_engineer, @technical_writer].each do |agent|
      agent.add_handoff(@project_manager)
    end

    # Project manager can delegate to any worker
    @project_manager.add_handoff(@business_analyst)
    @project_manager.add_handoff(@tech_lead)
    @project_manager.add_handoff(@developer)
    @project_manager.add_handoff(@qa_engineer)
    @project_manager.add_handoff(@technical_writer)
  end
end

class ECommerceWorkflow
  def initialize
    @order_processor = RAAF::Agent.new(
      name: "OrderProcessor",
      instructions: "Process e-commerce orders and validate information",
      model: "gpt-4o"
    )

    @inventory_manager = RAAF::Agent.new(
      name: "InventoryManager", 
      instructions: "Check inventory and reserve items",
      model: "gpt-4o"
    )

    @payment_processor = RAAF::Agent.new(
      name: "PaymentProcessor",
      instructions: "Process payments and handle transactions",
      model: "gpt-4o"
    )

    @fulfillment_agent = RAAF::Agent.new(
      name: "FulfillmentAgent",
      instructions: "Coordinate shipping and delivery",
      model: "gpt-4o"
    )

    setup_workflow
  end

  def process_order(order_data)
    # Shared context that flows through the entire workflow
    shared_context = {
      order_id: order_data[:id],
      customer_id: order_data[:customer_id],
      items: order_data[:items],
      shipping_address: order_data[:shipping_address],
      payment_method: order_data[:payment_method],
      order_status: 'processing'
    }

    runner = RAAF::Runner.new(
      agent: @order_processor,
      agents: [@order_processor, @inventory_manager, @payment_processor, @fulfillment_agent],
      context_variables: shared_context
    )

    result = runner.run("Process this e-commerce order")

    # Context is updated throughout the workflow
    final_context = runner.context_variables
    {
      success: result.success?,
      order_id: final_context[:order_id],
      final_status: final_context[:order_status],
      tracking_number: final_context[:tracking_number]
    }
  end

  private

  def setup_workflow
    # Define the order processing pipeline
    @order_processor.add_handoff(@inventory_manager)
    @inventory_manager.add_handoff(@payment_processor)  
    @payment_processor.add_handoff(@fulfillment_agent)

    # Add tools that update shared context
    add_context_updating_tools
  end

  def add_context_updating_tools
    # Tool to update order status (available to all agents)
    update_order_status = lambda do |status:, notes: nil|
      # This tool automatically updates the shared context
      runner.update_context(
        order_status: status,
        last_updated: Time.now,
        status_notes: notes
      )

      { success: true, new_status: status }
    end

    [@order_processor, @inventory_manager, @payment_processor, @fulfillment_agent].each do |agent|
      agent.add_tool(update_order_status)
    end
  end
end

class ContentCreationPipeline
  def initialize
    # Each agent enriches the data for the next stage
    @researcher = create_researcher
    @outline_creator = create_outline_creator  
    @content_writer = create_content_writer
    @seo_optimizer = create_seo_optimizer
    @publisher = create_publisher

    setup_data_flow
  end

  def create_content(topic, target_audience, content_type)
    initial_brief = {
      topic: topic,
      target_audience: target_audience,
      content_type: content_type,
      creation_date: Date.today,
      workflow_stage: 'research'
    }

    runner = RAAF::Runner.new(
      agent: @researcher,
      agents: [@researcher, @outline_creator, @content_writer, @seo_optimizer, @publisher],
      context_variables: initial_brief
    )

    runner.run("Create #{content_type} content about #{topic} for #{target_audience}")
  end

  private

  def create_researcher
    agent = RAAF::Agent.new(
      name: "ContentResearcher",
      instructions: "Research topics and gather supporting information",
      model: "gpt-4o"
    )

    # Tool to store research findings
    agent.add_tool(lambda do |research_data:, sources: []|
      runner.update_context(
        research_findings: research_data,
        sources: sources,
        research_completed_at: Time.now,
        workflow_stage: 'outlining'
      )

      { status: 'research_complete', findings_count: research_data.length }
    end)

    agent.add_handoff(@outline_creator)
    agent
  end

  def create_outline_creator
    agent = RAAF::Agent.new(
      name: "OutlineCreator",
      instructions: <<~INSTRUCTIONS,
        Create detailed content outlines based on research.
        Use research_findings from context to structure content.
      INSTRUCTIONS
      model: "gpt-4o"
    )

    agent.add_tool(lambda do |outline:, key_points: []|
      runner.update_context(
        content_outline: outline,
        key_points: key_points,
        outline_completed_at: Time.now,
        workflow_stage: 'writing'
      )

      { status: 'outline_complete', sections: outline.length }
    end)

    agent.add_handoff(@content_writer)
    agent
  end

  def create_content_writer
    agent = RAAF::Agent.new(
      name: "ContentWriter",
      instructions: <<~INSTRUCTIONS,
        Write engaging content following the outline.
        Use content_outline and research_findings from context.
      INSTRUCTIONS
      model: "gpt-4o"
    )

    agent.add_tool(lambda do |content:, word_count:|
      runner.update_context(
        final_content: content,
        word_count: word_count,
        content_completed_at: Time.now,
        workflow_stage: 'seo_optimization'
      )

      { status: 'content_complete', word_count: word_count }
    end)

    agent.add_handoff(@seo_optimizer)
    agent
  end
end

class ResilientWorkflow
  def initialize
    @primary_agents = create_primary_agents
    @fallback_agents = create_fallback_agents
    @error_handler = create_error_handler
  end

  def execute_with_fallbacks(task)
    begin
      # Try primary workflow
      execute_primary_workflow(task)
    rescue RAAF::Errors::AgentExecutionError => e
      log_error(e, 'primary_workflow_failed')

      # Attempt recovery with fallback agents
      execute_fallback_workflow(task, e)
    rescue => e
      # Ultimate fallback - human escalation
      escalate_to_human(task, e)
    end
  end

  private

  def execute_primary_workflow(task)
    runner = RAAF::Runner.new(
      agent: @primary_agents[:coordinator],
      agents: @primary_agents.values,
      error_strategy: :retry_with_backoff,
      max_retries: 3
    )

    runner.run(task)
  end

  def execute_fallback_workflow(task, original_error)
    # Use simpler agents or different models
    fallback_runner = RAAF::Runner.new(
      agent: @fallback_agents[:simple_coordinator],
      agents: @fallback_agents.values,
      context_variables: {
        fallback_mode: true,
        original_error: original_error.message
      }
    )

    fallback_runner.run("Simplified version: #{task}")
  end

  def create_fallback_agents
    {
      simple_coordinator: RAAF::Agent.new(
        name: "SimpleCoordinator",
        instructions: "Handle tasks with basic capabilities only",
        model: "gpt-4o-mini"  # Use cheaper, faster model
      )
    }
  end

  def escalate_to_human(task, error)
    {
      status: 'human_escalation_required',
      task: task,
      error: error.message,
      escalation_id: SecureRandom.uuid,
      escalated_at: Time.now
    }
  end
end

class CircuitBreakerWorkflow
  def initialize
    @circuit_breakers = {}
    @failure_thresholds = {
      api_agent: 5,        # 5 failures in 10 minutes
      db_agent: 3,         # 3 failures in 5 minutes  
      external_service: 10  # 10 failures in 30 minutes
    }
  end

  def execute_with_circuit_breaker(agent_name, task)
    circuit_breaker = get_circuit_breaker(agent_name)

    if circuit_breaker[:open] && !circuit_breaker_should_retry?(circuit_breaker)
      return {
        status: 'circuit_breaker_open',
        message: "#{agent_name} is temporarily unavailable",
        retry_after: circuit_breaker[:retry_after]
      }
    end

    begin
      result = execute_agent_task(agent_name, task)
      reset_circuit_breaker(agent_name)
      result
    rescue => e
      record_failure(agent_name, e)

      if should_open_circuit?(agent_name)
        open_circuit_breaker(agent_name)
      end

      raise e
    end
  end

  private

  def get_circuit_breaker(agent_name)
    @circuit_breakers[agent_name] ||= {
      failures: [],
      open: false,
      opened_at: nil,
      retry_after: nil
    }
  end

  def should_open_circuit?(agent_name)
    circuit_breaker = @circuit_breakers[agent_name]
    threshold = @failure_thresholds[agent_name] || 5

    recent_failures = circuit_breaker[:failures].select do |failure_time|
      Time.now - failure_time < 10.minutes
    end

    recent_failures.count >= threshold
  end

  def open_circuit_breaker(agent_name)
    @circuit_breakers[agent_name].merge!(
      open: true,
      opened_at: Time.now,
      retry_after: Time.now + 5.minutes
    )

    log_circuit_breaker_opened(agent_name)
  end
end

class HighThroughputProcessor
  def initialize(pool_size: 10)
    @agent_pools = {
      text_processor: create_agent_pool('TextProcessor', pool_size),
      data_analyzer: create_agent_pool('DataAnalyzer', pool_size),
      report_generator: create_agent_pool('ReportGenerator', pool_size)
    }
  end

  def process_batch(tasks)
    # Group tasks by type
    grouped_tasks = tasks.group_by { |task| task[:type] }

    # Process each group in parallel
    futures = grouped_tasks.map do |task_type, task_list|
      Concurrent::Future.execute do
        process_task_group(task_type, task_list)
      end
    end

    # Collect all results
    futures.map(&:value).flatten
  end

  private

  def create_agent_pool(agent_type, size)
    ConnectionPool.new(size: size, timeout: 30) do
      case agent_type
      when 'TextProcessor'
        RAAF::Agent.new(
          name: "TextProcessor_#{SecureRandom.hex(4)}",
          instructions: "Process and analyze text content",
          model: "gpt-4o-mini"  # Use faster model for bulk processing
        )
      when 'DataAnalyzer'
        RAAF::Agent.new(
          name: "DataAnalyzer_#{SecureRandom.hex(4)}", 
          instructions: "Analyze data and extract insights",
          model: "gpt-4o"
        )
      when 'ReportGenerator'
        RAAF::Agent.new(
          name: "ReportGenerator_#{SecureRandom.hex(4)}",
          instructions: "Generate formatted reports",
          model: "gpt-4o"
        )
      end
    end
  end

  def process_task_group(task_type, tasks)
    pool = @agent_pools[task_type.downcase.to_sym]

    # Process tasks in parallel using the pool
    Concurrent::Array.new.tap do |results|
      Concurrent::ThreadPoolExecutor.new.tap do |executor|
        tasks.each do |task|
          executor.post do
            pool.with do |agent|
              runner = RAAF::Runner.new(agent: agent)
              result = runner.run(task[:content])
              results << { task_id: task[:id], result: result }
            end
          end
        end

        executor.shutdown
        executor.wait_for_termination
      end
    end
  end
end

class EventDrivenAgentSystem
  def initialize
    @event_bus = EventBus.new
    @agents = {}
    @subscriptions = {}

    setup_agents_and_subscriptions
  end

  def publish_event(event_type, data)
    @event_bus.publish(event_type, data)
  end

  private

  def setup_agents_and_subscriptions
    # Create agents
    @agents[:order_processor] = create_order_processor
    @agents[:inventory_manager] = create_inventory_manager
    @agents[:notification_service] = create_notification_service

    # Set up event subscriptions
    @event_bus.subscribe('order.created') do |event_data|
      process_new_order(event_data)
    end

    @event_bus.subscribe('inventory.low') do |event_data|
      handle_low_inventory(event_data)
    end

    @event_bus.subscribe('order.shipped') do |event_data|
      send_shipping_notification(event_data)
    end
  end

  def process_new_order(order_data)
    runner = RAAF::Runner.new(agent: @agents[:order_processor])
    result = runner.run("Process new order: #{order_data[:order_id]}")

    if result.success?
      # Trigger next event in the chain
      @event_bus.publish('order.processed', {
        order_id: order_data[:order_id],
        processed_at: Time.now
      })
    end
  end

  def handle_low_inventory(inventory_data)
    runner = RAAF::Runner.new(agent: @agents[:inventory_manager])
    runner.run("Handle low inventory for product: #{inventory_data[:product_id]}")
  end

  def send_shipping_notification(shipping_data)
    runner = RAAF::Runner.new(agent: @agents[:notification_service])
    runner.run("Send shipping notification for order: #{shipping_data[:order_id]}")
  end
end

class StateMachineWorkflow
  include AASM

  aasm do
    state :waiting_for_input, initial: true
    state :analyzing
    state :processing
    state :reviewing
    state :completed
    state :failed

    event :start_analysis do
      transitions from: :waiting_for_input, to: :analyzing
    end

    event :begin_processing do
      transitions from: :analyzing, to: :processing
    end

    event :request_review do
      transitions from: :processing, to: :reviewing
    end

    event :complete do
      transitions from: :reviewing, to: :completed
    end

    event :fail do
      transitions from: [:analyzing, :processing, :reviewing], to: :failed
    end
  end

  def initialize(task_data)
    @task_data = task_data
    @agents = create_specialized_agents
    @context = { task_id: SecureRandom.uuid }
  end

  def execute
    start_analysis!

    case aasm_state
    when 'analyzing'
      perform_analysis
    when 'processing'  
      perform_processing
    when 'reviewing'
      perform_review
    when 'completed'
      return_results
    when 'failed'
      handle_failure
    end
  end

  private

  def perform_analysis
    begin
      runner = RAAF::Runner.new(
        agent: @agents[:analyst],
        context_variables: @context
      )

      result = runner.run("Analyze: #{@task_data}")

      if result.success?
        @context[:analysis_result] = result.messages.last[:content]
        begin_processing!
        execute  # Continue to next state
      else
        fail!
      end
    rescue => e
      @context[:error] = e.message
      fail!
    end
  end

  def perform_processing
    begin
      runner = RAAF::Runner.new(
        agent: @agents[:processor],
        context_variables: @context
      )

      result = runner.run("Process based on analysis")

      if result.success?
        @context[:processing_result] = result.messages.last[:content]
        request_review!
        execute  # Continue to next state
      else
        fail!
      end
    rescue => e
      @context[:error] = e.message
      fail!
    end
  end
end

RSpec.describe 'Multi-Agent Research Workflow' do
  let(:research_agent) { create_research_agent }
  let(:writer_agent) { create_writer_agent }
  let(:editor_agent) { create_editor_agent }

  describe 'Research Agent' do
    it 'gathers relevant information' do
      runner = RAAF::Runner.new(agent: research_agent)
      result = runner.run("Research renewable energy technologies")

      expect(result.success?).to be true
      expect(result.messages.last[:content]).to include('renewable energy')

      # Verify handoff intent
      expect(result.handoff_requested?).to be true
      expect(result.handoff_target).to eq('Writer')
    end
  end

  describe 'Writer Agent' do
    it 'creates content from research' do
      # Set up context with research data
      context = {
        research_findings: "Solar and wind power are leading renewable technologies...",
        target_audience: "general public"
      }

      runner = RAAF::Runner.new(
        agent: writer_agent,
        context_variables: context
      )

      result = runner.run("Write an article based on the research")

      expect(result.success?).to be true
      expect(result.messages.last[:content]).to include('renewable')
    end
  end
end

RSpec.describe 'Complete Content Creation Workflow' do
  let(:workflow) { ContentCreationWorkflow.new }

  it 'completes the full research → write → edit pipeline' do
    result = workflow.create_content(
      topic: "Climate Change Solutions",
      target_audience: "business leaders",
      content_type: "blog post"
    )

    expect(result.success?).to be true
    expect(result.final_stage).to eq('completed')

    # Verify each stage was executed
    expect(result.execution_log).to include(
      { stage: 'research', agent: 'ContentResearcher', status: 'completed' },
      { stage: 'writing', agent: 'ContentWriter', status: 'completed' },
      { stage: 'editing', agent: 'Editor', status: 'completed' }
    )

    # Verify content quality
    final_content = result.final_output
    expect(final_content).to include('climate change')
    expect(final_content.length).to be > 500  # Minimum length
  end

  it 'handles failures gracefully' do
    # Simulate agent failure
    allow_any_instance_of(RAAF::Agent).to receive(:run).and_raise(StandardError)

    result = workflow.create_content(
      topic: "Test Topic",
      target_audience: "test audience", 
      content_type: "article"
    )

    expect(result.success?).to be false
    expect(result.error_stage).to be_present
    expect(result.fallback_used?).to be true
  end
end

# ❌ BAD: Tightly coupled agents
class BadAgent < RAAF::Agent
  def initialize(other_agent)
    @other_agent = other_agent  # Direct dependency
    super(name: "BadAgent", instructions: "...", model: "gpt-4o")
  end

  def custom_method
    # Directly calling other agent
    @other_agent.run("Some message")  # Tight coupling
  end
end

# ✅ GOOD: Loosely coupled through handoffs
class GoodAgent < RAAF::Agent
  def initialize
    super(name: "GoodAgent", instructions: "...", model: "gpt-4o")

    # Define handoff conditions, not direct dependencies
    add_handoff_condition do |context, messages|
      if should_escalate?(messages.last[:content])
        { agent: :specialist_agent, reason: 'Escalation needed' }
      end
    end
  end
end

class MonitoredWorkflow
  def initialize
    @tracer = RAAF::Tracing::SpanTracer.new
    @tracer.add_processor(RAAF::Tracing::ConsoleProcessor.new)
    @tracer.add_processor(RAAF::Tracing::OpenAIProcessor.new)

    @metrics = setup_metrics_collection
  end

  def execute_with_monitoring(task)
    start_time = Time.now

    begin
      result = execute_workflow(task)

      # Record success metrics
      @metrics.increment('workflow.success')
      @metrics.timing('workflow.duration', Time.now - start_time)

      result
    rescue => e
      # Record failure metrics
      @metrics.increment('workflow.failure')
      @metrics.increment("workflow.failure.#{e.class.name.downcase}")

      # Log error details
      @tracer.record_error(e, {
        task: task,
        duration: Time.now - start_time
      })

      raise e
    end
  end

  private

  def setup_metrics_collection
    # Configure your metrics backend (StatsD, Prometheus, etc.)
    StatsD.new('localhost', 8125)
  end
end