Claude Agent SDK: Recommended PocketPaw Backend

The Claude Agent SDK backend is the recommended choice for PocketPaw. It uses Anthropic’s official SDK with built-in tools and native MCP support.

Overview

This backend leverages the claude-agent-sdk package, which provides:

• Built-in tools: Bash, Read, Write, Edit — managed by the SDK
• Tool execution hooks: PreToolUse hooks for dangerous command blocking
• MCP integration: Native Model Context Protocol server support
• Streaming: Real-time token-by-token response streaming

Authentication

An Anthropic API key is required when using this backend with the Anthropic provider. This is a hard requirement — PocketPaw will not process messages without one.

export POCKETPAW_ANTHROPIC_API_KEY="sk-ant-..."

This requirement only applies to the Anthropic provider. If you use Ollama (local models), no API key is needed.

Configuration

export POCKETPAW_AGENT_BACKEND="claude_agent_sdk"
export POCKETPAW_ANTHROPIC_API_KEY="sk-ant-..."

Claude SDK Settings

These settings apply specifically to the Claude Agent SDK backend:

# Let Claude Code auto-select the model (recommended — no override needed)
export POCKETPAW_CLAUDE_SDK_MODEL=""

# Or force a specific model
export POCKETPAW_CLAUDE_SDK_MODEL="claude-sonnet-4-5-20250929"

# Increase max turns for complex multi-step tasks
export POCKETPAW_CLAUDE_SDK_MAX_TURNS=50

Provider Support

Using with Ollama

export POCKETPAW_AGENT_BACKEND="claude_agent_sdk"
export POCKETPAW_LLM_PROVIDER="ollama"
export POCKETPAW_OLLAMA_MODEL="qwen2.5:7b"

See Ollama (Local LLMs) for full setup instructions.

Using with LiteLLM

export POCKETPAW_AGENT_BACKEND="claude_agent_sdk"
export POCKETPAW_CLAUDE_SDK_PROVIDER="litellm"
export POCKETPAW_LITELLM_API_BASE="http://localhost:4000"
export POCKETPAW_LITELLM_MODEL="gpt-4o"

The adapter sets ANTHROPIC_BASE_URL to point at the LiteLLM proxy, so the Claude SDK sends Anthropic-format requests to the proxy which translates them for the target provider.

Built-in Tools

The Claude Agent SDK provides these tools natively:

Tool Name Mapping

The SDK uses capitalized tool names internally. PocketPaw maps these to the policy system’s snake_case names:

This mapping is handled by _TOOL_POLICY_MAP in the backend’s info() method.

Safety Hooks

The backend uses PreToolUse hooks to intercept and block dangerous commands before execution:

# Example: Blocking destructive shell commands
async def pre_tool_use(tool_name, tool_input):
    if tool_name == "Bash":
        command = tool_input.get("command", "")
        if is_dangerous_command(command):
            return BlockedResponse("This command has been blocked for safety.")

MCP Server Integration

The Claude Agent SDK has native MCP support. PocketPaw’s _get_mcp_servers() function translates MCP server configurations into the SDK’s expected format:

# MCP servers are loaded from ~/.pocketpaw/mcp.json
# and passed to the SDK during initialization
servers = _get_mcp_servers()

MCP tools are subject to the tool policy system. Use mcp:<server>:* patterns in allow/deny lists:

# Allow all tools from a specific MCP server
export POCKETPAW_TOOLS_ALLOW="mcp:filesystem:*"

# Deny all MCP tools
export POCKETPAW_TOOLS_DENY="group:mcp"

Custom Tools

In addition to the SDK’s built-in tools, PocketPaw registers its own tools (web_search, image_gen, etc.) as custom tool definitions passed to the SDK.

Skill Auto-Discovery

The backend passes setting_sources=["user", "project"] to the SDK, enabling automatic discovery of SKILL.md files from:

• ~/.claude/skills/ — User-level skills
• .claude/skills/ — Project-level skills

This means skills created by the skill_gen tool (which writes to ~/.claude/skills/) are automatically available to the SDK without additional configuration.

Response Format

The backend yields standardized AgentEvent objects (not raw dicts):

AgentEvent(type="message", content="Here's the result...")
AgentEvent(type="tool_use", content="", metadata={"tool": "Bash", "input": {"command": "ls"}})
AgentEvent(type="tool_result", content="file1.txt\nfile2.txt", metadata={"tool": "Bash"})
AgentEvent(type="done", content="")

All backends use the same AgentEvent format, defined in agents/backend.py.

Related