Skip to content

Commit e14df89

Browse files
committed
feat(claude-agent-sdk): add @traceai/claude-agent-sdk for TypeScript
New package typescript/packages/traceai_claude_agent_sdk. wrapQuery() wraps the SDK's exported query() and turns its message stream into conversation, assistant_turn, tool_execution, mcp_tool and subagent spans. Each span keeps the Python claude_agent.span_kind string and sets gen_ai.span.kind and fi.span.kind. The conversation span falls back to CHAIN because TS FISpanKind has no CONVERSATION. The attribute names are copied from the Python _attributes.py, and a test fails when one is missing. Tokens and cost come from the result message. Cost is also written to gen_ai.cost.total, the key the collector promotes. The session id goes to session.id. The wrapper also records fork origin, provider (custom when ANTHROPIC_BASE_URL is not an anthropic.com host), abort and errors. Prompts, tool inputs and outputs, and assistant text are hidden unless hideInputs/hideOutputs or FI_HIDE_* opt in. This is stricter than the Python package. @anthropic-ai/claude-agent-sdk (Anthropic Commercial Terms) is a peer dependency, ^0.3.142. It is never imported at runtime or bundled. The contract test packs the tarball and checks it holds no SDK file or native binary. Tests: 40 jest tests, plus shared-harness contract tests. The contract tests send fixture journeys and the real SDK 0.3.289 / 0.3.142 CLI, pointed at a loopback Messages mock through options.env .ANTHROPIC_BASE_URL, through fi-core to the harness Receiver. No Anthropic call. pnpm-lock.yaml gets only this importer and the 15 packages/snapshots it needs. pnpm 10.30.1 also re-resolved other importers' ts-node peers, and those changes were left out. Refs: TH-8235
1 parent 3eaadc8 commit e14df89

25 files changed

Lines changed: 4022 additions & 0 deletions

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -331,6 +331,7 @@ var tracer = TraceAI.Register(opts =>
331331
| [`@traceai/mastra`](https://www.npmjs.com/package/@traceai/mastra) | Mastra | [![npm](https://img.shields.io/npm/v/@traceai/mastra)](https://www.npmjs.com/package/@traceai/mastra) |
332332
| [`@traceai/beeai`](https://www.npmjs.com/package/@traceai/beeai) | IBM BeeAI | [![npm](https://img.shields.io/npm/v/@traceai/beeai)](https://www.npmjs.com/package/@traceai/beeai) |
333333
| [`@traceai/strands`](https://www.npmjs.com/package/@traceai/strands) | AWS Strands Agents | [![npm](https://img.shields.io/npm/v/@traceai/strands)](https://www.npmjs.com/package/@traceai/strands) |
334+
| [`@traceai/claude-agent-sdk`](https://www.npmjs.com/package/@traceai/claude-agent-sdk) | Claude Agent SDK (`query()`) | [![npm](https://img.shields.io/npm/v/@traceai/claude-agent-sdk)](https://www.npmjs.com/package/@traceai/claude-agent-sdk) |
334335

335336
#### Tools and Libraries
336337

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# @traceai/claude-agent-sdk
2+
3+
OpenTelemetry tracing for the TypeScript [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) `query()`, exported to Future AGI through `@traceai/fi-core`.
4+
5+
Alpha. Tested against `@anthropic-ai/claude-agent-sdk` 0.3.289 with recorded message fixtures and with the real SDK and bundled CLI pointed at a loopback mock of the Messages API. No live Anthropic call was made.
6+
7+
This is not the Python package (`traceAI-claude-agent-sdk`), not Claude Code CLI session tracing, and not the Anthropic Messages API instrumentation (`@traceai/anthropic`).
8+
9+
## Licence of the SDK
10+
11+
`@anthropic-ai/claude-agent-sdk` is under the Anthropic Commercial Terms, not an OSI licence. It is a **peer dependency**: install it yourself. This package never bundles or re-exports the SDK or its CLI binary, and does not import it at runtime.
12+
13+
| Item | Value |
14+
|---|---|
15+
| Tested pin | `@anthropic-ai/claude-agent-sdk` 0.3.289 (npm shasum `36c710c40a2d9761d6c12c42b469d002e64e9be8`) |
16+
| Peer range | `^0.3.142` (0.3.142 is the oldest 0.3.x on npm; its `query()` and the message fields read here match 0.3.289, and the real-SDK contract test passed against it) |
17+
| Node | 18, 20, 22 (CJS and ESM import checked); the SDK itself declares `node >=18` |
18+
19+
## Install
20+
21+
```bash
22+
npm install @traceai/claude-agent-sdk @traceai/fi-core @anthropic-ai/claude-agent-sdk
23+
```
24+
25+
## Use
26+
27+
The SDK is ESM-only and its module namespace cannot be patched, so wrap `query` and call the wrapped function:
28+
29+
```typescript
30+
import { register, ProjectType } from "@traceai/fi-core";
31+
import { query } from "@anthropic-ai/claude-agent-sdk";
32+
import { wrapQuery, shutdown } from "@traceai/claude-agent-sdk";
33+
34+
const tracerProvider = register({
35+
projectType: ProjectType.OBSERVE,
36+
projectName: "my-agent", // or FI_PROJECT_NAME; the collector drops a batch with no project_name
37+
});
38+
39+
const tracedQuery = wrapQuery(query, { tracerProvider });
40+
41+
for await (const message of tracedQuery({ prompt: "Summarize the README.", options: { maxTurns: 3 } })) {
42+
// the same message objects the SDK yielded
43+
}
44+
45+
await shutdown(); // flush before a short script exits
46+
```
47+
48+
`FI_API_KEY` and `FI_SECRET_KEY` are read by fi-core and sent as the `X-Api-Key` / `X-Secret-Key` headers. They are never copied onto spans.
49+
50+
`ClaudeAgentSDKInstrumentation` (or `instrumentClaudeAgentSDK()`) does the same with an object you keep: `instrumentation.wrapQuery(query)`, `instrumentation.forceFlush()`.
51+
52+
### What the wrapper does and does not do
53+
54+
- Calls the original `query()` with the same params object. Options (`resume`, `forkSession`, `sessionId`, `hooks`, `mcpServers`, `agents`, `abortController`, `allowedTools`, `permissionMode`, `maxTurns`, `env`, ...) are passed through untouched. The wrapper never sets `ANTHROPIC_BASE_URL`.
55+
- Yields the same message objects, in order. Control methods on the returned `Query` (`interrupt()`, `setModel()`, ...) go to the original.
56+
- A tracing error never fails the agent. An exporter or collector failure is logged and does not reject the iterator.
57+
- `startup()` is not wrapped in 0.1.0.
58+
59+
## Spans
60+
61+
| Span name | `claude_agent.span_kind` | `gen_ai.span.kind` / `fi.span.kind` | Parent |
62+
|---|---|---|---|
63+
| `claude_agent.conversation` | `conversation` | `CHAIN` (TS fi-semantic-conventions has no `CONVERSATION`) | caller's active span |
64+
| `claude_agent.assistant_turn` | `assistant_turn` | `LLM` | conversation, or the subagent span inside a subagent |
65+
| `tool.<name>` | `tool_execution`, or `mcp_tool` for `mcp__<server>__<tool>` | `TOOL` | the assistant turn that issued the `tool_use` |
66+
| `claude_agent.subagent.<subagent_type>` | `subagent` | `AGENT` | the `tool.Agent` / `tool.Task` span |
67+
68+
One API response that the SDK splits over several assistant messages (same `message.id`) is one turn.
69+
70+
| Field | Attributes | Source |
71+
|---|---|---|
72+
| Model | `gen_ai.request.model`, `claude_agent.model` | `options.model`, the init message, each assistant message |
73+
| Provider | `gen_ai.provider.name` = `anthropic`, or `custom` when `ANTHROPIC_BASE_URL` (from `options.env`, else `process.env`) is not an `anthropic.com` host | |
74+
| Tokens | `gen_ai.usage.input_tokens`, `output_tokens`, `total_tokens`; `gen_ai.usage.cache_read_tokens` / `cache_creation_tokens` when present | result message, on the conversation span |
75+
| Cost | `claude_agent.cost.total_usd` and `gen_ai.cost.total` | result `total_cost_usd`; never computed here |
76+
| Session | `session.id`, `claude_agent.session.id`, `claude_agent.session_id`; `claude_agent.session.fork_from` on fork | init / result `session_id`, `options.sessionId`, `options.resume` |
77+
| Tools | `claude_agent.tool.name`, `gen_ai.tool.name`, `use_id`, `source` (`builtin` / `mcp` / `custom`), `is_error`, `duration_ms` | `tool_use` / `tool_result` blocks |
78+
| Errors | span status ERROR; `claude_agent.error.type` / `error.message`; `claude_agent.cancelled=true` on abort | error result, thrown error, `is_error` tool results, `AbortController` |
79+
80+
The `claude_agent.*` names are the Python package's names (`_attributes.py`); a test fails if one is missing.
81+
82+
An app-set fi-core `session.id` / `user.id` (fi-core context helpers) is kept; the SDK session id still goes to `claude_agent.session.id`.
83+
84+
## Privacy: content is off by default
85+
86+
Prompts, system prompts, tool inputs, tool outputs, assistant text and the final result can contain source code, file contents or secrets. They are **not** recorded unless you opt in:
87+
88+
```typescript
89+
wrapQuery(query, { tracerProvider, traceConfig: { hideInputs: false, hideOutputs: false } });
90+
// or: FI_HIDE_INPUTS=false FI_HIDE_OUTPUTS=false
91+
```
92+
93+
This is stricter than fi-core's own default and than the Python package, which records the prompt and tool input/output unconditionally.
94+
95+
## Flushing and batching
96+
97+
`shutdown()` calls `forceFlush()` on the provider(s) you passed (or the global provider). It does not shut the provider down. The wrapper has no queue of its own.
98+
99+
fi-core's `register()` exports each span through its default `SimpleSpanProcessor`. At the fi-core version in this repo, `register({ batch: true })` does not replace that processor with OpenTelemetry `sdk-trace-base` 2.x. If you want batching, build a provider with a `BatchSpanProcessor` yourself (`OTEL_BSP_MAX_QUEUE_SIZE`, default 2048).
100+
101+
## Pointing the SDK at a mock or gateway
102+
103+
There is no `baseURL` option. `options.env` **replaces** the CLI subprocess environment, so spread `process.env` (or pass `PATH`, `HOME`, ...) and add `ANTHROPIC_BASE_URL`:
104+
105+
```typescript
106+
options: { env: { ...process.env, ANTHROPIC_BASE_URL: "http://127.0.0.1:8080" } }
107+
```
108+
109+
With 0.3.289 the CLI then calls `POST {ANTHROPIC_BASE_URL}/v1/messages?beta=true` with `stream: true` (observed in `contract/run_real_sdk.mjs`).
110+
111+
## Troubleshooting
112+
113+
- **No traces.** `register()` needs `projectName` or `FI_PROJECT_NAME`.
114+
- **Zero spans from a short script.** `await shutdown()` before exit.
115+
- **Duplicate model spans.** Do not also run a provider instrumentor on the same calls.
116+
- **A span left open after abort.** Every span for the query is ended with status ERROR and `claude_agent.cancelled=true` when its `AbortController` aborts. Anything else is a bug here.
117+
118+
## Tests
119+
120+
```bash
121+
pnpm --filter @traceai/claude-agent-sdk test # jest: wrapper, parity, fi-core export contract
122+
```
123+
124+
The shared-harness contract tests (`contract/test_harness_contract.py`) run the built package in Node against the Python OTLP `Receiver`, run the real SDK against a loopback Messages API mock, pack the tarball and check it holds no SDK file or native binary, and import the package as CJS and ESM. See the module docstring for the command.
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
'use strict';
2+
/**
3+
* Contract script for the shared Python harness (python/tests/harness).
4+
*
5+
* Runs the built package (dist/src, CommonJS) with the real fi-core register()
6+
* and the real OTLP/HTTP exporter. The Claude Agent SDK is replaced by a fake
7+
* query() that yields SDK-typed fixture messages: no CLI, no Anthropic call.
8+
*
9+
* Env:
10+
* FI_BASE_URL, FI_API_KEY, FI_SECRET_KEY, FI_PROJECT_NAME read by fi-core
11+
* CONTRACT_FIXTURES_DIR compiled src/__tests__/fixtures (messages.js, fakeQuery.js)
12+
* JOURNEY simple | subagent | mcp
13+
*
14+
* Prints {"yielded": [...], "expected": [...]} on stdout.
15+
*/
16+
const path = require('path');
17+
18+
const pkgDir = path.resolve(__dirname, '..');
19+
const { register, ProjectType } = require(require.resolve('@traceai/fi-core', { paths: [pkgDir] }));
20+
const { wrapQuery, shutdown } = require(pkgDir);
21+
const fixtures = require(path.join(process.env.CONTRACT_FIXTURES_DIR, 'messages.js'));
22+
const { makeFakeQuery } = require(path.join(process.env.CONTRACT_FIXTURES_DIR, 'fakeQuery.js'));
23+
24+
const JOURNEYS = {
25+
simple: fixtures.simpleToolJourney,
26+
subagent: fixtures.subagentJourney,
27+
mcp: fixtures.mcpErrorJourney,
28+
};
29+
30+
async function main() {
31+
const journey = JOURNEYS[process.env.JOURNEY || 'simple'];
32+
if (!journey) throw new Error(`unknown JOURNEY ${process.env.JOURNEY}`);
33+
34+
// Project name and collector endpoint come from FI_PROJECT_NAME / FI_BASE_URL.
35+
const provider = register({ projectType: ProjectType.OBSERVE, batch: true });
36+
37+
const messages = journey();
38+
const expected = JSON.parse(JSON.stringify(messages));
39+
const fake = makeFakeQuery(messages);
40+
const query = wrapQuery(fake.query, { tracerProvider: provider });
41+
42+
const yielded = [];
43+
for await (const message of query({ prompt: fixtures.PROMPT, options: { model: fixtures.MODEL } })) {
44+
yielded.push(message);
45+
}
46+
47+
await shutdown();
48+
await provider.shutdown();
49+
process.stdout.write(JSON.stringify({ yielded, expected }));
50+
}
51+
52+
main().catch((error) => {
53+
process.stderr.write(`${error && error.stack ? error.stack : error}\n`);
54+
process.exit(1);
55+
});
Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
// Contract script: the REAL @anthropic-ai/claude-agent-sdk query() (and its
2+
// bundled Claude Code CLI) against a loopback mock of the Anthropic Messages
3+
// API, reached through options.env.ANTHROPIC_BASE_URL. No Anthropic call:
4+
// the API key is a placeholder, HTTPS_PROXY/HTTP_PROXY point at a dead
5+
// loopback port, and HOME / CLAUDE_CONFIG_DIR are a fresh temp dir.
6+
//
7+
// The mock answers the first /v1/messages call with a Read tool_use for a temp
8+
// file and the second with text, so the CLI runs one real tool.
9+
//
10+
// Env: FI_BASE_URL, FI_API_KEY, FI_SECRET_KEY, FI_PROJECT_NAME (fi-core).
11+
// CLAUDE_AGENT_SDK_ENTRY (optional): absolute path to another SDK build's
12+
// sdk.mjs, to run the same contract against an older 0.3.x.
13+
// Prints {"requests": [...], "messages": [...]} on stdout.
14+
import http from "node:http";
15+
import fs from "node:fs";
16+
import os from "node:os";
17+
import path from "node:path";
18+
import { ProjectType, register } from "@traceai/fi-core";
19+
import { shutdown, wrapQuery } from "@traceai/claude-agent-sdk";
20+
21+
const { query } = process.env.CLAUDE_AGENT_SDK_ENTRY
22+
? await import(process.env.CLAUDE_AGENT_SDK_ENTRY)
23+
: await import("@anthropic-ai/claude-agent-sdk");
24+
25+
const MOCK_MODEL = "claude-sonnet-4-5";
26+
const PROMPT = "Read README.md and summarize it. SECRET_PROMPT_MARKER";
27+
28+
const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "th8235-real-sdk-"));
29+
const readmePath = path.join(workdir, "README.md");
30+
fs.writeFileSync(readmePath, "# Demo\nSECRET_TOOL_OUTPUT_MARKER\n");
31+
32+
const requests = [];
33+
function sendSse(res, model, blocks, stopReason) {
34+
res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", "request-id": "req_mock" });
35+
const send = (event, data) => res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
36+
send("message_start", {
37+
type: "message_start",
38+
message: {
39+
id: `msg_mock_${requests.length}`, type: "message", role: "assistant", model, content: [],
40+
stop_reason: null, stop_sequence: null,
41+
usage: { input_tokens: 20, output_tokens: 1, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 },
42+
},
43+
});
44+
blocks.forEach((block, index) => {
45+
if (block.type === "text") {
46+
send("content_block_start", { type: "content_block_start", index, content_block: { type: "text", text: "" } });
47+
send("content_block_delta", { type: "content_block_delta", index, delta: { type: "text_delta", text: block.text } });
48+
} else {
49+
send("content_block_start", { type: "content_block_start", index, content_block: { type: "tool_use", id: block.id, name: block.name, input: {} } });
50+
send("content_block_delta", { type: "content_block_delta", index, delta: { type: "input_json_delta", partial_json: JSON.stringify(block.input) } });
51+
}
52+
send("content_block_stop", { type: "content_block_stop", index });
53+
});
54+
send("message_delta", { type: "message_delta", delta: { stop_reason: stopReason, stop_sequence: null }, usage: { output_tokens: 8 } });
55+
send("message_stop", { type: "message_stop" });
56+
res.end();
57+
}
58+
59+
const server = http.createServer((req, res) => {
60+
let body = "";
61+
req.on("data", (chunk) => (body += chunk));
62+
req.on("end", () => {
63+
let parsed = {};
64+
try { parsed = JSON.parse(body || "{}"); } catch { /* not JSON */ }
65+
const hasToolResult = JSON.stringify(parsed.messages ?? []).includes('"tool_result"');
66+
requests.push({
67+
method: req.method,
68+
url: req.url,
69+
stream: parsed.stream === true,
70+
model: parsed.model,
71+
xApiKey: req.headers["x-api-key"] ?? null,
72+
hasToolResult,
73+
});
74+
if (req.method === "POST" && req.url.startsWith("/v1/messages") && !req.url.includes("count_tokens")) {
75+
const model = parsed.model || MOCK_MODEL;
76+
if (!hasToolResult) {
77+
return sendSse(res, model, [
78+
{ type: "text", text: "Reading it. SECRET_ASSISTANT_TEXT_MARKER" },
79+
{ type: "tool_use", id: "toolu_mock_read", name: "Read", input: { file_path: readmePath } },
80+
], "tool_use");
81+
}
82+
return sendSse(res, model, [{ type: "text", text: "It is a demo README." }], "end_turn");
83+
}
84+
res.writeHead(404, { "content-type": "application/json" });
85+
res.end(JSON.stringify({ type: "error", error: { type: "not_found_error", message: "mock" } }));
86+
});
87+
});
88+
await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
89+
const mockOrigin = `http://127.0.0.1:${server.address().port}`;
90+
91+
const provider = register({ projectType: ProjectType.OBSERVE });
92+
const tracedQuery = wrapQuery(query, { tracerProvider: provider });
93+
94+
const abortController = new AbortController();
95+
const timer = setTimeout(() => abortController.abort(), 90_000);
96+
const messages = [];
97+
try {
98+
const stream = tracedQuery({
99+
prompt: PROMPT,
100+
options: {
101+
model: MOCK_MODEL,
102+
cwd: workdir,
103+
maxTurns: 3,
104+
allowedTools: ["Read"],
105+
permissionMode: "default",
106+
settingSources: [],
107+
persistSession: false,
108+
abortController,
109+
// Options.env REPLACES the subprocess environment: pass everything the CLI needs.
110+
env: {
111+
PATH: process.env.PATH,
112+
HOME: workdir,
113+
CLAUDE_CONFIG_DIR: path.join(workdir, ".claude"),
114+
ANTHROPIC_BASE_URL: mockOrigin,
115+
ANTHROPIC_API_KEY: "sk-ant-PLACEHOLDER-not-a-key",
116+
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
117+
DISABLE_TELEMETRY: "1",
118+
DISABLE_ERROR_REPORTING: "1",
119+
DISABLE_AUTOUPDATER: "1",
120+
HTTPS_PROXY: "http://127.0.0.1:9",
121+
HTTP_PROXY: "http://127.0.0.1:9",
122+
NO_PROXY: "127.0.0.1,localhost",
123+
},
124+
},
125+
});
126+
for await (const message of stream) {
127+
messages.push(message);
128+
}
129+
} finally {
130+
clearTimeout(timer);
131+
await shutdown(provider);
132+
await provider.shutdown();
133+
server.close();
134+
fs.rmSync(workdir, { recursive: true, force: true });
135+
}
136+
137+
process.stdout.write(JSON.stringify({ mockOrigin, requests, messages }));

0 commit comments

Comments
 (0)