Agentic Voice Workflow

Repeatable process for creating agentic background jobs with voice I/O and queue integration.

When to Use

Use this workflow when building agents that:

• •Run as background jobs via RunningFifoQueue
• •Send progress notifications via cosa-voice MCP tools
• •Support human-in-the-loop decision points
• •Generate artifacts (reports, audio, etc.)
• •Follow the AgenticJobBase interface contract

Quick Start

Slash Command: /lupin-new-claude-agent-sdk-voice-workflow

Reference Agents:

• •src/cosa/agents/deep_research/ - Research agent pattern
• •src/cosa/agents/podcast_generator/ - Audio generation pattern

Workflow Phases

Phase 0: Discovery Questions

Before creating files, answer:

1. •Agent Name (snake_case): e.g., pdf_summarizer
2. •Job Prefix (2-3 letters): e.g., ps → job IDs like ps-a1b2c3d4
3. •Input Type: User query, file path, URL, structured data
4. •Output Type: Text report, audio file, JSON, multiple artifacts
5. •External Dependencies: Web search, LLM API, TTS, database
6. •Human-in-the-Loop: None, input clarification, plan approval, draft review
7. •Execution Time: Seconds, minutes, long-running

State Machine Pattern

class OrchestratorState( Enum ):
    # Active states
    INITIALIZING = "initializing"
    PROCESSING   = "processing"
    GENERATING   = "generating"

    # Waiting states (human-in-the-loop)
    WAITING_APPROVAL = "waiting_approval"

    # Terminal states
    COMPLETED = "completed"
    FAILED    = "failed"

Voice Notification Integration

# Progress update
notify( "Starting research phase", priority="low" )

# Human-in-the-loop
response = ask_yes_no( "Approve this plan?", default="yes" )

# Completion
notify( "Agent completed successfully", priority="medium" )

Key Interfaces

AgenticJobBase Contract

• •run() - Main entry point
• •get_state() - Current orchestrator state
• •get_progress() - Completion percentage
• •get_result() - Final output

Queue Integration

• •Job ID format: {prefix}-{uuid4[:8]}
• •Status updates via WebSocket events
• •Progress tracking for UI display

Detailed Reference

Full Workflow Document: src/workflow/agentic-voice-workflow.md

Contains:

• •Complete phase breakdowns
• •File templates
• •Testing procedures
• •Integration patterns

Anti-Patterns

• •Don't skip Phase 0 discovery - design before coding
• •Don't forget voice notifications - user needs progress updates
• •Don't ignore state machine - enables proper job tracking
• •Don't hardcode job IDs - use the prefix pattern