@posthog/ai/dist/openai-agents/index.d.ts

PostHog Node.js AI integrations

import { PostHog } from 'posthog-node';
import { Trace, TracingProcessor, Span, SpanData } from '@openai/agents-core';

type DistinctIdResolver = string | ((trace: Trace) => string | null | undefined);
interface PostHogTracingProcessorOptions {
    client: PostHog;
    distinctId?: DistinctIdResolver;
    privacyMode?: boolean;
    groups?: Record<string, any>;
    properties?: Record<string, any>;
}
/**
 * A tracing processor that sends OpenAI Agents SDK traces to PostHog.
 *
 * Implements the TracingProcessor interface from the OpenAI Agents SDK
 * and maps agent traces, spans, and generations to PostHog's LLM analytics events.
 *
 * @example
 * ```typescript
 * import { PostHogTracingProcessor } from '@posthog/ai/openai-agents'
 * import { addTraceProcessor } from '@openai/agents'
 *
 * const processor = new PostHogTracingProcessor({
 *   client: posthog,
 *   distinctId: 'user@example.com',
 * })
 * addTraceProcessor(processor)
 * ```
 */
declare class PostHogTracingProcessor implements TracingProcessor {
    private _client;
    private _distinctId;
    private _privacyMode;
    private _groups;
    private _properties;
    private _spanStartTimes;
    private _traceMetadata;
    private _maxTrackedEntries;
    constructor(options: PostHogTracingProcessorOptions);
    private _getDistinctId;
    private _withPrivacyMode;
    private _prepareCapturedValue;
    private _evictStaleEntries;
    private _captureEvent;
    private _baseProperties;
    private _getErrorProperties;
    onTraceStart(trace: Trace): Promise<void>;
    onTraceEnd(trace: Trace): Promise<void>;
    onSpanStart(span: Span<SpanData>): Promise<void>;
    onSpanEnd(span: Span<SpanData>): Promise<void>;
    shutdown(): Promise<void>;
    forceFlush(): Promise<void>;
    private _handleGenerationSpan;
    private _handleResponseSpan;
    private _handleFunctionSpan;
    private _handleAgentSpan;
    private _handleHandoffSpan;
    private _handleGuardrailSpan;
    private _handleCustomSpan;
    private _handleAudioSpan;
    private _handleMcpSpan;
    private _handleGenericSpan;
}

type InstrumentOptions = PostHogTracingProcessorOptions;
/**
 * One-liner to instrument OpenAI Agents SDK with PostHog tracing.
 *
 * This registers a PostHogTracingProcessor with the OpenAI Agents SDK,
 * automatically capturing traces, spans, and LLM generations.
 *
 * @param options - Configuration options
 * @returns The registered processor instance
 *
 * @example
 * ```typescript
 * import { instrument } from '@posthog/ai/openai-agents'
 * import PostHog from 'posthog-node'
 *
 * const phClient = new PostHog('<API_KEY>')
 *
 * // Simple setup — await before running agents
 * await instrument({ client: phClient, distinctId: 'user@example.com' })
 *
 * // With dynamic distinct ID
 * await instrument({
 *   client: phClient,
 *   distinctId: (trace) => trace.metadata?.userId,
 *   privacyMode: true,
 *   properties: { environment: 'production' },
 * })
 *
 * // Now run agents as normal - traces automatically sent to PostHog
 * import { Agent, run } from '@openai/agents'
 * const agent = new Agent({ name: 'Assistant', instructions: 'You are helpful.' })
 * const result = await run(agent, 'Hello!')
 * ```
 */
declare function instrument(options: InstrumentOptions): Promise<PostHogTracingProcessor>;

export { type DistinctIdResolver, type InstrumentOptions, PostHogTracingProcessor, type PostHogTracingProcessorOptions, instrument };