Skip to main content

ADR: Agent Executor Simplification Refactor

Status: 🟡 In-review
Category: Refactoring & Code Quality
Date: January 16, 2026
Signed-off-by: Sri Aradhyula <sraradhy@cisco.com>

Overview​

Refactored agent_executor.py to reduce complexity by 36% (from 971 to 613 lines) while maintaining full functionality. The monolithic 722-line execute() method was decomposed into focused helper methods, and dead code (unused routing logic, feature flags) was removed.

This refactor also incorporates the streaming duplication fix from PR #647 (clear_accumulators signal handling).

Motivation​

Issues​

  1. Monolithic execute() method: The main execution method was 722 lines, making it difficult to:

    • Understand the execution flow
    • Test individual components
    • Debug issues
    • Add new features safely

  2. Dead code accumulation: Over time, experimental features were added but never used:

    • RoutingType enum and RoutingDecision class
    • _route_query(), _detect_sub_agent_query() methods
    • _stream_from_sub_agent(), _stream_from_multiple_agents() methods
    • Feature flags for routing modes (ENABLE_ENHANCED_STREAMING, etc.)
    • Configurable routing keywords

  3. Scattered state management: Execution state was tracked through many individual variables, making it hard to trace the flow.

Code Metrics Before​

MetricValue
Total lines971
execute() method~722 lines
Dead methods8
Feature flags4
State variables15+ scattered

Testing Strategy​

Streaming Tests​

# Test 1: CAIPE persona query
curl -s -N -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "test-1",
    "method": "message/stream",
    "params": {
      "message": {
        "messageId": "msg-1",
        "role": "user",
        "parts": [{"text": "What is CAIPE persona support?"}]
      }
    }
  }'
# ✅ Verified: Streaming works, tool notifications appear, final result correct

# Test 2: SRE onboarding query
curl -s -N -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "test-2",
    "method": "message/stream",
    "params": {
      "message": {
        "messageId": "msg-2",
        "role": "user",
        "parts": [{"text": "Show SRE onboarding docs"}]
      }
    }
  }'
# ✅ Verified: Multi-tool flow works, execution plan tracked

Verified Behaviors​

BehaviorResult
Token streaming✅ Works
Tool notifications✅ Displayed
Execution plan tracking✅ Updated
Sub-agent artifacts✅ Forwarded
Task completion✅ Sent
Error handling✅ Works
User input requests✅ Works
Cancellation✅ Works

Benefits​

  1. Improved Readability

    • execute() now fits on one screen (~155 lines)
    • Clear separation of concerns
    • State management centralized in StreamState

  2. Better Testability

    • Helper methods can be unit tested individually
    • State transitions are predictable
    • Mock-friendly design

  3. Easier Maintenance

    • No dead code to maintain
    • No unused feature flags to confuse
    • Clear responsibility boundaries

  4. Performance

    • No runtime overhead from unused routing logic
    • Cleaner execution path
    • Same functionality, less code to execute