feat: Add voice agent SDK module and CLI template

[ben-kluger-scale]

Add comprehensive voice agent support to the Agentex SDK:

New SDK Module (src/agentex/voice/)

• VoiceAgentBase: Base class with state management, interruption handling, guardrail execution, and streaming support
• AgentState/AgentResponse: Pydantic models for conversation state
• Guardrail/LLMGuardrail: Abstract base classes for implementing guardrails

New CLI Template (agentex init)

• Full project scaffolding for voice agents
• Multi-provider LLM support (OpenAI, Azure, SGP, Vertex AI, Mock)
• Docker + Kubernetes deployment configuration
• Example guardrail structure

CLI Changes

• Added Conversational Agent template option in 'agentex init' command
• Generates voice-specific project structure

Dependencies

• Added partial-json-parser for streaming JSON parsing
• Added google-auth for Vertex AI authentication

What's Different About This Template

Unlike standard templates where you write ACP handlers from scratch, the Conversational Agent template uses VoiceAgentBase which provides:

• Automatic state persistence across messages
• Interruption handling when new messages arrive mid-processing
• Concurrent guardrail execution during streaming
• Conversation history management

Developers implement just 2 methods (get_system_prompt, update_state_and_tracing_from_response) and get production-ready conversational agents.

What Gets Generated

Running agentex init → "Conversational Agent" creates:

my-agent/
├── project/
│   ├── __init__.py
│   └── acp.py          # Your agent implementation
├── Dockerfile
├── manifest.yaml       # Deployment configuration
├── environments.yaml   # Environment-specific settings
├── pyproject.toml      # Dependencies
├── dev.ipynb           # Development notebook
└── README.md           # Setup instructions

acp.py specifics

project/acp.py
├── LLM Configuration (lines 30-153)
│   └── Auto-detects which LLM provider you configured
│
├── State & Response Models (lines 163-184)
│   ├── MyAgentState(AgentState)     ← Track conversation data
│   └── MyAgentResponse(AgentResponse) ← Structured LLM outputs
│
├── Agent Class (lines 191-259)
│   └── MyAgent(VoiceAgentBase)
│       ├── get_system_prompt()      ← Agent prompt
│       └── update_state_and_tracing_from_response()
│
├── Guardrails (optional, lines ~270)
│   └── GUARDRAILS = [...]
│
├── Tools (optional, lines ~290)
│   └── TOOLS = [...]
│
├── Agent Instance (lines ~310)
│   └── AGENT = MyAgent(...)
│
└── ACP Handler (lines ~320)
    └── @acp.on_message_send → delegates to AGENT.send_message()

Key Code: project/acp.py

class MyAgentState(AgentState):
    """Custom state - extend to track conversation data."""
    pass

class MyAgent(VoiceAgentBase):
    """Your conversational agent."""
    
    def get_system_prompt(self, state, guardrail_override=None):
        """Define your agent's behavior."""
        return "You are a helpful assistant..."
    
    def update_state_and_tracing_from_response(self, state, response, span):
        """Update state after each response."""
        return state

# ACP Handler - delegates to VoiceAgentBase
@acp.on_message_send
async def handle_message_send(params: SendMessageParams):
    async for chunk in AGENT.send_message(params):
        yield chunk

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	partial-json-parser@​0.2.1.1.post7

View full report