/**
 * @license
 * Copyright 2025 Google LLC
 * SPDX-License-Identifier: Apache-2.0
 */
/**
 * NOTE:
 *
 *    We expect that the underlying GenAI SDK will provide a certain
 *    level of tracing and logging telemetry aligned with Open Telemetry
 *    Semantic Conventions (such as logging prompts, responses,
 *    request properties, etc.) and so the information that is recorded by the
 *    Agent Development Kit should be focused on the higher-level
 *    constructs of the framework that are not observable by the SDK.
 */
import { Content } from '@google/genai';
import { Context } from '@opentelemetry/api';
import { BaseAgent } from '../agents/base_agent.js';
import { InvocationContext } from '../agents/invocation_context.js';
import { Event } from '../events/event.js';
import { LlmRequest } from '../models/llm_request.js';
import { LlmResponse } from '../models/llm_response.js';
import { BaseTool } from '../tools/base_tool.js';
export declare const tracer: import("@opentelemetry/api").Tracer;
export interface TraceAgentInvocationParams {
    agent: BaseAgent;
    invocationContext: InvocationContext;
}
/**
 * Sets span attributes immediately available on agent invocation according to OTEL semconv version 1.37.
 *
 * @param params The parameters object containing agent and invocation context.
 *
 * Inference related fields are not set, due to their planned removal from invoke_agent span:
 * https://github.com/open-telemetry/semantic-conventions/issues/2632
 *
 * `gen_ai.agent.id` is not set because currently it's unclear what attributes this field should have, specifically:
 * - In which scope should it be unique (globally, given project, given agentic flow, given deployment).
 * - Should it be unchanging between deployments, and how this should this be achieved.
 *
 * `gen_ai.data_source.id` is not set because it's not available.
 * Closest type which could contain this information is types.GroundingMetadata, which does not have an ID.
 *
 * `server.*` attributes are not set pending confirmation from aabmass.
 */
export declare function traceAgentInvocation({ agent, invocationContext, }: TraceAgentInvocationParams): void;
export interface TraceWorkflowInvocationParams {
    workflowName: string;
    nodePath: string;
    sessionId: string;
}
export declare function traceWorkflowInvocation({ workflowName, nodePath, sessionId, }: TraceWorkflowInvocationParams): void;
export type NodeExecutionStatus = 'completed' | 'waiting' | 'failed';
export interface TraceNodeExecutionParams {
    nodePath: string;
    runId: string;
    attempt: number;
    status: NodeExecutionStatus;
    interruptCount: number;
}
export declare function traceNodeExecution({ nodePath, runId, attempt, status, interruptCount, }: TraceNodeExecutionParams): void;
export interface TraceToolCallParams {
    tool: BaseTool;
    args: Record<string, unknown>;
    functionResponseEvent: Event;
}
/**
 * Traces tool call.
 *
 * @param params The parameters object containing tool, args, and function response event.
 */
export declare function traceToolCall({ tool, args, functionResponseEvent, }: TraceToolCallParams): void;
export interface TraceMergedToolCallsParams {
    responseEventId: string;
    functionResponseEvent: Event;
}
/**
 * Traces merged tool call events.
 *
 * Calling this function is not needed for telemetry purposes. This is provided
 * for preventing /debug/trace requests (typically sent by web UI).
 *
 * @param params The parameters object containing response event ID and function response event.
 */
export declare function traceMergedToolCalls({ responseEventId, functionResponseEvent, }: TraceMergedToolCallsParams): void;
export interface TraceCallLlmParams {
    invocationContext: InvocationContext;
    eventId: string;
    llmRequest: LlmRequest;
    llmResponse: LlmResponse;
}
/**
 * Traces a call to the LLM.
 *
 * This function records details about the LLM request and response as
 * attributes on the current OpenTelemetry span.
 *
 * @param params The parameters object containing invocationContext, eventId, llmRequest, and llmResponse.
 */
export declare function traceCallLlm({ invocationContext, eventId, llmRequest, llmResponse, }: TraceCallLlmParams): void;
export interface TraceSendDataParams {
    /** The invocation context for the current agent run. */
    invocationContext: InvocationContext;
    /** The ID of the event. */
    eventId: string;
    /** A list of content objects. */
    data: Content[];
}
/**
 * Traces the sending of data to the agent.
 *
 * This function records details about the data sent to the agent as
 * attributes on the current OpenTelemetry span.
 *
 * @param params The parameters object containing invocationContext, eventId, and data.
 */
export declare function traceSendData({ invocationContext, eventId, data, }: TraceSendDataParams): void;
/**
 * Runs an async generator function with both OTEL context and JavaScript 'this' context.
 *
 * @param otelContext - The OpenTelemetry context to bind the generator to
 * @param generatorFnContext - The 'this' context to bind to the generator function
 * @param generatorFn - The generator function to execute
 *
 * @returns A new async generator that executes within both contexts
 */
export declare function runAsyncGeneratorWithOtelContext<TThis, T>(otelContext: Context, generatorFnContext: TThis, generatorFn: (this: TThis) => AsyncGenerator<T, void, void>): AsyncGenerator<T, void, void>;