@google/adk 2.2.1 → 2.4.0

package/dist/types/agents/functions.d.ts

@@ -9,11 +9,14 @@ import { Event } from '../events/event.js';
 import { BaseTool } from '../tools/base_tool.js';
 import { ResumeInputs } from '../tools/resume_inputs.js';
 import { ToolConfirmation } from '../tools/tool_confirmation.js';
+import { Context } from './context.js';
 import { SingleAfterToolCallback, SingleBeforeToolCallback } from './llm_agent.js';
 export { AF_FUNCTION_CALL_ID_PREFIX, generateClientFunctionCallId, populateClientFunctionCallId, } from '../events/event.js';
 export { REQUEST_CONFIRMATION_FUNCTION_CALL_NAME, REQUEST_CREDENTIAL_FUNCTION_CALL_NAME, REQUEST_INPUT_FUNCTION_CALL_NAME, reservedFunctionCallName, } from './framework_function_calls.js';
 export declare const functionsExportedForTestingOnly: {
     handleFunctionCallList: typeof handleFunctionCallList;
+    handleFunctionCallsLive: typeof handleFunctionCallsLive;
+    processFunctionLiveHelper: typeof processFunctionLiveHelper;
     generateAuthEvent: typeof generateAuthEvent;
     generateRequestConfirmationEvent: typeof generateRequestConfirmationEvent;
 };
@@ -63,6 +66,23 @@ export declare function handleFunctionCallsAsync({ invocationContext, functionCa
     toolConfirmationDict?: Record<string, ToolConfirmation>;
     resumeInputsDict?: Record<string, ResumeInputs>;
 }): Promise<Event | null>;
+/**
+ * Handles function calls in a live (bidirectional streaming) session.
+ *
+ * Supports regular sync/async tools, async-generator streaming tools that push
+ * incremental results onto `invocationContext.liveRequestQueue`, and the
+ * `stop_streaming` control call that cancels an active streaming tool task.
+ */
+export declare function handleFunctionCallsLive({ invocationContext, functionCallEvent, toolsDict, beforeToolCallbacks, afterToolCallbacks, filters, toolConfirmationDict, resumeInputsDict, }: {
+    invocationContext: InvocationContext;
+    functionCallEvent: Event;
+    toolsDict: Record<string, BaseTool>;
+    beforeToolCallbacks: SingleBeforeToolCallback[];
+    afterToolCallbacks: SingleAfterToolCallback[];
+    filters?: Set<string>;
+    toolConfirmationDict?: Record<string, ToolConfirmation>;
+    resumeInputsDict?: Record<string, ResumeInputs>;
+}): Promise<Event | null>;
 /**
  * Whether `tool` is the placeholder handed to the on-tool-error callbacks for a
  * function call naming a tool this agent cannot call.
@@ -76,7 +96,7 @@ export declare function isToolNotFound(tool: unknown): boolean;
  * function calls instead of an event.
  * This is also used by llm_agent execution flow in preprocessing.
  */
-export declare function handleFunctionCallList({ invocationContext, functionCalls, toolsDict, beforeToolCallbacks, afterToolCallbacks, filters, toolConfirmationDict, resumeInputsDict, }: {
+export declare function handleFunctionCallList({ invocationContext, functionCalls, toolsDict, beforeToolCallbacks, afterToolCallbacks, filters, toolConfirmationDict, resumeInputsDict, isLive, }: {
     invocationContext: InvocationContext;
     functionCalls: FunctionCall[];
     toolsDict: Record<string, BaseTool>;
@@ -91,11 +111,23 @@ export declare function handleFunctionCallList({ invocationContext, functionCall
      * approval; see {@link ResumeInputs}.
      */
     resumeInputsDict?: Record<string, ResumeInputs>;
+    isLive?: boolean;
 }): Promise<Event | null>;
 /**
  * Merges a list of function response events into a single event.
  */
 export declare function mergeParallelFunctionResponseEvents(functionResponseEvents: Event[]): Event;
+/**
+ * Executes a single tool call in live mode, supporting `stop_streaming`,
+ * async-generator streaming tools, and standard sync/async tools.
+ */
+declare function processFunctionLiveHelper({ tool, toolContext, functionCall, functionArgs, invocationContext, }: {
+    tool: BaseTool;
+    toolContext: Context;
+    functionCall: FunctionCall;
+    functionArgs: Record<string, unknown>;
+    invocationContext: InvocationContext;
+}): Promise<unknown>;
 /**
  * Finds the most recent event before `endIndex` that contains a function call
  * with the given ID.

package/dist/types/agents/invocation_context.d.ts

@@ -59,6 +59,24 @@ export interface InvocationContextParams {
      */
     a2aMetadata?: Record<string, unknown>;
 }
+/**
+ * A unique symbol to identify {@link LlmCallsLimitExceededError} instances.
+ */
+declare const LLM_CALLS_LIMIT_EXCEEDED_ERROR_SIGNATURE_SYMBOL: unique symbol;
+/**
+ * Error thrown when the number of LLM calls in an invocation exceeds {@link RunConfig.maxLlmCalls}.
+ */
+export declare class LlmCallsLimitExceededError extends Error {
+    readonly [LLM_CALLS_LIMIT_EXCEEDED_ERROR_SIGNATURE_SYMBOL] = true;
+    constructor(message: string);
+}
+/**
+ * Type guard to check if an object is an instance of {@link LlmCallsLimitExceededError}.
+ *
+ * @param obj The object to check.
+ * @returns True if the object is an instance of {@link LlmCallsLimitExceededError}.
+ */
+export declare function isLlmCallsLimitExceededError(obj: unknown): obj is LlmCallsLimitExceededError;
 /**
  * An invocation context represents the data of a single invocation of an agent.
  *
@@ -198,7 +216,7 @@ export declare class InvocationContext {
      * The live request queue feeding the model on the bidirectional (live) path.
      * Set only for invocations started via `runner.runLive`.
      */
-    readonly liveRequestQueue?: LiveRequestQueue;
+    liveRequestQueue?: LiveRequestQueue;
     /**
      * The most recent session resumption handle observed on the live path.
      * Updated as the server emits resumption updates so a reconnect can restore
@@ -255,3 +273,4 @@ export declare function newInvocationContextId(): string;
  * @throws if the invocation is driving a bare node rather than an agent.
  */
 export declare function requireAgent(ctx: InvocationContext): BaseAgent;
+export {};

package/dist/types/agents/langgraph_agent.d.ts

@@ -0,0 +1,153 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../events/event.js';
+import { BaseAgent, BaseAgentConfig } from './base_agent.js';
+import { InvocationContext } from './invocation_context.js';
+/**
+ * Text or structured content part inside a LangGraph message content array.
+ */
+export interface LangGraphContentPart {
+    readonly type?: string;
+    readonly text?: string;
+}
+/**
+ * Content carried by a LangGraph message (`string` or an array of content parts).
+ */
+export type LangGraphMessageContent = string | ReadonlyArray<string | LangGraphContentPart>;
+/**
+ * Structural representation of a message exchanged with a LangGraph graph.
+ */
+export interface LangGraphMessageLike {
+    /**
+     * Text or structured content of the message.
+     */
+    readonly content: LangGraphMessageContent;
+    /**
+     * Optional role or message type identifier (`'human'`, `'ai'`, or `'system'`).
+     */
+    readonly type?: string;
+}
+/**
+ * Represents a human user message passed to a LangGraph graph.
+ */
+export interface LangGraphHumanMessage extends LangGraphMessageLike {
+    readonly type: 'human';
+    readonly content: string;
+}
+/**
+ * Represents an AI assistant message passed to or returned by a LangGraph graph.
+ */
+export interface LangGraphAIMessage extends LangGraphMessageLike {
+    readonly type: 'ai';
+    readonly content: LangGraphMessageContent;
+}
+/**
+ * Represents a system instruction message passed to a LangGraph graph.
+ */
+export interface LangGraphSystemMessage extends LangGraphMessageLike {
+    readonly type: 'system';
+    readonly content: string;
+}
+/**
+ * Runnable configuration passed to a compiled LangGraph graph invocation.
+ */
+export interface LangGraphRunnableConfig {
+    readonly configurable: {
+        /**
+         * Thread identifier expected in `snake_case` by LangGraph.js checkpointers.
+         */
+        readonly thread_id: string;
+    };
+}
+/**
+ * State snapshot returned by a compiled LangGraph graph's `getState` method.
+ */
+export interface LangGraphStateSnapshot {
+    readonly values?: {
+        readonly messages?: readonly LangGraphMessageLike[];
+    };
+}
+/**
+ * Input state passed to a compiled LangGraph graph's `invoke` method.
+ */
+export interface LangGraphInvokeInput {
+    readonly messages: readonly LangGraphMessageLike[];
+}
+/**
+ * Output state returned by a compiled LangGraph graph's `invoke` method.
+ */
+export interface LangGraphInvokeOutput {
+    readonly messages?: readonly LangGraphMessageLike[];
+}
+/**
+ * Structural interface for a compiled LangGraph graph.
+ */
+export interface CompiledGraphLike {
+    /**
+     * Optional checkpointer configured on the compiled graph for multi-turn state persistence.
+     */
+    readonly checkpointer?: unknown;
+    /**
+     * Optional helper returning the underlying graph representation.
+     */
+    getGraph?(...args: unknown[]): unknown;
+    /**
+     * Retrieves the current graph state for the given runnable configuration.
+     */
+    getState?(config: LangGraphRunnableConfig): LangGraphStateSnapshot | undefined | Promise<LangGraphStateSnapshot | undefined>;
+    /**
+     * Invokes the compiled graph with the given message list and runnable configuration.
+     */
+    invoke(input: LangGraphInvokeInput, config: LangGraphRunnableConfig): LangGraphInvokeOutput | Promise<LangGraphInvokeOutput>;
+}
+/**
+ * Configuration options for {@link LangGraphAgent}.
+ */
+export interface LangGraphAgentConfig extends BaseAgentConfig {
+    /**
+     * The compiled LangGraph graph to execute.
+     */
+    graph: CompiledGraphLike;
+    /**
+     * Optional system instruction prepended when the graph state has no existing messages.
+     */
+    instruction?: string;
+}
+/**
+ * Extracts the trailing contiguous sequence of human user messages from `events`.
+ *
+ * @param events The session events to inspect.
+ * @returns The trailing user messages in chronological order.
+ */
+export declare function getLastHumanMessages(events: readonly Event[]): LangGraphHumanMessage[];
+declare const LANGGRAPH_AGENT_SIGNATURE_SYMBOL: unique symbol;
+/**
+ * Type guard to check if an object is an instance of {@link LangGraphAgent}.
+ *
+ * @param obj The object to check.
+ * @returns True if the object is an instance of {@link LangGraphAgent}.
+ */
+export declare function isLangGraphAgent(obj: unknown): obj is LangGraphAgent;
+/**
+ * An agent that wraps a compiled LangGraph graph for single-turn and multi-turn execution.
+ */
+export declare class LangGraphAgent extends BaseAgent<LangGraphAgentConfig> {
+    readonly [LANGGRAPH_AGENT_SIGNATURE_SYMBOL] = true;
+    /**
+     * The compiled LangGraph graph executed by this agent.
+     */
+    readonly graph: CompiledGraphLike;
+    /**
+     * System instruction prepended when the graph state contains no prior messages.
+     */
+    readonly instruction: string;
+    constructor(config: LangGraphAgentConfig);
+    protected runAsyncImpl(ctx: InvocationContext): AsyncGenerator<Event, void, void>;
+    protected runLiveImpl(_ctx: InvocationContext): AsyncGenerator<Event, void, void>;
+    private getMessages;
+    private getConversationWithAgent;
+}
+export {};

package/dist/types/agents/llm_agent.d.ts

@@ -226,7 +226,11 @@ export interface LlmAgentConfig extends BaseAgentConfig {
      */
     contextCompactors?: BaseContextCompactor[];
     /**
-     * Instructs the agent to make a plan and execute it step by step.
+     * Allows the agent to execute code blocks from model responses using the
+     * provided `BaseCodeExecutor`.
+     *
+     * NOTE: to use the model's built-in code executor, use the
+     * `BuiltInCodeExecutor`.
      */
     codeExecutor?: BaseCodeExecutor;
     /**

package/dist/types/agents/processors/content_processor_utils.d.ts

@@ -20,10 +20,12 @@ export declare function removeClientFunctionCallId(content: Content): void;
  * @param agentName: The name of the agent.
  * @param currentBranch: The current branch of the agent.
  * @param currentIsolationScope: The isolation scope of the current node, if any.
+ * @param preserveFunctionCallIds: Whether to preserve client-generated
+ *     `adk-*` function call and response IDs instead of stripping them.
  *
  * @returns A list of processed contents.
  */
-export declare function getContents(events: Event[], agentName: string, currentBranch?: string, currentIsolationScope?: string): Content[];
+export declare function getContents(events: Event[], agentName: string, currentBranch?: string, currentIsolationScope?: string, preserveFunctionCallIds?: boolean): Content[];
 /**
  * Get contents for the current turn only (no conversation history).
  *
@@ -42,7 +44,7 @@ export declare function getContents(events: Event[], agentName: string, currentB
  * @returns A list of contents for the current turn only, preserving context
  *     needed for proper tool execution while excluding conversation history.
  */
-export declare function getCurrentTurnContents(events: Event[], agentName: string, currentBranch?: string, currentIsolationScope?: string): Content[];
+export declare function getCurrentTurnContents(events: Event[], agentName: string, currentBranch?: string, currentIsolationScope?: string, preserveFunctionCallIds?: boolean): Content[];
 /**
  * Merges a list of function_response events into one event.
  *

package/dist/types/agents/processors/nl_planning_processor.d.ts

@@ -19,7 +19,8 @@ export declare class NlPlanningRequestProcessor extends BaseLlmRequestProcessor
     runAsync(invocationContext: InvocationContext, llmRequest: LlmRequest): AsyncGenerator<Event, void, void>;
 }
 /**
- * Replaces the LLM response parts with the planner's processed parts.
+ * Replaces the LLM response parts with the planner's processed parts and emits
+ * a state-update event when the planner modifies session state.
  *
  * Partial responses are processed too.
  */

package/dist/types/auth/auth_handler.d.ts

@@ -12,7 +12,12 @@ import { AuthConfig } from './auth_tool.js';
  * This class should only be used by Agent Development Kit.
  */
 export declare class AuthHandler {
-    private readonly authConfig;
+    authConfig: AuthConfig;
+    /**
+     * @param authConfig The auth config this handler reads. It stays readable
+     *     and replaceable after construction; each method reads the current
+     *     value.
+     */
     constructor(authConfig: AuthConfig);
     getAuthResponse(state: State): AuthCredential | undefined;
     /**
@@ -22,6 +27,24 @@ export declare class AuthHandler {
      * @throws Error: If the auth config has no credentialKey.
      */
     parseAndStoreAuthResponse(state: State): Promise<void>;
+    /**
+     * Builds the auth request to send to the client.
+     *
+     * The result is always a new object, and its `exchangedAuthCredential` is
+     * never an object held by {@link authConfig}. A caller that fills in the
+     * response, for example `exchangedAuthCredential.oauth2.authResponseUri`,
+     * therefore leaves the handler's credentials unchanged.
+     *
+     * When the config is returned as is, because the scheme is not OAuth2 or
+     * OpenID Connect or the exchanged credential already has an auth URI, the
+     * result is a deep copy of the whole config. In the other branches only the
+     * exchanged credential is guaranteed independent: `authScheme` and
+     * `rawAuthCredential` are the handler's own objects.
+     *
+     * @return The auth config to request from the client.
+     * @throws Error: If an OAuth2 or OpenID Connect scheme has no raw
+     *     credential, no `oauth2` on it, or no client ID and secret.
+     */
     generateAuthRequest(): AuthConfig;
     /**
      * Generates an response containing the auth uri for user to sign in.
@@ -30,6 +53,10 @@ export declare class AuthHandler {
      * challenge derived from the credential's code verifier, and the returned
      * credential carries the verifier the later token exchange must send.
      *
+     * The URI leaves out `redirect_uri` when the credential has no
+     * `redirectUri`, so the provider uses the redirect registered for the
+     * client, and leaves out `scope` when the scheme lists no scopes.
+     *
      * @return An AuthCredential object containing the auth URI and state.
      * @throws Error: If the authorization endpoint is not configured in the
      *     auth scheme, or the credential requests a code challenge method other

package/dist/types/auth/auth_schemes.d.ts

@@ -23,6 +23,19 @@ export interface OpenIdConnectWithConfig extends OpenAPIV3.OpenIdSecurityScheme
  * OpenIdConnectWithConfig.
  */
 export type AuthScheme = OpenAPIV3.SecuritySchemeObject | OpenIdConnectWithConfig;
+/**
+ * The OpenAPI security scheme types an {@link AuthScheme} can declare.
+ *
+ * The values are the exact strings of the OpenAPI `type` field, so a member
+ * compares equal to `authScheme.type` and can be enumerated at runtime with
+ * `Object.values(AuthSchemeType)`.
+ */
+export declare enum AuthSchemeType {
+    API_KEY = "apiKey",
+    HTTP = "http",
+    OAUTH2 = "oauth2",
+    OPEN_ID_CONNECT = "openIdConnect"
+}
 /**
  * Represents the OAuth2 flow (or grant type).
  */

package/dist/types/cli/cli_eval.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseAgent } from '../agents/base_agent.js';
+import { BaseArtifactService } from '../artifacts/base_artifact_service.js';
+import { BaseSessionService } from '../sessions/base_session_service.js';
+import { EvaluationItem } from './utils/evals.js';
+/**
+ * Error message when evaluation dependencies are missing.
+ */
+export declare const MISSING_EVAL_DEPENDENCIES_MESSAGE = "Eval module is not installed, please install via `pip install google-adk[eval]`.";
+/**
+ * Metric key for average tool trajectory score.
+ */
+export declare const TOOL_TRAJECTORY_SCORE_KEY = "tool_trajectory_avg_score";
+/**
+ * Metric key for response match (ROUGE-1) score.
+ */
+export declare const RESPONSE_MATCH_SCORE_KEY = "response_match_score";
+/**
+ * Metric key for LLM-based response evaluation score.
+ */
+export declare const RESPONSE_EVALUATION_SCORE_KEY = "response_evaluation_score";
+/**
+ * Prefix applied to session IDs generated during evaluation runs.
+ */
+export declare const EVAL_SESSION_ID_PREFIX = "___eval___session___";
+/**
+ * Default evaluation criteria thresholds when no config file is supplied.
+ */
+export declare const DEFAULT_CRITERIA: Record<string, number>;
+/**
+ * Outcome status of an evaluation metric or case.
+ */
+export declare enum EvalStatus {
+    PASSED = 1,
+    FAILED = 2,
+    NOT_EVALUATED = 3
+}
+/**
+ * An evaluation metric definition and its pass threshold.
+ */
+export interface EvalMetric {
+    metric_name: string;
+    threshold: number;
+}
+/**
+ * Result of evaluating a single metric.
+ */
+export interface EvalMetricResult extends EvalMetric {
+    score?: number;
+    eval_status: EvalStatus;
+}
+/**
+ * Per-invocation evaluation metric breakdown.
+ */
+export interface InvocationEvalMetricResult {
+    actual_invocation: EvaluationItem;
+    expected_invocation: EvaluationItem;
+    eval_metric_results: EvalMetricResult[];
+}
+/**
+ * Complete evaluation result for a single eval case in an evalset.
+ */
+export interface EvalResult {
+    eval_set_file: string;
+    eval_id: string;
+    final_eval_status: EvalStatus;
+    eval_metric_results: Array<[EvalMetric, EvalMetricResult]>;
+    overall_eval_metric_results: EvalMetricResult[];
+    eval_metric_result_per_invocation: InvocationEvalMetricResult[];
+    session_id: string;
+    user_id?: string;
+}
+/**
+ * Request payload for adding a session to an eval set (`add_session`).
+ */
+export interface AddSessionToEvalSetRequest {
+    evalId: string;
+    sessionId: string;
+    userId: string;
+}
+/**
+ * Request payload for running evaluations on an eval set (`run_eval`).
+ */
+export interface RunEvalRequest {
+    evalIds: string[];
+    evalMetrics: EvalMetric[];
+}
+/**
+ * Result returned for a single evaluation case by the `run_eval` endpoint.
+ */
+export interface RunEvalResult extends EvalResult {
+    evalSetFile: string;
+    evalSetId: string;
+    evalId: string;
+    finalEvalStatus: EvalStatus;
+    evalMetricResults: Array<[EvalMetric, EvalMetricResult]>;
+    overallEvalMetricResults: EvalMetricResult[];
+    evalMetricResultPerInvocation: InvocationEvalMetricResult[];
+    userId?: string;
+    sessionId: string;
+}
+/**
+ * Initial session metadata for an evaluation case.
+ */
+export interface EvalInitialSession {
+    state?: Record<string, unknown>;
+    app_name?: string;
+    user_id?: string;
+}
+/**
+ * A named evaluation case within an evalset file.
+ */
+export interface EvalEntry {
+    name: string;
+    data: EvaluationItem[];
+    initial_session?: EvalInitialSession;
+}
+/**
+ * Alias for a single evaluation case entry in an evalset.
+ */
+export type EvalSetItem = EvalEntry;
+/**
+ * Options for running evaluations via `runEvals`.
+ */
+export interface RunEvalsOptions {
+    evalCasesByEvalSetId: Record<string, EvalEntry[] | string[]>;
+    rootAgent: BaseAgent;
+    resetFunc?: () => void | Promise<void>;
+    evalMetrics?: EvalMetric[];
+    printDetailedResults?: boolean;
+    sessionService?: BaseSessionService;
+    artifactService?: BaseArtifactService;
+}
+/**
+ * Loads evaluation criteria from a JSON config file, or returns `DEFAULT_CRITERIA`
+ * if no path is supplied.
+ *
+ * @param evalConfigFilePath Optional path to a `test_config.json` file.
+ * @returns Map of metric names to numeric thresholds.
+ */
+export declare function getEvaluationCriteriaOrDefault(evalConfigFilePath?: string): Record<string, number>;
+/**
+ * Dynamically imports an agent module and returns its `rootAgent`.
+ *
+ * @param agentModuleFilePath File or directory path to the agent module.
+ * @returns The loaded `BaseAgent` instance.
+ */
+export declare function getRootAgent(agentModuleFilePath: string): Promise<BaseAgent>;
+/**
+ * Attempts to retrieve an optional `reset_data` or `resetData` function from
+ * the agent module.
+ *
+ * @param agentModuleFilePath File or directory path to the agent module.
+ * @returns The reset function if exported, or `undefined`.
+ */
+export declare function tryGetResetFunc(agentModuleFilePath: string): Promise<(() => void | Promise<void>) | undefined>;
+/**
+ * Parses CLI evalset file arguments of the form `file_path` or
+ * `file_path:eval_1,eval_2` into a mapping from file path to requested eval IDs.
+ *
+ * @param evalSetFilePaths Array of evalset file specifications.
+ * @returns Mapping of evalset file path to list of eval case names.
+ */
+export declare function parseAndGetEvalsToRun(evalSetFilePaths: string[]): Record<string, string[]>;
+/**
+ * Runs a collection of evaluation cases against `rootAgent` and yields an
+ * `EvalResult` for each case.
+ */
+export declare function runEvals(optionsOrMap: RunEvalsOptions | Record<string, EvalEntry[] | string[]>, rootAgentArg?: BaseAgent, resetFuncArg?: () => void | Promise<void>, evalMetricsArg?: EvalMetric[], printDetailedResultsArg?: boolean, sessionServiceArg?: BaseSessionService, artifactServiceArg?: BaseArtifactService): AsyncGenerator<EvalResult, void, void>;

package/dist/types/cli/utils/envs.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Walks up the directory tree starting from `folder` until `filename` is found,
+ * or until the filesystem root is reached.
+ *
+ * @param folder The directory to start searching from.
+ * @param filename The file name to look for. Defaults to `'.env'`.
+ * @returns The absolute path to the found file, or `''` if not found.
+ */
+export declare function walkToRootUntilFound(folder: string, filename?: string): string;
+/**
+ * Walks up from the agent directory to the root directory and loads the first
+ * `.env` file found into `process.env` with override semantics.
+ *
+ * @param agentName The name or path of the agent.
+ * @param agentParentFolder The parent directory containing the agent. Defaults to `'.'`.
+ * @param filename The dotenv filename to search for. Defaults to `'.env'`.
+ */
+export declare function loadDotenvForAgent(agentName: string, agentParentFolder?: string, filename?: string): void;

package/dist/types/cli/utils/evals.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Part } from '@google/genai';
+import { BaseAgent } from '../../agents/base_agent.js';
+import { Session } from '../../sessions/session.js';
+/**
+ * Represents a single expected tool invocation in an evaluation item.
+ */
+export interface ToolUseItem {
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    mock_tool_output?: unknown;
+}
+/**
+ * Represents an intermediate agent response tuple of `[author, parts]`.
+ */
+export type IntermediateAgentResponseItem = [string, Part[]];
+/**
+ * Represents a single turn in an evaluation dataset converted from a session.
+ */
+export interface EvaluationItem {
+    query: string;
+    expected_tool_use: ToolUseItem[];
+    expected_intermediate_agent_responses: IntermediateAgentResponseItem[];
+    reference: string;
+}
+/**
+ * Converts a session into a list of evaluation items suitable for saving into
+ * an evalset or running through `runEvals`.
+ *
+ * @param session The session whose events should be converted.
+ * @returns An array of `EvaluationItem` records, one per user turn.
+ */
+export declare function convertSessionToEvalFormat(session?: Session): EvaluationItem[];
+/**
+ * Creates a state object initialized with empty strings `''` for all `{var}`
+ * placeholders referenced in the instruction strings of `agent` and its
+ * sub-agents, overridden by any keys provided in `initializedStates`.
+ *
+ * @param agent The root agent to inspect.
+ * @param initializedStates Optional pre-initialized state values that take precedence.
+ * @returns The combined state record.
+ */
+export declare function createEmptyState(agent: BaseAgent, initializedStates?: Record<string, unknown>): Record<string, unknown>;

package/dist/types/cli/utils/logs.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LogLevel } from '../../utils/logger.js';
+/**
+ * Standard log format template for CLI log output.
+ */
+export declare const LOGGING_FORMAT = "%(asctime)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s";
+/**
+ * Options for configuring `logToTmpFolder`.
+ */
+export interface LogToTmpFolderOptions {
+    /** Minimum log level to record. Defaults to `LogLevel.INFO`. */
+    level?: LogLevel;
+    /** Subdirectory inside the system temp folder. Defaults to `'agents_log'`. */
+    subFolder?: string;
+    /** Prefix for generated log files. Defaults to `'agent'`. */
+    logFilePrefix?: string;
+    /** Timestamp suffix for the log filename. Defaults to `YYYYMMDD_HHMMSS`. */
+    logFileTimestamp?: string;
+}
+/**
+ * Configures the global ADK logger to write formatted log records to `stderr`.
+ *
+ * @param level The minimum `LogLevel` to emit. Defaults to `LogLevel.INFO`.
+ */
+export declare function setupAdkLogger(level?: LogLevel): void;
+/**
+ * Configures the global ADK logger to write formatted log records to a timestamped
+ * file in the system temporary directory and updates the `<prefix>.latest.log`
+ * symlink to point to the newest file.
+ *
+ * @param options Configuration options for the temporary log file.
+ * @returns The absolute path to the created log file.
+ */
+export declare function logToTmpFolder(options?: LogToTmpFolderOptions): string;