/**
 * @license
 * Copyright 2025 Google LLC
 * SPDX-License-Identifier: Apache-2.0
 */
import { GenerateContentConfig, Schema } from '@google/genai';
import { FinishTaskTool } from '../tools/finish_task_tool.js';
import { type BaseNode } from '../workflow/base_node.js';
import { NodeContext } from '../workflow/node_context.js';
import { z as z3 } from 'zod/v3';
import { z as z4 } from 'zod/v4';
import { BaseCodeExecutor } from '../code_executors/base_code_executor.js';
import { Event } from '../events/event.js';
import { BaseExampleProvider } from '../examples/base_example_provider.js';
import { Example } from '../examples/example.js';
import { BaseLlm } from '../models/base_llm.js';
import { LlmRequest } from '../models/llm_request.js';
import { LlmResponse } from '../models/llm_response.js';
import { BaseTool } from '../tools/base_tool.js';
import { BaseToolset } from '../tools/base_toolset.js';
import { Context } from './context.js';
import { SchemaLike } from '../utils/schema.js';
import { BaseAgent, BaseAgentConfig } from './base_agent.js';
import { BaseLlmRequestProcessor, BaseLlmResponseProcessor } from './processors/base_llm_processor.js';
import { BaseContextCompactor } from '../context/base_context_compactor.js';
import { InvocationContext } from './invocation_context.js';
import { ReadonlyContext } from './readonly_context.js';
/**
 * Input/output schema type for agent.
 */
export type LlmAgentSchema = z3.ZodObject<z3.ZodRawShape> | z4.ZodObject<z4.ZodRawShape> | Schema;
/** An object that can provide an instruction string. */
export type InstructionProvider = (context: ReadonlyContext) => string | Promise<string>;
/**
 * A callback that runs before a request is sent to the model.
 *
 * @param params.context The current callback context.
 * @param params.request The raw model request. Callback can mutate the request.
 * @returns The content to return to the user. When present, the model call
 *     will be skipped and the provided content will be returned to user.
 */
export type SingleBeforeModelCallback = (params: {
    context: Context;
    request: LlmRequest;
}) => LlmResponse | undefined | Promise<LlmResponse | undefined>;
/**
 * A single callback or a list of callbacks.
 *
 * When a list of callbacks is provided, the callbacks will be called in the
 * order they are listed until a callback does not return None.
 */
export type BeforeModelCallback = SingleBeforeModelCallback | SingleBeforeModelCallback[];
/**
 * A callback that runs after a response is received from the model.
 *
 * @param params.context The current callback context.
 * @param params.response The actual model response.
 * @returns The content to return to the user. When present, the actual model
 *     response will be ignored and the provided content will be returned to
 *     user.
 */
export type SingleAfterModelCallback = (params: {
    context: Context;
    response: LlmResponse;
}) => LlmResponse | undefined | Promise<LlmResponse | undefined>;
/**
 * A single callback or a list of callbacks.
 *
 * When a list of callbacks is provided, the callbacks will be called in the
 order they are listed until a callback does not return None.
 */
export type AfterModelCallback = SingleAfterModelCallback | SingleAfterModelCallback[];
/**
 * A callback that runs before a tool is called.
 *
 * @param params.tool The tool to be called.
 * @param params.args The arguments to the tool.
 * @param params.context Context for the tool call.
 * @returns The tool response. When present, the returned tool response will
 *     be used and the framework will skip calling the actual tool.
 */
export type SingleBeforeToolCallback = (params: {
    tool: BaseTool;
    args: Record<string, unknown>;
    context: Context;
}) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>;
/**
 * A single callback or a list of callbacks.
 *
 * When a list of callbacks is provided, the callbacks will be called in the
 * order they are listed until a callback does not return None.
 */
export type BeforeToolCallback = SingleBeforeToolCallback | SingleBeforeToolCallback[];
/**
 * A callback that runs after a tool is called.
 *
 * @param params.tool The tool to be called.
 * @param params.args The arguments to the tool.
 * @param params.context Context for the tool call.
 * @param params.response The response from the tool.
 * @returns When present, the returned record will be used as tool result.
 */
export type SingleAfterToolCallback = (params: {
    tool: BaseTool;
    args: Record<string, unknown>;
    context: Context;
    response: Record<string, unknown>;
}) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>;
/**
 * A single callback or a list of callbacks.
 *
 * When a list of callbacks is provided, the callbacks will be called in the
 * order they are listed until acallback does not return None.
 */
export type AfterToolCallback = SingleAfterToolCallback | SingleAfterToolCallback[];
/** A list of examples or an example provider. */
export type ExamplesUnion = Example[] | BaseExampleProvider;
/** A union of tool types that can be provided to an agent. */
export type ToolUnion = BaseTool | BaseToolset | BaseNode;
/**
 * The configuration options for creating an LLM-based agent.
 */
export interface LlmAgentConfig extends BaseAgentConfig {
    /**
     * The model to use for the agent.
     */
    model?: string | BaseLlm;
    /** Instructions for the LLM model, guiding the agent's behavior. */
    instruction?: string | InstructionProvider;
    /**
     * Instructions for all the agents in the entire agent tree.
     *
     * ONLY the globalInstruction in root agent will take effect.
     *
     * For example: use globalInstruction to make all agents have a stable
     * identity or personality.
     *
     * @deprecated Use GlobalInstructionPlugin instead.
     */
    globalInstruction?: string | InstructionProvider;
    /** Tools available to this agent. */
    tools?: ToolUnion[];
    /**
     * The additional content generation configurations.
     *
     * NOTE: not all fields are usable, e.g. tools must be configured via
     * `tools`, thinking_config must be configured via `planner` in LlmAgent.
     *
     * For example: use this config to adjust model temperature, configure safety
     * settings, etc.
     */
    generateContentConfig?: GenerateContentConfig;
    /**
     * Disallows LLM-controlled transferring to the parent agent.
     *
     * NOTE: Setting this as True also prevents this agent to continue reply to
     * the end-user. This behavior prevents one-way transfer, in which end-user
     * may be stuck with one agent that cannot transfer to other agents in the
     * agent tree.
     */
    disallowTransferToParent?: boolean;
    /** Disallows LLM-controlled transferring to the peer agents. */
    disallowTransferToPeers?: boolean;
    /**
     * Controls content inclusion in model requests.
     *
     * Options:
     *   default: Model receives relevant conversation history
     *   none: Model receives no prior history, operates solely on current
     *   instruction and input
     */
    includeContents?: 'default' | 'none';
    /**
     * The agent's execution mode when run as a workflow node.
     *
     * - `single_turn` (default): the agent runs once against the node input.
     * - `task`: the agent is given a `finish_task` tool and runs a multi-round
     *   loop until it calls `finish_task`, whose arguments (conforming to
     *   `outputSchema`) become the node output. Mirrors Python's `Agent(mode=...)`.
     */
    mode?: 'single_turn' | 'task';
    /** The input schema when agent is used as a tool. */
    inputSchema?: LlmAgentSchema;
    /** The output schema when agent replies. */
    outputSchema?: LlmAgentSchema;
    /**
     * The key in session state to store the output of the agent.
     *
     * Typically use cases:
     * - Extracts agent reply for later use, such as in tools, callbacks, etc.
     * - Connects agents to coordinate with each other.
     */
    outputKey?: string;
    /**
     * Callbacks to be called before calling the LLM.
     */
    beforeModelCallback?: BeforeModelCallback;
    /**
     * Callbacks to be called after calling the LLM.
     */
    afterModelCallback?: AfterModelCallback;
    /**
     * Callbacks to be called before calling the tool.
     */
    beforeToolCallback?: BeforeToolCallback;
    /**
     * Callbacks to be called after calling the tool.
     */
    afterToolCallback?: AfterToolCallback;
    /**
     * Processors to run before the LLM request is sent.
     */
    requestProcessors?: BaseLlmRequestProcessor[];
    /**
     * Processors to run after the LLM response is received.
     */
    responseProcessors?: BaseLlmResponseProcessor[];
    /**
     * A list of context compactors to evaluate in priority order.
     * Modifies the session history to keep context overhead within limits.
     */
    contextCompactors?: BaseContextCompactor[];
    /**
     * Instructs the agent to make a plan and execute it step by step.
     */
    codeExecutor?: BaseCodeExecutor;
}
/**
 * A unique symbol to identify ADK agent classes.
 * Defined once and shared by all LlmAgent instances.
 */
declare const LLM_AGENT_SIGNATURE_SYMBOL: unique symbol;
/**
 * Type guard to check if an object is an instance of LlmAgent.
 * @param obj The object to check.
 * @returns True if the object is an instance of LlmAgent, false otherwise.
 */
export declare function isLlmAgent(obj: unknown): obj is LlmAgent;
/**
 * An agent that uses a large language model to generate responses.
 */
export declare class LlmAgent extends BaseAgent<LlmAgentConfig> {
    /** A unique symbol to identify ADK LLM agent class. */
    readonly [LLM_AGENT_SIGNATURE_SYMBOL] = true;
    model?: string | BaseLlm;
    instruction: string | InstructionProvider;
    /** @deprecated Use GlobalInstructionPlugin instead. */
    globalInstruction: string | InstructionProvider;
    tools: ToolUnion[];
    generateContentConfig?: GenerateContentConfig;
    disallowTransferToParent: boolean;
    disallowTransferToPeers: boolean;
    includeContents: 'default' | 'none';
    /**
     * Whether {@link includeContents} was set by the caller rather than defaulted.
     *
     * A workflow node runs its agent for a single turn on the input the graph
     * handed it, so the agent must not also read the surrounding conversation —
     * unless the author asked for it. Mirrors Python checking
     * `'include_contents' in agent.model_fields_set`.
     */
    readonly includeContentsExplicit: boolean;
    mode?: 'single_turn' | 'task';
    inputSchema?: Schema;
    outputSchema?: Schema;
    /**
     * The input schema exactly as it was supplied, before conversion into the
     * genai dialect.
     *
     * `inputSchema` is normalized to a genai `Schema` because that is what the
     * model API and function declarations require, but that conversion is lossy:
     * a Zod refinement, transform, or custom error message has no genai
     * equivalent. Validation therefore uses the original, falling back to the
     * converted form when the schema was given in the genai dialect to begin
     * with.
     */
    readonly inputSchemaSource?: SchemaLike;
    /** The output schema as supplied — see {@link inputSchemaSource}. */
    readonly outputSchemaSource?: SchemaLike;
    outputKey?: string;
    private _finishTaskTool?;
    beforeModelCallback?: BeforeModelCallback;
    afterModelCallback?: AfterModelCallback;
    beforeToolCallback?: BeforeToolCallback;
    afterToolCallback?: AfterToolCallback;
    requestProcessors: BaseLlmRequestProcessor[];
    responseProcessors: BaseLlmResponseProcessor[];
    codeExecutor?: BaseCodeExecutor;
    constructor(config: LlmAgentConfig);
    /**
     * The resolved BaseLlm instance.
     *
     * When not set, the agent will inherit the model from its ancestor.
     */
    get canonicalModel(): BaseLlm;
    /**
     * The `finish_task` tool for this agent (task mode). Lazily created and cached
     * so its declaration (derived from `outputSchema`) is stable across turns.
     */
    get finishTaskTool(): FinishTaskTool;
    /**
     * The resolved instruction field to construct instruction for this
     * agent.
     *
     * This method is only for use by Agent Development Kit.
     * @param context The context to retrieve the session state.
     * @returns The resolved instruction field.
     */
    canonicalInstruction(context: ReadonlyContext): Promise<{
        instruction: string;
        requireStateInjection: boolean;
    }>;
    /**
     * The resolved globalInstruction field to construct global instruction.
     *
     * This method is only for use by Agent Development Kit.
     * @param context The context to retrieve the session state.
     * @returns The resolved globalInstruction field.
     * @deprecated Use GlobalInstructionPlugin instead.
     */
    canonicalGlobalInstruction(context: ReadonlyContext): Promise<{
        instruction: string;
        requireStateInjection: boolean;
    }>;
    /**
     * The resolved tools field as a list of BaseTool based on the context.
     *
     * This method is only for use by Agent Development Kit.
     */
    canonicalTools(context?: ReadonlyContext): Promise<BaseTool[]>;
    /**
     * Normalizes a callback or an array of callbacks into an array of callbacks.
     *
     * @param callback The callback or an array of callbacks.
     * @returns An array of callbacks.
     */
    private static normalizeCallbackArray;
    /**
     * The resolved beforeModelCallback field as a list of
     * SingleBeforeModelCallback.
     *
     * This method is only for use by Agent Development Kit.
     */
    get canonicalBeforeModelCallbacks(): SingleBeforeModelCallback[];
    /**
     * The resolved afterModelCallback field as a list of
     * SingleAfterModelCallback.
     *
     * This method is only for use by Agent Development Kit.
     */
    get canonicalAfterModelCallbacks(): SingleAfterModelCallback[];
    /**
     * The resolved beforeToolCallback field as a list of
     * BeforeToolCallback.
     *
     * This method is only for use by Agent Development Kit.
     */
    get canonicalBeforeToolCallbacks(): SingleBeforeToolCallback[];
    /**
     * The resolved afterToolCallback field as a list of AfterToolCallback.
     *
     * This method is only for use by Agent Development Kit.
     */
    get canonicalAfterToolCallbacks(): SingleAfterToolCallback[];
    /**
     * Saves the agent's final response to the session state if configured.
     *
     * It extracts the text content from the final response event, optionally
     * parses it as JSON based on the output schema, and stores the result in the
     * session state using the specified output key.
     *
     * @param event The event to process.
     */
    private maybeSaveOutputToState;
    /**
     * Validates a value against this agent's output schema, in whichever dialect
     * it was declared, and returns the parsed value.
     *
     * Prefers the schema as supplied ({@link outputSchemaSource}) over the genai
     * form derived from it, since the conversion drops constraints Zod can
     * express and genai cannot.
     *
     * @throws if the value does not satisfy the schema.
     */
    validateOutput(value: unknown): unknown;
    /**
     * Runs this agent as a workflow node.
     *
     * Where {@link BaseAgent.runImpl} delegates straight to `runAsync`, an
     * `LlmAgent` has a node input to inject into the conversation, instruction
     * placeholders to resolve against it, a reply to promote to node output, and
     * — in `task` mode — a `finish_task` round-trip to drive. All of that lives
     * in `runLlmAgentAsNode`, mirroring adk-python's `LlmAgent._run_impl`
     * delegating to `run_llm_agent_as_node`.
     */
    protected runImpl(ctx: NodeContext, nodeInput: unknown): AsyncGenerator<Event, void, void>;
    protected runAsyncImpl(context: InvocationContext): AsyncGenerator<Event, void, void>;
    protected runLiveImpl(context: InvocationContext): AsyncGenerator<Event, void, void>;
    /**
     * Runs the bidirectional (live) flow for this agent.
     *
     * Establishes a live connection to the model, drains the invocation's
     * `liveRequestQueue` into the connection on a parallel task, and yields
     * events derived from server messages until the queue closes, the model
     * finishes, or an agent transfer occurs.
     *
     * If the live connection drops (network failure, server `goAway`) and a
     * session resumption handle has been observed, the flow transparently
     * reconnects using that handle up to {@link MAX_LIVE_RECONNECT_ATTEMPTS}
     * times. Subsequent reconnects skip `sendHistory` because the server
     * already holds the conversation state associated with the handle.
     */
    private runLiveFlow;
    private runLivePreprocess;
    private runSendLoop;
    private dispatchLiveRequest;
    /**
     * Tears down a live attempt: stops the send loop, closes the connection
     * (swallowing close errors), and waits for the send task to settle. Used
     * before reconnecting or propagating an error.
     */
    private teardownLiveConnection;
    private runReceiveLoop;
    private postprocessLive;
    private runOneStepAsync;
    private postprocess;
    /**
     * Retrieves an agent from the agent tree by its name.
     *
     * Performing a depth-first search to locate the agent with the given name.
     * - Starts searching from the root agent of the current invocation context.
     * - Traverses down the agent tree to find the specified agent.
     *
     * @param invocationContext The current invocation context.
     * @param agentName The name of the agent to retrieve.
     * @returns The agent with the given name.
     * @throws Error if the agent is not found.
     */
    private getAgentByName;
    protected callLlmAsync(invocationContext: InvocationContext, llmRequest: LlmRequest, modelResponseEvent: Event): AsyncGenerator<LlmResponse, void, void>;
    private handleBeforeModelCallback;
    private handleAfterModelCallback;
    protected runAndHandleError<T extends LlmResponse | Event>(responseGenerator: AsyncGenerator<T, void, void>, invocationContext: InvocationContext, llmRequest: LlmRequest, modelResponseEvent: Event): AsyncGenerator<T, void, void>;
}
export {};