Custom subagents and output style

[mikoskinen]

Thank you, great project!

Any guidance on how to use custom agents? And also custom output styles? Claude Code CLI allows passing the agent for a specific sessions and I'm looking something similar:

--agent	Specify an agent for the current session (overrides the agent setting)	claude --agent my-custom-agent
--agents	Define custom [subagents](https://code.claude.com/docs/en/sub-agents) dynamically via JSON (see below for format)	claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'

So my goal is to be able to easily start a session with a specific agents. And of course somehow manage the available agents.

[RichardAtCT]

@claude what changes will we need to make to support this?

[claude]

Claude finished @RichardAtCT's task —— View job

---

Analysis: Custom Subagents Implementation

Based on my analysis of the codebase, here's what would need to be implemented to support custom agents similar to Claude Code CLI:

Todo List:

• Read repository setup instructions (CLAUDE.md)
• Explore current codebase architecture
• Analyze existing agent/subagent functionality
• Research Claude Code CLI agent implementation
• Identify required changes for custom agents
• Provide implementation roadmap

🔍 Current State Analysis

The wrapper currently does not support the --agent and --agents CLI parameters. Instead, it uses:

1. Claude Agent SDK with structured system prompts
2. Tool-based subagents via the "Task" tool
3. OpenAI-compatible API without native CLI argument parsing

📋 Required Changes for Custom Agents

1. CLI Parameter Support

Add to src/main.py:1202-1214:

import argparse

def parse_cli_args():
    parser = argparse.ArgumentParser()
    parser.add_argument('--agent', type=str, help='Specify an agent for the current session')
    parser.add_argument('--agents', type=str, help='Define custom subagents via JSON')
    parser.add_argument('port', nargs='?', type=int, help='Port number')
    return parser.parse_args()

2. Agent Configuration Models

Add to src/models.py:

class AgentConfig(BaseModel):
    description: str
    prompt: str
    model: Optional[str] = None
    tools: Optional[List[str]] = None
    output_style: Optional[str] = None

class CustomAgentsRequest(BaseModel):
    agents: Dict[str, AgentConfig]
    
class SessionAgentRequest(BaseModel):
    agent_name: str
    session_id: Optional[str] = None

3. Agent Manager System

Create src/agent_manager.py:

class AgentManager:
    def __init__(self):
        self.agents: Dict[str, AgentConfig] = {}
        self.session_agents: Dict[str, str] = {}  # session_id -> agent_name
    
    def register_agent(self, name: str, config: AgentConfig):
        """Register a custom agent"""
        
    def get_agent_system_prompt(self, agent_name: str) -> str:
        """Get system prompt for an agent"""
        
    def set_session_agent(self, session_id: str, agent_name: str):
        """Set agent for a specific session"""

4. System Prompt Integration

Modify src/claude_cli.py:127-131 to support agent-specific prompts:

# Current code uses:
options.system_prompt = {"type": "text", "text": system_prompt}

# Enhance to:
if agent_name and agent_manager.has_agent(agent_name):
    agent_prompt = agent_manager.get_agent_system_prompt(agent_name)
    combined_prompt = f"{agent_prompt}\n\n{system_prompt}" if system_prompt else agent_prompt
    options.system_prompt = {"type": "text", "text": combined_prompt}

5. New API Endpoints

Add to src/main.py:

@app.post("/v1/agents/register")
async def register_custom_agents(request: CustomAgentsRequest):
    """Register custom agents"""
    
@app.get("/v1/agents")
async def list_agents():
    """List available agents"""
    
@app.post("/v1/sessions/{session_id}/agent")
async def set_session_agent(session_id: str, request: SessionAgentRequest):
    """Set agent for a session"""

6. Output Style System

Create src/output_styles.py:

class OutputStyleManager:
    def __init__(self):
        self.styles = {
            "default": lambda response: response,
            "concise": self._concise_style,
            "detailed": self._detailed_style
        }
    
    def apply_style(self, response: str, style: str) -> str:
        """Apply output style transformation"""

🛠 Implementation Plan

Phase 1: Core Agent System

1. Add CLI argument parsing to main.py
2. Create AgentManager class
3. Add agent configuration models
4. Integrate with existing system prompt handling

Phase 2: API Extensions

1. Add agent management endpoints
2. Extend session management for per-session agents
3. Add agent validation and error handling

Phase 3: Output Styles

1. Create OutputStyleManager
2. Add style configuration to agent configs
3. Integrate style application into response pipeline

Phase 4: Testing & Documentation

1. Add comprehensive tests for agent functionality
2. Update API documentation
3. Add example configurations

📝 Usage Examples (After Implementation)

CLI Usage:

# Single agent
python main.py --agent reviewer

# Multiple agents via JSON
python main.py --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"},"refactor":{"description":"Refactors code","prompt":"You are a refactoring specialist"}}'

API Usage:

# Register agents
curl -X POST http://localhost:8000/v1/agents/register \
  -d '{"agents": {"reviewer": {"description": "Reviews code", "prompt": "You are a code reviewer"}}}'

# Use agent in chat
curl -X POST http://localhost:8000/v1/chat/completions \
  -d '{"model": "claude-sonnet-4-5-20250929", "messages": [...], "extra_body": {"agent": "reviewer"}}'

🔗 Integration Points

The implementation would integrate with existing systems:

• Session Manager (src/session_manager.py) - for per-session agents
• Tool Manager (src/tool_manager.py) - for agent-specific tool configurations
• Message Adapter (src/message_adapter.py) - for output style transformations
• Parameter Validator (src/parameter_validator.py) - for agent validation

This approach maintains OpenAI API compatibility while adding the requested agent functionality as an extension.

---