@openai/agents-core/dist/runner/tracing.d.ts

The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows.

import { Agent } from '../agent';
import { Handoff } from '../handoff';
import { ModelTracing } from '../model';
import { Tool } from '../tool';
import { createAgentSpan } from '../tracing';
import { Span, type TaskSpanData, type TurnSpanData } from '../tracing/spans';
import { Trace } from '../tracing/traces';
import type { Usage } from '../usage';
export type TraceOverrideConfig = {
    traceId?: string;
    workflowName?: string;
    groupId?: string;
    traceMetadata?: Record<string, any>;
    tracingApiKey?: string;
};
type EnsureAgentSpanParams<TContext> = {
    agent: Agent<TContext, any>;
    handoffs: Handoff<any, any>[];
    tools: Tool<TContext>[];
    currentSpan?: ReturnType<typeof createAgentSpan>;
    parent?: Span<any> | Trace;
};
type UsageSnapshot = {
    requests: number;
    inputTokens: number;
    outputTokens: number;
    totalTokens: number;
    cachedInputTokens: number;
    cacheWriteInputTokens: number;
};
export type RunnerSpanLifecycle<TSpanData extends TaskSpanData | TurnSpanData> = {
    span: Span<TSpanData>;
    ownedUsage: UsageSnapshot;
};
export declare function recordRunnerSpanUsage(lifecycle: RunnerSpanLifecycle<TaskSpanData | TurnSpanData> | undefined, increment: Usage): void;
export declare function startTaskSpan(name: string, parent?: Span<any> | Trace): RunnerSpanLifecycle<TaskSpanData>;
export declare function ensureActiveAgentSpanForInterruptedResume<TContext>(options: {
    agent: Agent<TContext, any>;
    restoredAgentSpan?: ReturnType<typeof createAgentSpan>;
    parent?: Span<any> | Trace;
}): ReturnType<typeof createAgentSpan>;
export declare function startRunnerInvocationSpans<TContext>(options: {
    name: string;
    agent: Agent<TContext, any>;
    restoredAgentSpan?: ReturnType<typeof createAgentSpan>;
    resumeInterruptedTurn: boolean;
    parent?: Span<any> | Trace;
}): {
    taskSpan: RunnerSpanLifecycle<TaskSpanData>;
    agentSpan?: ReturnType<typeof createAgentSpan>;
};
export declare function startTurnSpan(turn: number, agentName: string, parent?: Span<any> | Trace): RunnerSpanLifecycle<TurnSpanData>;
export declare function ensureTurnSpan(current: RunnerSpanLifecycle<TurnSpanData> | undefined, turn: number, agentName: string, parent?: Span<any> | Trace): RunnerSpanLifecycle<TurnSpanData>;
export declare function finishRunnerSpan(lifecycle: RunnerSpanLifecycle<TaskSpanData | TurnSpanData> | undefined): void;
export declare function setRunnerSpanError(lifecycle: RunnerSpanLifecycle<TaskSpanData | TurnSpanData> | undefined, error: unknown, traceIncludeSensitiveData: boolean): void;
export declare function getRunnerSpanErrorDetails(error: unknown, traceIncludeSensitiveData: boolean): string;
/**
 * Normalizes tracing configuration into the format expected by model providers.
 * Returns `false` to disable tracing, `true` to include full payload data, or
 * `'enabled_without_data'` to omit sensitive content while still emitting spans.
 */
export declare function getTracing(tracingDisabled: boolean, traceIncludeSensitiveData: boolean): ModelTracing;
export declare function applyTraceOverrides(trace: Trace, currentSpan: Span<any> | undefined, overrides: TraceOverrideConfig): {
    trace: Trace;
    currentSpan: Span<any> | undefined;
};
/**
 * Ensures an agent span exists and updates tool metadata if already present.
 * Returns the span so callers can pass it through run state.
 */
export declare function ensureAgentSpan<TContext>(params: EnsureAgentSpanParams<TContext>): Span<import("../tracing").AgentSpanData>;
export {};