feat: add Claude Agent SDK provider integration #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open

spumer wants to merge 9 commits into FradSer:main from spumer:claude/migrate-agno-to-claude-sdk-017HRR68qrsLRXxUhY9DiH3C

.env.example

-Original file line number
+Diff line change
@@ -1,12 +1,14 @@
     # --- LLM Configuration ---
-    # Select the LLM provider: "deepseek" (default), "groq", "openrouter", "github", or "ollama"
+    # Select the LLM provider: "claude-agent-sdk", "deepseek" (default), "groq", "openrouter", "github", "anthropic", or "ollama"
     LLM_PROVIDER="deepseek"
     # Provide the API key for the chosen provider:
     # GROQ_API_KEY="your_groq_api_key"
     DEEPSEEK_API_KEY="your_deepseek_api_key"
     # OPENROUTER_API_KEY="your_openrouter_api_key"
     # GITHUB_TOKEN="ghp_your_github_personal_access_token"
+    # ANTHROPIC_API_KEY="your_anthropic_api_key"
+    # Note: Claude Agent SDK requires NO API KEY - uses local Claude Code installation
     # Note: Ollama requires no API key but needs local installation
     # Note: GitHub Models requires a GitHub Personal Access Token with appropriate scopes
@@ Expand All / @@ -15,12 +17,18 @@ LLM_BASE_URL="your_base_url_if_needed" @@
     # Optional: Specify different models for Enhanced (Complex Synthesis) and Standard (Individual Processing)
     # Defaults are set within the code based on the provider if these are not set.
+    # Example for Claude Agent SDK (uses local Claude Code - no API key needed):
+    # CLAUDE_AGENT_SDK_ENHANCED_MODEL_ID="claude-sonnet-4-5"  # For complex synthesis
+    # CLAUDE_AGENT_SDK_STANDARD_MODEL_ID="claude-sonnet-4-5"  # For individual processing
     # Example for Groq:
     # GROQ_ENHANCED_MODEL_ID="openai/gpt-oss-120b"  # For complex synthesis
     # GROQ_STANDARD_MODEL_ID="openai/gpt-oss-20b"  # For individual processing
     # Example for DeepSeek:
     # DEEPSEEK_ENHANCED_MODEL_ID="deepseek-chat"  # For complex synthesis
     # DEEPSEEK_STANDARD_MODEL_ID="deepseek-chat"  # For individual processing
+    # Example for Anthropic:
+    # ANTHROPIC_ENHANCED_MODEL_ID="claude-3-5-sonnet-20241022"  # For complex synthesis
+    # ANTHROPIC_STANDARD_MODEL_ID="claude-3-5-haiku-20241022"  # For individual processing
     # Example for GitHub Models:
     # GITHUB_ENHANCED_MODEL_ID="openai/gpt-5"  # For complex synthesis
     # GITHUB_STANDARD_MODEL_ID="openai/gpt-5-min"  # For individual processing
@@ Expand Down Expand Up / @@ -103,4 +111,26 @@ MAX_RETRIES="3" @@
     TIMEOUT="30.0"
     PERFORMANCE_MONITORING="true"  # Enable real-time performance monitoring
     PERFORMANCE_BASELINE_TIME="30.0"  # Baseline time per thought in seconds
-    PERFORMANCE_BASELINE_EFFICIENCY="0.8"  # Target efficiency score
+    PERFORMANCE_BASELINE_EFFICIENCY="0.8"  # Target efficiency score
+    # --- Claude Agent SDK Advanced Configuration ---
+    # These settings are ONLY used when LLM_PROVIDER="claude-agent-sdk"
+    # Claude Agent SDK uses local Claude Code - no API key required
+    # Quick Setup Example:
+    # LLM_PROVIDER="claude-agent-sdk"
+    # CLAUDE_AGENT_SDK_ENHANCED_MODEL_ID="claude-sonnet-4-5"
+    # CLAUDE_AGENT_SDK_STANDARD_MODEL_ID="claude-sonnet-4-5"
+    # Advanced Features (all optional):
+    # CLAUDE_SDK_PERMISSION_MODE="bypassPermissions"  # Options: "default", "acceptEdits", "plan", "bypassPermissions"
+    # CLAUDE_SDK_CWD="/path/to/working/directory"  # Working directory for file operations
+    # CLAUDE_SDK_ADD_DIRS="/path/to/extra/context,/another/path"  # Comma-separated additional directories for context
+    # Note: The following advanced features are available but configured programmatically:
+    # - Structured outputs support (automatic via Agno response_format)
+    # - Tool choice strategies (automatic via Agno tool_choice)
+    # - Session continuation (automatic via Agno session_id)
+    # - Usage tracking (automatic - tokens, cache, stop_reason)
+    # - User context (automatic via Agno user_id)
+    # See CLAUDE.md for detailed documentation on these features

CLAUDE.md

-Original file line number
+Diff line change
@@ Expand Up @@
     ### Configuration & Data Flow
     **Environment Variables:**
-    - `LLM_PROVIDER`: Provider selection (deepseek, groq, openrouter, ollama, github, anthropic)
-    - `{PROVIDER}_API_KEY`: API keys (e.g., `DEEPSEEK_API_KEY`, `GITHUB_TOKEN`)
+    - `LLM_PROVIDER`: Provider selection (deepseek, groq, openrouter, ollama, github, anthropic, claude-agent-sdk)
+    - `{PROVIDER}_API_KEY`: API keys (e.g., `DEEPSEEK_API_KEY`, `GITHUB_TOKEN`) - **Not required for claude-agent-sdk**
     - `{PROVIDER}_ENHANCED_MODEL_ID`: Enhanced model for complex synthesis (Blue Hat)
     - `{PROVIDER}_STANDARD_MODEL_ID`: Standard model for individual hat processing
     - `EXA_API_KEY`: Research capabilities (if using research agents)
@@ Expand Down Expand Up @@
     **Examples:**
     ```bash
+    # Claude Agent SDK (uses local Claude Code - no API key needed!)
+    LLM_PROVIDER="claude-agent-sdk"
+    # No API key required - uses locally installed Claude Code
+    # Model IDs are informational - Claude Code uses its internal models
+    CLAUDE_AGENT_SDK_ENHANCED_MODEL_ID="claude-sonnet-4-5"  # Both synthesis and processing
+    CLAUDE_AGENT_SDK_STANDARD_MODEL_ID="claude-sonnet-4-5"
     # GitHub Models
     GITHUB_ENHANCED_MODEL_ID="openai/gpt-5"      # Blue Hat synthesis
     GITHUB_STANDARD_MODEL_ID="openai/gpt-5-min"  # Individual hats
@@ Expand Down Expand Up @@
     **For Agno Documentation**: Use deepwiki MCP reference with repoName: `agno-agi/agno`
+    ## Claude Agent SDK Advanced Features
+    The Claude Agent SDK provider supports comprehensive Agno integration with advanced features:
+    ### Structured Outputs Support
+    **Response Format Configuration:**
+    The SDK supports structured outputs through Agno's `response_format` parameter:
+    ```python
+    from pydantic import BaseModel
+    class ThinkingResult(BaseModel):
+        """Structured thinking output"""
+        analysis: str
+        confidence: float
+        key_insights: list[str]
+    # Agent automatically uses this schema
+    agent = Agent(
+        model=claude_sdk_model,
+        output_schema=ThinkingResult  # Converted to system prompt instructions
+    )
+    ```
+    **Supported Formats:**
+    - **Pydantic BaseModel**: Full schema with validation (converted to JSON schema in system prompt)
+    - **JSON Mode**: `{"type": "json_object"}` for generic JSON output
+    - **Custom Schemas**: Dict-based schemas with properties
+    **How it Works:**
+    - `supports_native_structured_outputs()` returns `True` for Agno compatibility
+    - Schema is converted to detailed system prompt instructions
+    - Claude follows the schema structure via system prompt guidance
+    - Reliable structured output without native SDK support
+    ### Tool Choice Strategies
+    **Fine-grained Tool Control:**
+    ```python
+    agent = Agent(
+        model=claude_sdk_model,
+        tools=[ReasoningTools],
+        tool_choice="required"  # Force tool usage
+    )
+    # Available strategies:
+    # - "none": Disable all tools
+    # - "auto": Model decides (default)
+    # - "required" / "any": Model must use tools
+    # - {"type": "tool", "name": "Think"}: Specific tool only
+    ```
+    **Automatic Mapping:**
+    - `tool_choice="none"` → All tools added to `disallowed_tools`
+    - `tool_choice="required"` → Keep `allowed_tools` as-is
+    - Specific tool selection → Only that tool in `allowed_tools`, rest in `disallowed_tools`
+    ### Session Continuation and User Context
+    **Automatic Session Tracking:**
+    ```python
+    # Agno automatically provides session_id and user_id
+    agent.arun(
+        "Continue our previous discussion",
+        session_id="abc123",  # Extracted automatically
+        user_id="user_456"     # Used for personalization
+    )
+    # SDK automatically:
+    # - Sets continue_conversation=True
+    # - Passes user context: {"id": "user_456"}
+    # - Maintains conversation continuity
+    ```
+    **Benefits:**
+    - Multi-Thinking sequences maintain context across hat switches
+    - User-specific personalization
+    - Session history preservation
+    ### Usage and Cost Tracking
+    **Automatic Metadata Extraction:**
+    Every response includes comprehensive usage data:
+    ```python
+    response = await agent.arun("Analyze this problem")
+    # Available in response.provider_data:
+    {
+        "usage": {
+            "input_tokens": 1500,
+            "output_tokens": 800,
+            "cache_creation_input_tokens": 200,
+            "cache_read_input_tokens": 1000,
+            "stop_reason": "end_turn",
+            "model_used": "claude-sonnet-4-5"
+        },
+        "run_metadata": {
+            "session_id": "abc123",
+            "user_id": "user_456",
+            "run_id": "run_789"
+        },
+        "response_format_used": True,
+        "tool_choice_used": "auto",
+        "session_continuation": True
+    }
+    ```
+    **Use Cases:**
+    - Cost analysis and budget tracking
+    - Performance monitoring
+    - Cache efficiency optimization
+    - Debugging and troubleshooting
+    ### Advanced Configuration
+    **All Supported ClaudeAgentOptions:**
+    ```python
+    from pathlib import Path
+    model = ClaudeAgentSDKModel(
+        model_id="claude-sonnet-4-5",
+        # Permission control
+        permission_mode="bypassPermissions",  # default, acceptEdits, plan, bypassPermissions
+        # File system access
+        cwd="/path/to/project",
+        add_dirs=[Path("/extra/context")],
+        # MCP servers
+        mcp_servers={
+            "filesystem": {"path": "/path/to/mcp/config"}
+        },
+        # Environment
+        env={"DEBUG": "1", "CUSTOM_VAR": "value"},
+        # Event hooks
+        hooks={
+            "PreToolUse": [lambda ctx: print(f"Using {ctx.tool_name}")],
+            "PostToolUse": [lambda ctx: print(f"Completed {ctx.tool_name}")]
+        },
+        # Permission callback
+        can_use_tool=async_permission_checker
+    )
+    ```
+    **Automatic Agno Integration:**
+    When used with Agno Agent:
+    - ✅ `response_format` → System prompt schema instructions
+    - ✅ `tool_choice` → Allowed/disallowed tools mapping
+    - ✅ `tools` → Automatic tool name mapping (ReasoningTools → Think)
+    - ✅ `tool_call_limit` → max_turns parameter
+    - ✅ `run_response.session_id` → continue_conversation
+    - ✅ `run_response.user_id` → user context
+    - ✅ Usage metadata → Extracted and tracked
+    ### Multi-Thinking Integration Benefits
+    **For Multi-Thinking Workflow:**
+. **Structured Outputs**: Each hat can return structured JSON for reliable parsing
+. **Tool Control**: Fine-tune which hats use Think tool vs direct responses
+. **Session Context**: Maintain context across all 6 thinking agents
+. **Cost Tracking**: Monitor token usage per hat for optimization
+. **User Personalization**: Context-aware responses based on user history
+    **Example Multi-Thinking Flow:**
+    ```
+    Factual Hat → (session_id: abc123)
+       ↓ usage: 500 input, 200 output tokens
+    Emotional Hat → (session continues, uses cache)
+       ↓ usage: 100 input (400 cached), 150 output
+    Critical Hat → (session continues)
+       ↓ usage: 100 input (400 cached), 250 output
+    ...
+    Synthesis Hat → (full context, structured output)
+       ✓ Total cost tracked across all hats
+       ✓ Cache efficiency: 80% cache hit rate
+    ```
     ## AI-Powered Complexity Analysis
     **Key Innovation**: The system uses AI instead of rule-based pattern matching for complexity analysis:
@@ Expand Down @@

README.md

-Original file line number
+Diff line change
@@ Expand Up @@
     - **AI Selection**: System automatically chooses the right model based on task complexity
     ### Supported Providers:
+    - **Claude Agent SDK** - Use local Claude Code (no API key required!)
+      - ✨ **New: Advanced Agno Integration** - Structured outputs, tool choice strategies, session continuation
+      - ✅ Automatic usage tracking (tokens, cache efficiency, stop_reason)
+      - ✅ User context and session continuity across Multi-Thinking sequences
+      - 📖 See [CLAUDE.md: Claude Agent SDK Advanced Features](CLAUDE.md#claude-agent-sdk-advanced-features) for detailed usage
     - **DeepSeek** (default) - High performance, cost-effective
     - **Groq** - Ultra-fast inference
     - **OpenRouter** - Access to multiple models
@@ Expand Down Expand Up / @@ -339,9 +344,12 @@ Create a `.env` file or set these variables: @@
     ```bash
     # LLM Provider (required)
-    LLM_PROVIDER="deepseek"  # deepseek, groq, openrouter, github, anthropic, ollama
+    LLM_PROVIDER="deepseek"  # deepseek, groq, openrouter, github, anthropic, ollama, claude-agent-sdk
     DEEPSEEK_API_KEY="sk-..."
+    # Or use Claude Agent SDK (no API key needed!)
+    # LLM_PROVIDER="claude-agent-sdk"  # Requires Claude Code installed locally
     # Optional: Enhanced/Standard Model Selection
     # DEEPSEEK_ENHANCED_MODEL_ID="deepseek-chat"  # For synthesis
     # DEEPSEEK_STANDARD_MODEL_ID="deepseek-chat"  # For other agents
@@ Expand Down @@

pyproject.toml

-Original file line number
+Diff line change
@@ Expand Up / @@ -19,6 +19,7 @@ dependencies = [ @@
         "openrouter",
         "httpx[socks]>=0.28.1",
         "sqlalchemy",
+        "claude-agent-sdk",
     ]
     [project.optional-dependencies]
@@ Expand Down @@

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add Claude Agent SDK provider integration #35

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

feat: add Claude Agent SDK provider integration #35

Are you sure you want to change the base?

Uh oh!

feat: add Claude Agent SDK provider integration #35

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!