zeno-provider-claude

Claude Agent SDK provider for Zeno. Wraps claude-agent-sdk (ClaudeSDKClient) behind Zeno's Provider Protocol so an Agent definition stays portable across providers.

Install

uv add 'zeno-framework[claude]'

The zeno-framework meta-package ships Claude as the default; this extra is the explicit form for environments that pin extras.

Usage

from zeno.agent import Agent
from zeno.app import ZenoApp
from zeno.channels.cli.channel import CliChannel
from zeno.providers.claude_sdk import ClaudeSDKProvider

app = ZenoApp(
    agent=Agent(
        name="root",
        instructions="You are a helpful personal assistant.",
        permission_mode="bypassPermissions",
    ),
    channels=[CliChannel()],
    provider=ClaudeSDKProvider(),
)

ClaudeSDKProvider reads ANTHROPIC_API_KEY from the environment via the underlying SDK. Set it before app.start(). If the env var is unset, start() logs a warning at the zeno.providers.claude_sdk logger pointing at both auth paths (env var + claude login OAuth) — OAuth users can ignore it; users who haven't set up either get a clear hint before the first turn fails.

Resuming SDK sessions

Pass a session_lookup callable to resume a prior SDK session keyed by (user_id, channel, thread_key):

async def lookup_session(user_id: str, channel: str, thread_key: str | None) -> str | None:
    return await my_store.get_sdk_session_id(user_id, channel, thread_key)


provider = ClaudeSDKProvider(session_lookup=lookup_session)

When session_lookup returns None (or is omitted), each turn starts a fresh SDK session.

Capabilities

ClaudeSDKProvider is the only Zeno provider that supports:

• sub_agents — Claude Agent SDK dispatch via AgentDefinition
• built_in_tools — WebSearch, WebFetch, Bash, etc.
• permission_mode — default / acceptEdits / bypassPermissions / plan
• Streaming assistant text via ctx.stream(...)
• SDK hook bridge (PreToolUse / PostToolUse / UserPromptSubmit and the optional SubagentStart / SubagentStop / PostToolUseFailure hooks when available) translated into Zeno trace events.

See also

• zeno-provider-openai — OpenAI-compatible alternative (OpenRouter, LiteLLM, Azure, Ollama, etc.).
• docs/subagents.md — orchestrator + specialist composition.
• docs/adapters.md — writing your own Provider.

Part of the Zeno framework.