Spaces:
Sleeping
Sleeping
File size: 3,761 Bytes
116524e | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 | # Claude SDK Integration
The Claude SDK integration provides composable ACE steps for the
[Anthropic Python SDK](https://docs.anthropic.com/en/api/client-sdks). Use it
when you want direct Messages API access inside your own pipeline instead of a
prebuilt runner.
## Quick Start
```python
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
```bash
uv add ace-framework[claude-sdk]
```
For observability, also install and configure Logfire:
```bash
uv add ace-framework[logfire]
```
```python
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
```python
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](../guides/integration.md) — the shared
INJECT/EXECUTE/LEARN design
- [Composing Pipelines](../guides/composing-pipelines.md) — mix SDK steps with
other ACE steps
|