Agent Factory: Blueprint to Agent Instantiation

[mathaix]

User Story

As a developer
I want an Agent Factory that creates Interview Agents from blueprints
So that agents are dynamically configured based on manager specifications

Acceptance Criteria

Agent Factory Interface

class AgentFactory:
    async def create_agent(
        self,
        blueprint: InterviewBlueprint,
        agent_config_id: str
    ) -> InterviewAgent:
        """Create a Pydantic AI agent from blueprint configuration."""
        
    async def create_ag_ui_app(
        self,
        agent: InterviewAgent,
        interview_state: InterviewState
    ) -> AGUIApp:
        """Wrap agent in AG-UI adapter for streaming."""

System Prompt Generation

• Compose system prompt from blueprint components:
  • Persona description
  • Goal list with priorities
  • Question guidelines
  • Extraction instructions with examples
  • Behavioral rules (handling reluctance, etc.)
• System prompt template with variable substitution
• Validate generated prompt length

Tool Configuration

Based on blueprint, agent gets tools for:

• detect_entity(type, data) - Structured entity extraction
• update_topic_coverage(topic, depth) - Track interview progress
• trigger_ui_component(component, data) - Show adaptive UI
• request_file_upload(reason) - Ask for documents
• end_interview(summary) - Gracefully conclude

Extraction Schema Integration

• Convert ExtractionSpec to structured output schema
• Generate few-shot examples from entity examples
• Configure entity detection confidence thresholds

Interview State Initialization

• Create InterviewState from agent config
• Initialize topic coverage from question categories
• Set up entity detection callbacks
• Configure AG-UI event handlers

Model Selection

• Use model specified in AgentConfig
• Fallback to project default if not specified
• Support: claude-haiku, claude-sonnet, claude-opus
• Temperature from config (default 0.7)

AG-UI Integration

• Agent wrapped in AG-UI adapter
• Streaming responses via SSE
• State sync events for frontend
• Custom events for Clara-specific updates

Technical Notes

# Usage example
blueprint = await load_blueprint(blueprint_id)
agent = await factory.create_agent(blueprint, agent_id)
app = await factory.create_ag_ui_app(agent, interview_state)

# Mount to FastAPI
@router.get("/interviews/{id}/stream")
async def stream_interview(id: str):
    return await app.handle_stream(request)

See DESIGN-ASSISTANT-SDK-INTEGRATION.md for full integration spec.

Definition of Done

• Agent factory implemented
• System prompt generation working
• Tools configured from blueprint
• AG-UI streaming working
• Integration test with sample blueprint
• Code reviewed and merged

Requirement ID

AG-04, AG-05

---

🤖 Generated with Claude Code