docs/integrations/claude-sdk.md

Claude SDK Integration

The Claude SDK integration provides composable ACE steps for the Anthropic Python SDK. Use it when you want direct Messages API access inside your own pipeline instead of a prebuilt runner.

Quick Start

from ace import Pipeline, Reflector, SkillManager, Skillbook, learning_tail
from ace.integrations import ClaudeSDKExecuteStep, ClaudeSDKToTrace

skillbook = Skillbook()
pipe = Pipeline([
    ClaudeSDKExecuteStep(model="claude-sonnet-4-20250514"),
    ClaudeSDKToTrace(),
    *learning_tail(Reflector("gpt-4o-mini"), SkillManager("gpt-4o-mini"), skillbook),
])

Installation

uv add ace-framework[claude-sdk]

For observability, also install and configure Logfire:

uv add ace-framework[logfire]

from ace.observability import configure_logfire

configure_logfire()

What It Provides

• ClaudeSDKExecuteStep — injects skillbook context, calls the Anthropic Messages API, and writes a validated ClaudeSDKResult to ctx.trace
• ClaudeSDKToTrace — converts ClaudeSDKResult into the standard ACE trace dict consumed by ReflectStep
• ClaudeSDKResult — Pydantic model with validated output, token usage, latency, tool calls, and raw response access
• ToolCall — Pydantic model for captured Claude tool invocations

Parameters

ClaudeSDKExecuteStep

Parameter	Type	Default	Description
model	str	"claude-sonnet-4-20250514"	Claude model ID
system_prompt	str | None	None	Base system prompt
max_tokens	int	4096	Maximum output tokens
temperature	float	0.0	Sampling temperature
tools	list[dict] | None	None	Anthropic tool definitions
api_key	str | None	None	Optional API key override
base_url	str | None	None	Optional API base URL
inject_skillbook	bool	True	Prepend skillbook context to the system prompt
client	Any	None	Injected Anthropic client for testing or custom transport

Observability

When Logfire is configured, the step emits three layers of observability:

1. Step-level logfire.span(...) around ClaudeSDKExecuteStep
2. Structured logfire.info(...) and logfire.error(...) events with tokens, latency, stop reason, and tool counts
3. logfire.instrument_anthropic(client) auto-instrumentation for the underlying SDK calls

The result model also captures:

• input_tokens
• output_tokens
• total_tokens
• latency_seconds
• stop_reason
• tool_calls

Tool Use

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "input_schema": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    }
]

execute = ClaudeSDKExecuteStep(
    model="claude-sonnet-4-20250514",
    tools=tools,
)

If Claude returns tool use blocks, they are captured on ClaudeSDKResult.tool_calls as validated ToolCall models.

Validation

ClaudeSDKExecuteStep validates its configuration with Pydantic before the client is constructed. ClaudeSDKResult and ToolCall are also Pydantic models, so invalid token counts, latency values, or malformed tool calls are rejected early.

What to Read Next

• Integration Pattern — the shared INJECT/EXECUTE/LEARN design
• Composing Pipelines — mix SDK steps with other ACE steps