Metadata-Version: 2.4
Name: chatsee-claude-agent-sdk
Version: 0.1.0
Summary: ChatSee connector for the Claude Agent SDK — capture every turn with one line.
Maintainer-email: ChatSee <contact@chatsee.ai>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: chatsee-ai>=0.14.0
Requires-Dist: claude-agent-sdk>=0.2.100
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: chatsee-connector-testing; extra == "dev"

# chatsee-claude-agent-sdk

ChatSee connector for the **Claude Agent SDK** — Anthropic's agent framework,
the one that powers Claude Code.

```bash
pip install chatsee-claude-agent-sdk
```

```python
from chatsee_claude_agent_sdk import instrument_claude_agent_sdk

chatsee = instrument_claude_agent_sdk(agent_id="...", tenant_id="...")

async for message in chatsee.query(prompt="where is my order", options=opts):
    ...
```

`chatsee-ai` is installed for you as a dependency.

## Not the same thing as `chatsee-anthropic`

| | `chatsee-anthropic` | this |
| --- | --- | --- |
| Package it hooks | `anthropic` | `claude-agent-sdk` |
| Who writes the agent loop | the customer | Anthropic |
| What we hook | `client.messages.create` | the `query()` message stream |

Use `chatsee-anthropic` when they call the Messages API and run their own
tool-use loop. Use this when they call `query()` and let the SDK run it.

## Why a handle rather than a one-liner

There is no client object to patch — the entry point is a module-level
`query()`. So `instrument_claude_agent_sdk` returns a handle whose `.query` is
a drop-in: every message still reaches the caller, unchanged and in order,
while the turn is assembled alongside.

`claude_agent_sdk.query` is replaced too, so code calling it **through the
module** needs no change. Code that did `from claude_agent_sdk import query`
already holds its own reference to the original and cannot be reached that way
— that code uses the handle.

## What it captures

Per turn: the prompt, the final answer, the system prompt, every tool call with
its arguments and result, and **one model call per model**, with tokens, cached
tokens and a real dollar cost.

This SDK is the only one that states its own cost (`total_cost_usd`), so that
figure is passed through rather than estimated. Nothing here invents a price,
and a turn's cost is never divided across models — a split we made up would
look like measurement.

## Three things this framework does that nothing else does

**The CLI's system prompt is enormous.** Claude Code injects roughly 21k cached
tokens on every call, so a one-line "hello" costs around $0.027. Those land in
`cache_read_input_tokens`, not `input_tokens` — both are captured, or the turn
looks far cheaper than the bill.

**The CLI calls its own tools.** It loads tools on demand and emits a
`ToolSearch` tool-use alongside the agent's real one. Those are filtered: a
support agent that never touched a search tool must not show one in its trace.

**Tool names arrive MCP-qualified.** Custom tools reach the model as
`mcp__<server>__<tool>`. The customer named it `get_order_status`, so the
prefix is stripped and that is what the screens say.

## Guarantees

* **Fails open.** A failure inside capture is logged and swallowed.
* **Never consumes the stream.** Every message is forwarded unchanged, in order.
* **Idempotent.** Instrumenting twice does not capture twice.
* **Concurrency-safe.** State is per `query()` call, not per handle.

All four are enforced by the contract suite, not just intended.

## Tests

No network, no API key, no CLI subprocess — the SDK is stubbed, ChatSee is not.
That matters more here than anywhere else: a real turn costs about $0.027, so
finding a capture bug by running one would be slow and expensive.

```bash
pip install -e python/connectors/_shared
pip install -e python/connectors/ai_sdk/claude_agent_sdk
pytest python/connectors/ai_sdk/claude_agent_sdk/tests -q
```

## Known gap

Turn-level `duration_ms` comes from the tracker's own wall clock, and all four
tracker calls are made together once the turn is known to be complete — so it
reads near zero. The honest latency is on the model call, from the SDK's
`duration_api_ms`. Fixing it properly means letting `end_turn` accept a
measured duration, which is a core-SDK change and not this connector's to make.
