Agent Blueprint Schema

[mathaix]

User Story

As a developer
I want the AgentBlueprint schema fully defined
So that Interview Agents can be instantiated from blueprint configuration

Acceptance Criteria

AgentBlueprint Structure

class AgentBlueprint(BaseModel):
    id: str                             # agent_{ulid}
    name: str
    description: str
    mission: str                        # NEW: What this agent is trying to achieve
    
    target_interviewees: IntervieweeSpec
    persona: PersonaSpec
    goals: list[GoalSpec]
    questions: list[QuestionSpec]
    question_flow: QuestionFlowSpec
    
    rubric_field_mapping: list[str]    # NEW: Which shared rubric fields this agent populates
    system_prompt: str                  # Human-readable for debugging/transparency
    exit_conditions: ExitConditions     # NEW: When to exit interview
    
    config: AgentConfig
    design_rationale: DesignRationale

NEW: ExitConditions

class ExitConditions(BaseModel):
    required_fields_threshold: float = 1.0  # % of required rubric fields captured
    max_turns: int = 30                     # Safety net
    graceful_closing: bool = True           # Natural wrap-up vs. abrupt stop

Interview agents exit when:

1. Primary: All required rubric fields captured (or marked Unknown/TODO)
2. Secondary: LLM assessment ("Have I missed anything?")
3. Safety: Max turn limit reached

IntervieweeSpec

• roles: Target roles for this agent
• departments: Target departments
• expertise_areas: Required expertise
• count_target: How many interviews
• selection_criteria: How to choose interviewees

PersonaSpec

• role: Agent's role identity
• tone: Communication tone
• expertise: List of expertise areas
• communication_style: How agent communicates
• rapport_building_approach: Strategy for rapport
• handling_reluctance: Strategy for reluctant interviewees

GoalSpec

• id: Unique goal identifier
• goal: Goal description
• priority: 1 = highest
• success_criteria: List of criteria
• related_questions: Question IDs that support this goal

QuestionSpec

• id: Unique question identifier
• question: The question text
• purpose: Why ask this question
• category: rapport | discovery | probing | sensitive | closing
• sequence_position: Order in flow
• probing_triggers: When to probe deeper
• follow_up_questions: Follow-up question texts
• skip_conditions: When to skip this question
• expected_rubric_fields: Which rubric fields this question elicits

QuestionFlowSpec

• opening_sequence: Question IDs for opening
• core_sequence: Main interview questions
• sensitive_sequence: Sensitive topic questions
• closing_sequence: Wrap-up questions
• branching_rules: {condition, goto_question}

AgentConfig

• model: LLM model identifier
• max_turns: Maximum conversation turns
• estimated_duration_minutes: Expected interview length
• temperature: LLM temperature (default 0.7)
• recording_enabled: Boolean

DesignRationale

• understanding: What Architect understood
• assumptions: List of assumptions made
• key_considerations: Factors considered
• design_choices: List of {choice, rationale}
• potential_challenges: Anticipated issues

Definition of Done

• All models defined with validation
• Example blueprints validate successfully
• Schema documentation complete
• Code reviewed and merged

---

🤖 Generated with Claude Code