bitfab 0.21.1 → 0.22.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/{chunk-75LZO6JS.js → chunk-4SLFC266.js} +154 -24
- package/dist/chunk-4SLFC266.js.map +1 -0
- package/dist/index.cjs +154 -23
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +141 -20
- package/dist/index.d.ts +141 -20
- package/dist/index.js +3 -1
- package/dist/node.cjs +154 -23
- package/dist/node.cjs.map +1 -1
- package/dist/node.d.cts +1 -1
- package/dist/node.d.ts +1 -1
- package/dist/node.js +3 -1
- package/dist/node.js.map +1 -1
- package/package.json +1 -1
- package/dist/chunk-75LZO6JS.js.map +0 -1
package/dist/index.d.cts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { Trace, Span } from '@openai/agents';
|
|
1
|
+
import { Agent, AgentInputItem, RunState, NonStreamRunOptions, RunResult, StreamRunOptions, StreamedRunResult, Trace, Span } from '@openai/agents';
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
4
|
* BAML execution utilities for the Bitfab TypeScript SDK.
|
|
@@ -52,9 +52,14 @@ interface ActiveSpanContext$2 {
|
|
|
52
52
|
* Captures LLM turns, tool invocations, and subagent execution as
|
|
53
53
|
* Bitfab spans with proper parent-child hierarchy.
|
|
54
54
|
*
|
|
55
|
+
* The TypeScript Claude Agent SDK exposes a single `query()` entry point (there
|
|
56
|
+
* is no `ClaudeSDKClient` class — that exists only in the Python SDK). Wrap the
|
|
57
|
+
* `query()` async iterator with `wrapQuery`; tool and subagent spans come from
|
|
58
|
+
* the hooks injected by `instrumentOptions`.
|
|
59
|
+
*
|
|
55
60
|
* ```typescript
|
|
56
61
|
* import { Bitfab } from "@bitfab/sdk";
|
|
57
|
-
* import {
|
|
62
|
+
* import { query } from "@anthropic-ai/claude-agent-sdk";
|
|
58
63
|
*
|
|
59
64
|
* const bitfab = new Bitfab({ apiKey: "..." });
|
|
60
65
|
* const handler = bitfab.getClaudeAgentHandler("my-agent");
|
|
@@ -63,11 +68,9 @@ interface ActiveSpanContext$2 {
|
|
|
63
68
|
* model: "claude-sonnet-4-5-...",
|
|
64
69
|
* });
|
|
65
70
|
*
|
|
66
|
-
* const
|
|
67
|
-
*
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
* for await (const message of handler.wrapResponse(client.receiveResponse())) {
|
|
71
|
+
* for await (const message of handler.wrapQuery(
|
|
72
|
+
* query({ prompt: "Do something", options })
|
|
73
|
+
* )) {
|
|
71
74
|
* // process messages normally
|
|
72
75
|
* }
|
|
73
76
|
* ```
|
|
@@ -91,6 +94,9 @@ declare class BitfabClaudeAgentHandler {
|
|
|
91
94
|
private currentLlmStartedAt;
|
|
92
95
|
private currentLlmHistorySnapshot;
|
|
93
96
|
private activeSubagentSpans;
|
|
97
|
+
private hasRootInput;
|
|
98
|
+
private rootInput;
|
|
99
|
+
private rootOutput;
|
|
94
100
|
constructor(config: {
|
|
95
101
|
apiKey?: string;
|
|
96
102
|
traceFunctionKey: string;
|
|
@@ -100,6 +106,8 @@ declare class BitfabClaudeAgentHandler {
|
|
|
100
106
|
});
|
|
101
107
|
private ensureTrace;
|
|
102
108
|
private getParentId;
|
|
109
|
+
private maybeStartRootSpan;
|
|
110
|
+
private completeRootSpan;
|
|
103
111
|
private startSpan;
|
|
104
112
|
private completeSpan;
|
|
105
113
|
private sendSpan;
|
|
@@ -122,19 +130,38 @@ declare class BitfabClaudeAgentHandler {
|
|
|
122
130
|
*/
|
|
123
131
|
instrumentOptions<T extends Record<string, unknown>>(options: T): T;
|
|
124
132
|
/**
|
|
125
|
-
* Wrap
|
|
133
|
+
* Wrap any Claude Agent SDK message stream to capture LLM turns.
|
|
134
|
+
*
|
|
135
|
+
* Yields every message unchanged while capturing assistant message
|
|
136
|
+
* content as LLM turn spans. Kept for naming symmetry with the Python
|
|
137
|
+
* SDK's `wrapResponse` (which wraps `ClaudeSDKClient.receiveResponse()`);
|
|
138
|
+
* in TypeScript, prefer `wrapQuery` around `query()`.
|
|
126
139
|
*
|
|
127
|
-
*
|
|
128
|
-
*
|
|
140
|
+
* Pass `{ input }` (the prompt) to record a replayable root span — see
|
|
141
|
+
* `wrapQuery`.
|
|
129
142
|
*/
|
|
130
|
-
wrapResponse(stream: AsyncIterable<unknown
|
|
143
|
+
wrapResponse(stream: AsyncIterable<unknown>, opts?: {
|
|
144
|
+
input?: unknown;
|
|
145
|
+
}): AsyncIterable<unknown>;
|
|
131
146
|
/**
|
|
132
147
|
* Wrap a `query()` async iterator to capture LLM turns.
|
|
133
148
|
*
|
|
134
|
-
*
|
|
135
|
-
*
|
|
149
|
+
* Tool and subagent spans are captured separately via the hooks injected
|
|
150
|
+
* by `instrumentOptions` into the `options` passed to `query()`.
|
|
151
|
+
*
|
|
152
|
+
* Pass `{ input }` — the prompt (or the serializable args that produced it)
|
|
153
|
+
* — to make a handler-only run replayable: the handler records a root `agent`
|
|
154
|
+
* span with that input, so `replay(key, fn)` can re-feed it. Omit it only
|
|
155
|
+
* when an enclosing `withSpan` already supplies the replayable root.
|
|
156
|
+
*
|
|
157
|
+
* ```typescript
|
|
158
|
+
* handler.wrapQuery(query({ prompt, options }), { input: prompt })
|
|
159
|
+
* ```
|
|
136
160
|
*/
|
|
137
|
-
wrapQuery(stream: AsyncIterable<unknown
|
|
161
|
+
wrapQuery(stream: AsyncIterable<unknown>, opts?: {
|
|
162
|
+
input?: unknown;
|
|
163
|
+
}): AsyncIterable<unknown>;
|
|
164
|
+
private setRootInput;
|
|
138
165
|
private processStream;
|
|
139
166
|
private processMessage;
|
|
140
167
|
private handleAssistantMessage;
|
|
@@ -286,6 +313,76 @@ declare class BitfabLangGraphCallbackHandler {
|
|
|
286
313
|
handleRetrieverError(error: unknown, runId: string): Promise<void>;
|
|
287
314
|
}
|
|
288
315
|
|
|
316
|
+
/**
|
|
317
|
+
* OpenAI Agents SDK handler for Bitfab tracing.
|
|
318
|
+
*
|
|
319
|
+
* The OpenAI Agents SDK is instrumented in two layers:
|
|
320
|
+
*
|
|
321
|
+
* 1. A process-wide `TracingProcessor` (see `getOpenAiTracingProcessor` /
|
|
322
|
+
* `BitfabOpenAITracingProcessor`) registered once with `addTraceProcessor`.
|
|
323
|
+
* It captures everything *inside* a run — LLM calls, tool calls, handoffs —
|
|
324
|
+
* as Bitfab spans.
|
|
325
|
+
* 2. This handler's `wrapRun`, which owns the *root*. The processor never sees
|
|
326
|
+
* the caller's input (the SDK's trace events don't carry it), so a
|
|
327
|
+
* processor-only run records a root span with an empty input and is not
|
|
328
|
+
* replayable. `wrapRun` is a thin drop-in for `run()` that opens a
|
|
329
|
+
* `withSpan` root carrying the input and final output, so the run is
|
|
330
|
+
* replayable with no hand-written `withSpan`. The processor's spans nest
|
|
331
|
+
* underneath it automatically (it remaps onto the active span context).
|
|
332
|
+
*
|
|
333
|
+
* Use both together: register the processor once at startup, then call
|
|
334
|
+
* `handler.wrapRun(agent, input)` instead of `run(agent, input)`.
|
|
335
|
+
*/
|
|
336
|
+
|
|
337
|
+
type RootSpanOptions = {
|
|
338
|
+
type: "agent";
|
|
339
|
+
finalize: (result: unknown) => unknown | Promise<unknown>;
|
|
340
|
+
};
|
|
341
|
+
type WithSpanFn = <TArgs extends unknown[], TReturn>(traceFunctionKey: string, options: RootSpanOptions, fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
|
|
342
|
+
type RunInput<TContext, TAgent extends Agent<any, any>> = string | AgentInputItem[] | RunState<TContext, TAgent>;
|
|
343
|
+
/**
|
|
344
|
+
* OpenAI Agents SDK handler that records a replayable root span around a run.
|
|
345
|
+
*
|
|
346
|
+
* ```typescript
|
|
347
|
+
* import { Bitfab } from "@bitfab/sdk";
|
|
348
|
+
* import { addTraceProcessor, Agent, run } from "@openai/agents";
|
|
349
|
+
*
|
|
350
|
+
* const bitfab = new Bitfab({ apiKey: "..." });
|
|
351
|
+
* addTraceProcessor(bitfab.getOpenAiTracingProcessor()); // captures internals
|
|
352
|
+
*
|
|
353
|
+
* const agent = new Agent({ name: "Researcher", instructions: "..." });
|
|
354
|
+
* const handler = bitfab.getOpenAiAgentHandler("research-topic");
|
|
355
|
+
*
|
|
356
|
+
* // Swap run(agent, input) -> handler.wrapRun(agent, input)
|
|
357
|
+
* const result = await handler.wrapRun(agent, "Find X");
|
|
358
|
+
* return result.finalOutput;
|
|
359
|
+
* ```
|
|
360
|
+
*/
|
|
361
|
+
declare class BitfabOpenAIAgentHandler {
|
|
362
|
+
private readonly traceFunctionKey;
|
|
363
|
+
private readonly withSpanFn;
|
|
364
|
+
constructor(config: {
|
|
365
|
+
traceFunctionKey: string;
|
|
366
|
+
withSpan: WithSpanFn;
|
|
367
|
+
});
|
|
368
|
+
/**
|
|
369
|
+
* Drop-in replacement for the OpenAI Agents SDK's `run()` that records a
|
|
370
|
+
* replayable root `agent` span.
|
|
371
|
+
*
|
|
372
|
+
* The `input` is captured as the root span's input (as a single positional
|
|
373
|
+
* argument, so `replay(key, fn)` re-feeds it), and the run's `finalOutput`
|
|
374
|
+
* is recorded as the root output. For streaming runs (`{ stream: true }`),
|
|
375
|
+
* the result is handed back immediately and the final output is recorded
|
|
376
|
+
* once the stream completes — first-byte latency is untouched.
|
|
377
|
+
*
|
|
378
|
+
* The process-wide tracing processor (`getOpenAiTracingProcessor`) must still
|
|
379
|
+
* be registered: it captures the LLM/tool/handoff spans that nest beneath
|
|
380
|
+
* this root.
|
|
381
|
+
*/
|
|
382
|
+
wrapRun<TAgent extends Agent<any, any>, TContext = undefined>(agent: TAgent, input: RunInput<TContext, TAgent>, options?: NonStreamRunOptions<TContext>): Promise<RunResult<TContext, TAgent>>;
|
|
383
|
+
wrapRun<TAgent extends Agent<any, any>, TContext = undefined>(agent: TAgent, input: RunInput<TContext, TAgent>, options: StreamRunOptions<TContext>): Promise<StreamedRunResult<TContext, TAgent>>;
|
|
384
|
+
}
|
|
385
|
+
|
|
289
386
|
/**
|
|
290
387
|
* Per-trace environment exposed to customer code during replay.
|
|
291
388
|
*
|
|
@@ -836,6 +933,29 @@ declare class Bitfab {
|
|
|
836
933
|
* @returns A BitfabOpenAITracingProcessor instance configured for this client
|
|
837
934
|
*/
|
|
838
935
|
getOpenAiTracingProcessor(): BitfabOpenAITracingProcessor;
|
|
936
|
+
/**
|
|
937
|
+
* Get an OpenAI Agents SDK handler that records a replayable root span.
|
|
938
|
+
*
|
|
939
|
+
* The processor from {@link getOpenAiTracingProcessor} captures everything
|
|
940
|
+
* inside a run (LLM calls, tools, handoffs) but never sees the caller's
|
|
941
|
+
* input, so a processor-only run records an empty-input root and is not
|
|
942
|
+
* replayable. This handler's `wrapRun` is a drop-in for `run()` that opens a
|
|
943
|
+
* `withSpan` root carrying the input and final output; the processor's spans
|
|
944
|
+
* nest beneath it. Register the processor once at startup, then call
|
|
945
|
+
* `handler.wrapRun(agent, input)` in place of `run(agent, input)`.
|
|
946
|
+
*
|
|
947
|
+
* ```typescript
|
|
948
|
+
* import { addTraceProcessor, Agent, run } from "@openai/agents";
|
|
949
|
+
*
|
|
950
|
+
* addTraceProcessor(client.getOpenAiTracingProcessor());
|
|
951
|
+
* const handler = client.getOpenAiAgentHandler("research-topic");
|
|
952
|
+
* const result = await handler.wrapRun(agent, "Find X");
|
|
953
|
+
* ```
|
|
954
|
+
*
|
|
955
|
+
* @param traceFunctionKey - Groups traces under this key in Bitfab
|
|
956
|
+
* @returns A BitfabOpenAIAgentHandler configured for this client
|
|
957
|
+
*/
|
|
958
|
+
getOpenAiAgentHandler(traceFunctionKey: string): BitfabOpenAIAgentHandler;
|
|
839
959
|
/**
|
|
840
960
|
* Get a LangGraph/LangChain callback handler for tracing.
|
|
841
961
|
*
|
|
@@ -877,14 +997,15 @@ declare class Bitfab {
|
|
|
877
997
|
* execution as Bitfab spans with proper parent-child hierarchy.
|
|
878
998
|
*
|
|
879
999
|
* ```typescript
|
|
1000
|
+
* import { query } from "@anthropic-ai/claude-agent-sdk";
|
|
1001
|
+
*
|
|
880
1002
|
* const handler = client.getClaudeAgentHandler("my-agent");
|
|
881
1003
|
* const options = handler.instrumentOptions({
|
|
882
1004
|
* model: "claude-sonnet-4-5-...",
|
|
883
1005
|
* });
|
|
884
|
-
* const
|
|
885
|
-
*
|
|
886
|
-
*
|
|
887
|
-
* for await (const msg of handler.wrapResponse(sdkClient.receiveResponse())) {
|
|
1006
|
+
* for await (const msg of handler.wrapQuery(
|
|
1007
|
+
* query({ prompt: "Do something", options })
|
|
1008
|
+
* )) {
|
|
888
1009
|
* // process messages
|
|
889
1010
|
* }
|
|
890
1011
|
* ```
|
|
@@ -1089,7 +1210,7 @@ declare class BitfabFunction {
|
|
|
1089
1210
|
/**
|
|
1090
1211
|
* SDK version from package.json (injected at build time)
|
|
1091
1212
|
*/
|
|
1092
|
-
declare const __version__ = "0.
|
|
1213
|
+
declare const __version__ = "0.22.0";
|
|
1093
1214
|
|
|
1094
1215
|
/**
|
|
1095
1216
|
* Constants for the Bitfab SDK.
|
|
@@ -1157,4 +1278,4 @@ declare const finalizers: {
|
|
|
1157
1278
|
readableStream: typeof readableStream;
|
|
1158
1279
|
};
|
|
1159
1280
|
|
|
1160
|
-
export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabOpenAITracingProcessor, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace };
|
|
1281
|
+
export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { Trace, Span } from '@openai/agents';
|
|
1
|
+
import { Agent, AgentInputItem, RunState, NonStreamRunOptions, RunResult, StreamRunOptions, StreamedRunResult, Trace, Span } from '@openai/agents';
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
4
|
* BAML execution utilities for the Bitfab TypeScript SDK.
|
|
@@ -52,9 +52,14 @@ interface ActiveSpanContext$2 {
|
|
|
52
52
|
* Captures LLM turns, tool invocations, and subagent execution as
|
|
53
53
|
* Bitfab spans with proper parent-child hierarchy.
|
|
54
54
|
*
|
|
55
|
+
* The TypeScript Claude Agent SDK exposes a single `query()` entry point (there
|
|
56
|
+
* is no `ClaudeSDKClient` class — that exists only in the Python SDK). Wrap the
|
|
57
|
+
* `query()` async iterator with `wrapQuery`; tool and subagent spans come from
|
|
58
|
+
* the hooks injected by `instrumentOptions`.
|
|
59
|
+
*
|
|
55
60
|
* ```typescript
|
|
56
61
|
* import { Bitfab } from "@bitfab/sdk";
|
|
57
|
-
* import {
|
|
62
|
+
* import { query } from "@anthropic-ai/claude-agent-sdk";
|
|
58
63
|
*
|
|
59
64
|
* const bitfab = new Bitfab({ apiKey: "..." });
|
|
60
65
|
* const handler = bitfab.getClaudeAgentHandler("my-agent");
|
|
@@ -63,11 +68,9 @@ interface ActiveSpanContext$2 {
|
|
|
63
68
|
* model: "claude-sonnet-4-5-...",
|
|
64
69
|
* });
|
|
65
70
|
*
|
|
66
|
-
* const
|
|
67
|
-
*
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
* for await (const message of handler.wrapResponse(client.receiveResponse())) {
|
|
71
|
+
* for await (const message of handler.wrapQuery(
|
|
72
|
+
* query({ prompt: "Do something", options })
|
|
73
|
+
* )) {
|
|
71
74
|
* // process messages normally
|
|
72
75
|
* }
|
|
73
76
|
* ```
|
|
@@ -91,6 +94,9 @@ declare class BitfabClaudeAgentHandler {
|
|
|
91
94
|
private currentLlmStartedAt;
|
|
92
95
|
private currentLlmHistorySnapshot;
|
|
93
96
|
private activeSubagentSpans;
|
|
97
|
+
private hasRootInput;
|
|
98
|
+
private rootInput;
|
|
99
|
+
private rootOutput;
|
|
94
100
|
constructor(config: {
|
|
95
101
|
apiKey?: string;
|
|
96
102
|
traceFunctionKey: string;
|
|
@@ -100,6 +106,8 @@ declare class BitfabClaudeAgentHandler {
|
|
|
100
106
|
});
|
|
101
107
|
private ensureTrace;
|
|
102
108
|
private getParentId;
|
|
109
|
+
private maybeStartRootSpan;
|
|
110
|
+
private completeRootSpan;
|
|
103
111
|
private startSpan;
|
|
104
112
|
private completeSpan;
|
|
105
113
|
private sendSpan;
|
|
@@ -122,19 +130,38 @@ declare class BitfabClaudeAgentHandler {
|
|
|
122
130
|
*/
|
|
123
131
|
instrumentOptions<T extends Record<string, unknown>>(options: T): T;
|
|
124
132
|
/**
|
|
125
|
-
* Wrap
|
|
133
|
+
* Wrap any Claude Agent SDK message stream to capture LLM turns.
|
|
134
|
+
*
|
|
135
|
+
* Yields every message unchanged while capturing assistant message
|
|
136
|
+
* content as LLM turn spans. Kept for naming symmetry with the Python
|
|
137
|
+
* SDK's `wrapResponse` (which wraps `ClaudeSDKClient.receiveResponse()`);
|
|
138
|
+
* in TypeScript, prefer `wrapQuery` around `query()`.
|
|
126
139
|
*
|
|
127
|
-
*
|
|
128
|
-
*
|
|
140
|
+
* Pass `{ input }` (the prompt) to record a replayable root span — see
|
|
141
|
+
* `wrapQuery`.
|
|
129
142
|
*/
|
|
130
|
-
wrapResponse(stream: AsyncIterable<unknown
|
|
143
|
+
wrapResponse(stream: AsyncIterable<unknown>, opts?: {
|
|
144
|
+
input?: unknown;
|
|
145
|
+
}): AsyncIterable<unknown>;
|
|
131
146
|
/**
|
|
132
147
|
* Wrap a `query()` async iterator to capture LLM turns.
|
|
133
148
|
*
|
|
134
|
-
*
|
|
135
|
-
*
|
|
149
|
+
* Tool and subagent spans are captured separately via the hooks injected
|
|
150
|
+
* by `instrumentOptions` into the `options` passed to `query()`.
|
|
151
|
+
*
|
|
152
|
+
* Pass `{ input }` — the prompt (or the serializable args that produced it)
|
|
153
|
+
* — to make a handler-only run replayable: the handler records a root `agent`
|
|
154
|
+
* span with that input, so `replay(key, fn)` can re-feed it. Omit it only
|
|
155
|
+
* when an enclosing `withSpan` already supplies the replayable root.
|
|
156
|
+
*
|
|
157
|
+
* ```typescript
|
|
158
|
+
* handler.wrapQuery(query({ prompt, options }), { input: prompt })
|
|
159
|
+
* ```
|
|
136
160
|
*/
|
|
137
|
-
wrapQuery(stream: AsyncIterable<unknown
|
|
161
|
+
wrapQuery(stream: AsyncIterable<unknown>, opts?: {
|
|
162
|
+
input?: unknown;
|
|
163
|
+
}): AsyncIterable<unknown>;
|
|
164
|
+
private setRootInput;
|
|
138
165
|
private processStream;
|
|
139
166
|
private processMessage;
|
|
140
167
|
private handleAssistantMessage;
|
|
@@ -286,6 +313,76 @@ declare class BitfabLangGraphCallbackHandler {
|
|
|
286
313
|
handleRetrieverError(error: unknown, runId: string): Promise<void>;
|
|
287
314
|
}
|
|
288
315
|
|
|
316
|
+
/**
|
|
317
|
+
* OpenAI Agents SDK handler for Bitfab tracing.
|
|
318
|
+
*
|
|
319
|
+
* The OpenAI Agents SDK is instrumented in two layers:
|
|
320
|
+
*
|
|
321
|
+
* 1. A process-wide `TracingProcessor` (see `getOpenAiTracingProcessor` /
|
|
322
|
+
* `BitfabOpenAITracingProcessor`) registered once with `addTraceProcessor`.
|
|
323
|
+
* It captures everything *inside* a run — LLM calls, tool calls, handoffs —
|
|
324
|
+
* as Bitfab spans.
|
|
325
|
+
* 2. This handler's `wrapRun`, which owns the *root*. The processor never sees
|
|
326
|
+
* the caller's input (the SDK's trace events don't carry it), so a
|
|
327
|
+
* processor-only run records a root span with an empty input and is not
|
|
328
|
+
* replayable. `wrapRun` is a thin drop-in for `run()` that opens a
|
|
329
|
+
* `withSpan` root carrying the input and final output, so the run is
|
|
330
|
+
* replayable with no hand-written `withSpan`. The processor's spans nest
|
|
331
|
+
* underneath it automatically (it remaps onto the active span context).
|
|
332
|
+
*
|
|
333
|
+
* Use both together: register the processor once at startup, then call
|
|
334
|
+
* `handler.wrapRun(agent, input)` instead of `run(agent, input)`.
|
|
335
|
+
*/
|
|
336
|
+
|
|
337
|
+
type RootSpanOptions = {
|
|
338
|
+
type: "agent";
|
|
339
|
+
finalize: (result: unknown) => unknown | Promise<unknown>;
|
|
340
|
+
};
|
|
341
|
+
type WithSpanFn = <TArgs extends unknown[], TReturn>(traceFunctionKey: string, options: RootSpanOptions, fn: (...args: TArgs) => TReturn) => (...args: TArgs) => TReturn;
|
|
342
|
+
type RunInput<TContext, TAgent extends Agent<any, any>> = string | AgentInputItem[] | RunState<TContext, TAgent>;
|
|
343
|
+
/**
|
|
344
|
+
* OpenAI Agents SDK handler that records a replayable root span around a run.
|
|
345
|
+
*
|
|
346
|
+
* ```typescript
|
|
347
|
+
* import { Bitfab } from "@bitfab/sdk";
|
|
348
|
+
* import { addTraceProcessor, Agent, run } from "@openai/agents";
|
|
349
|
+
*
|
|
350
|
+
* const bitfab = new Bitfab({ apiKey: "..." });
|
|
351
|
+
* addTraceProcessor(bitfab.getOpenAiTracingProcessor()); // captures internals
|
|
352
|
+
*
|
|
353
|
+
* const agent = new Agent({ name: "Researcher", instructions: "..." });
|
|
354
|
+
* const handler = bitfab.getOpenAiAgentHandler("research-topic");
|
|
355
|
+
*
|
|
356
|
+
* // Swap run(agent, input) -> handler.wrapRun(agent, input)
|
|
357
|
+
* const result = await handler.wrapRun(agent, "Find X");
|
|
358
|
+
* return result.finalOutput;
|
|
359
|
+
* ```
|
|
360
|
+
*/
|
|
361
|
+
declare class BitfabOpenAIAgentHandler {
|
|
362
|
+
private readonly traceFunctionKey;
|
|
363
|
+
private readonly withSpanFn;
|
|
364
|
+
constructor(config: {
|
|
365
|
+
traceFunctionKey: string;
|
|
366
|
+
withSpan: WithSpanFn;
|
|
367
|
+
});
|
|
368
|
+
/**
|
|
369
|
+
* Drop-in replacement for the OpenAI Agents SDK's `run()` that records a
|
|
370
|
+
* replayable root `agent` span.
|
|
371
|
+
*
|
|
372
|
+
* The `input` is captured as the root span's input (as a single positional
|
|
373
|
+
* argument, so `replay(key, fn)` re-feeds it), and the run's `finalOutput`
|
|
374
|
+
* is recorded as the root output. For streaming runs (`{ stream: true }`),
|
|
375
|
+
* the result is handed back immediately and the final output is recorded
|
|
376
|
+
* once the stream completes — first-byte latency is untouched.
|
|
377
|
+
*
|
|
378
|
+
* The process-wide tracing processor (`getOpenAiTracingProcessor`) must still
|
|
379
|
+
* be registered: it captures the LLM/tool/handoff spans that nest beneath
|
|
380
|
+
* this root.
|
|
381
|
+
*/
|
|
382
|
+
wrapRun<TAgent extends Agent<any, any>, TContext = undefined>(agent: TAgent, input: RunInput<TContext, TAgent>, options?: NonStreamRunOptions<TContext>): Promise<RunResult<TContext, TAgent>>;
|
|
383
|
+
wrapRun<TAgent extends Agent<any, any>, TContext = undefined>(agent: TAgent, input: RunInput<TContext, TAgent>, options: StreamRunOptions<TContext>): Promise<StreamedRunResult<TContext, TAgent>>;
|
|
384
|
+
}
|
|
385
|
+
|
|
289
386
|
/**
|
|
290
387
|
* Per-trace environment exposed to customer code during replay.
|
|
291
388
|
*
|
|
@@ -836,6 +933,29 @@ declare class Bitfab {
|
|
|
836
933
|
* @returns A BitfabOpenAITracingProcessor instance configured for this client
|
|
837
934
|
*/
|
|
838
935
|
getOpenAiTracingProcessor(): BitfabOpenAITracingProcessor;
|
|
936
|
+
/**
|
|
937
|
+
* Get an OpenAI Agents SDK handler that records a replayable root span.
|
|
938
|
+
*
|
|
939
|
+
* The processor from {@link getOpenAiTracingProcessor} captures everything
|
|
940
|
+
* inside a run (LLM calls, tools, handoffs) but never sees the caller's
|
|
941
|
+
* input, so a processor-only run records an empty-input root and is not
|
|
942
|
+
* replayable. This handler's `wrapRun` is a drop-in for `run()` that opens a
|
|
943
|
+
* `withSpan` root carrying the input and final output; the processor's spans
|
|
944
|
+
* nest beneath it. Register the processor once at startup, then call
|
|
945
|
+
* `handler.wrapRun(agent, input)` in place of `run(agent, input)`.
|
|
946
|
+
*
|
|
947
|
+
* ```typescript
|
|
948
|
+
* import { addTraceProcessor, Agent, run } from "@openai/agents";
|
|
949
|
+
*
|
|
950
|
+
* addTraceProcessor(client.getOpenAiTracingProcessor());
|
|
951
|
+
* const handler = client.getOpenAiAgentHandler("research-topic");
|
|
952
|
+
* const result = await handler.wrapRun(agent, "Find X");
|
|
953
|
+
* ```
|
|
954
|
+
*
|
|
955
|
+
* @param traceFunctionKey - Groups traces under this key in Bitfab
|
|
956
|
+
* @returns A BitfabOpenAIAgentHandler configured for this client
|
|
957
|
+
*/
|
|
958
|
+
getOpenAiAgentHandler(traceFunctionKey: string): BitfabOpenAIAgentHandler;
|
|
839
959
|
/**
|
|
840
960
|
* Get a LangGraph/LangChain callback handler for tracing.
|
|
841
961
|
*
|
|
@@ -877,14 +997,15 @@ declare class Bitfab {
|
|
|
877
997
|
* execution as Bitfab spans with proper parent-child hierarchy.
|
|
878
998
|
*
|
|
879
999
|
* ```typescript
|
|
1000
|
+
* import { query } from "@anthropic-ai/claude-agent-sdk";
|
|
1001
|
+
*
|
|
880
1002
|
* const handler = client.getClaudeAgentHandler("my-agent");
|
|
881
1003
|
* const options = handler.instrumentOptions({
|
|
882
1004
|
* model: "claude-sonnet-4-5-...",
|
|
883
1005
|
* });
|
|
884
|
-
* const
|
|
885
|
-
*
|
|
886
|
-
*
|
|
887
|
-
* for await (const msg of handler.wrapResponse(sdkClient.receiveResponse())) {
|
|
1006
|
+
* for await (const msg of handler.wrapQuery(
|
|
1007
|
+
* query({ prompt: "Do something", options })
|
|
1008
|
+
* )) {
|
|
888
1009
|
* // process messages
|
|
889
1010
|
* }
|
|
890
1011
|
* ```
|
|
@@ -1089,7 +1210,7 @@ declare class BitfabFunction {
|
|
|
1089
1210
|
/**
|
|
1090
1211
|
* SDK version from package.json (injected at build time)
|
|
1091
1212
|
*/
|
|
1092
|
-
declare const __version__ = "0.
|
|
1213
|
+
declare const __version__ = "0.22.0";
|
|
1093
1214
|
|
|
1094
1215
|
/**
|
|
1095
1216
|
* Constants for the Bitfab SDK.
|
|
@@ -1157,4 +1278,4 @@ declare const finalizers: {
|
|
|
1157
1278
|
readableStream: typeof readableStream;
|
|
1158
1279
|
};
|
|
1159
1280
|
|
|
1160
|
-
export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabOpenAITracingProcessor, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace };
|
|
1281
|
+
export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace };
|
package/dist/index.js
CHANGED
|
@@ -12,6 +12,7 @@ import {
|
|
|
12
12
|
BitfabClaudeAgentHandler,
|
|
13
13
|
BitfabFunction,
|
|
14
14
|
BitfabLangGraphCallbackHandler,
|
|
15
|
+
BitfabOpenAIAgentHandler,
|
|
15
16
|
BitfabOpenAITracingProcessor,
|
|
16
17
|
DEFAULT_SERVICE_URL,
|
|
17
18
|
ReplayEnvironment,
|
|
@@ -21,7 +22,7 @@ import {
|
|
|
21
22
|
flushTraces,
|
|
22
23
|
getCurrentSpan,
|
|
23
24
|
getCurrentTrace
|
|
24
|
-
} from "./chunk-
|
|
25
|
+
} from "./chunk-4SLFC266.js";
|
|
25
26
|
import {
|
|
26
27
|
BitfabError
|
|
27
28
|
} from "./chunk-EQI6ZJC3.js";
|
|
@@ -32,6 +33,7 @@ export {
|
|
|
32
33
|
BitfabFunction,
|
|
33
34
|
BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler,
|
|
34
35
|
BitfabLangGraphCallbackHandler,
|
|
36
|
+
BitfabOpenAIAgentHandler,
|
|
35
37
|
BitfabOpenAITracingProcessor,
|
|
36
38
|
DEFAULT_SERVICE_URL,
|
|
37
39
|
ReplayEnvironment,
|