Summary

Implement the 3-stage agent execution hook system in SearchService to enable AI agents to enhance, transform, and augment the search pipeline at strategic points.

Background

This implements the architecture defined in docs/architecture/search-agent-hooks-architecture.md. Agents can be injected at three stages:

1. Pre-Search Agents - Transform/enhance query before vector search
2. Post-Search Agents - Process/filter documents before answer generation
3. Response Agents - Generate artifacts from final answer (parallel execution)

Pipeline Flow

User Query
    │
    ▼
┌─────────────────────────────────────┐
│  STAGE 1: PRE-SEARCH AGENTS         │
│  • Query Expander                   │
│  • Language Detector/Translator     │
│  • Acronym Resolver                 │
│  • Intent Classifier                │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│  CORE RAG SEARCH (unchanged)        │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│  STAGE 2: POST-SEARCH AGENTS        │
│  • Re-ranker                        │
│  • Deduplicator                     │
│  • External Enricher                │
│  • PII Redactor                     │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│  ANSWER GENERATION (unchanged)      │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│  STAGE 3: RESPONSE AGENTS           │
│  • PowerPoint Generator             │
│  • PDF Report Generator             │
│  • Chart Generator                  │
│  • Audio Summary                    │
│  (Runs in PARALLEL)                 │
└─────────────────────────────────────┘
    │
    ▼
Final Response with Artifacts

Implementation Tasks

Database Schema

• Create agent_configs table (user's agent configurations)
• Create collection_agents junction table (collection ↔ agent association)
• Add indexes for efficient lookups

Backend Components

• AgentContext dataclass for passing state through pipeline
• AgentResult dataclass for agent responses
• Agent executor for each stage in SearchService
• Pre-search agent hook (sequential by priority)
• Post-search agent hook (sequential by priority)
• Response agent hook (parallel execution)
• Circuit breaker for agent failures

API Endpoints

• GET /api/agents/configs - List user's agent configs
• POST /api/agents/configs - Create agent config
• PATCH /api/agents/configs/{id} - Update agent config
• DELETE /api/agents/configs/{id} - Delete agent config
• GET /api/collections/{id}/agents - List collection's agents
• POST /api/collections/{id}/agents - Add agent to collection
• DELETE /api/collections/{id}/agents/{agent_id} - Remove agent
• PATCH /api/agents/configs/priorities - Batch update priorities

Search Response Enhancement

• Add agent_artifacts field to SearchResponse
• Add agent_executions field for tracking
• Add pipeline_metadata for timing info

Dependencies

• PR feat: SPIFFE/SPIRE Integration Architecture for Agent Identity #695 (SPIFFE/SPIRE agent identity) - merged
• PR feat(mcp): Add MCP Gateway integration for tool invocation and enrichment #671 (MCP Gateway client) - for calling external agent tools

Acceptance Criteria

• Agents execute at correct pipeline stages
• Pre/post-search agents run sequentially by priority
• Response agents run in parallel
• Agent failures are isolated (don't break search)
• Collection ↔ Agent associations persist correctly
• Agent artifacts returned in SearchResponse
• Unit tests with 80%+ coverage
• Integration tests for full pipeline

References

• Architecture: docs/architecture/search-agent-hooks-architecture.md
• Epic: [EPIC] Future: Agentic AI Platform v2 (Phase 4) #691