@paean-ai/adk 0.2.19 → 0.2.20

package/dist/esm/agents/llm_agent.js

@@ -0,0 +1,1225 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from "zod";
+import { BaseCodeExecutor } from "../code_executors/base_code_executor.js";
+import { BuiltInCodeExecutor } from "../code_executors/built_in_code_executor.js";
+import { buildCodeExecutionResultPart, buildExecutableCodePart, convertCodeExecutionParts, extractCodeAndTruncateContent } from "../code_executors/code_execution_utils.js";
+import { CodeExecutorContext } from "../code_executors/code_executor_context.js";
+import { createEvent, createNewEventId, getFunctionCalls, getFunctionResponses, isFinalResponse } from "../events/event.js";
+import { createEventActions } from "../events/event_actions.js";
+import { isBaseLlm } from "../models/base_llm.js";
+import { appendInstructions, setOutputSchema } from "../models/llm_request.js";
+import { LLMRegistry } from "../models/registry.js";
+import { State } from "../sessions/state.js";
+import { BaseTool } from "../tools/base_tool.js";
+import { FunctionTool } from "../tools/function_tool.js";
+import { ToolConfirmation } from "../tools/tool_confirmation.js";
+import { ToolContext } from "../tools/tool_context.js";
+import { deepClone } from "../utils/deep_clone.js";
+import { base64Decode } from "../utils/env_aware_utils.js";
+import { logger } from "../utils/logger.js";
+import { BaseAgent } from "./base_agent.js";
+import { BaseLlmRequestProcessor } from "./base_llm_processor.js";
+import { CallbackContext } from "./callback_context.js";
+import { getContents, getCurrentTurnContents } from "./content_processor_utils.js";
+import { generateAuthEvent, generateRequestConfirmationEvent, getLongRunningFunctionCalls, handleFunctionCallList, handleFunctionCallsAsync, populateClientFunctionCallId, REQUEST_CONFIRMATION_FUNCTION_CALL_NAME } from "./functions.js";
+import { injectSessionState } from "./instructions.js";
+import { ReadonlyContext } from "./readonly_context.js";
+import { StreamingMode } from "./run_config.js";
+const ADK_AGENT_NAME_LABEL_KEY = "adk_agent_name";
+async function convertToolUnionToTools(toolUnion, context) {
+  if (toolUnion instanceof BaseTool) {
+    return [toolUnion];
+  }
+  return await toolUnion.getTools(context);
+}
+class BasicLlmRequestProcessor extends BaseLlmRequestProcessor {
+  async *runAsync(invocationContext, llmRequest) {
+    var _a;
+    const agent = invocationContext.agent;
+    if (!(agent instanceof LlmAgent)) {
+      return;
+    }
+    llmRequest.model = agent.canonicalModel.model;
+    llmRequest.config = { ...(_a = agent.generateContentConfig) != null ? _a : {} };
+    if (agent.outputSchema) {
+      setOutputSchema(llmRequest, agent.outputSchema);
+    }
+    if (invocationContext.runConfig) {
+      llmRequest.liveConnectConfig.responseModalities = invocationContext.runConfig.responseModalities;
+      llmRequest.liveConnectConfig.speechConfig = invocationContext.runConfig.speechConfig;
+      llmRequest.liveConnectConfig.outputAudioTranscription = invocationContext.runConfig.outputAudioTranscription;
+      llmRequest.liveConnectConfig.inputAudioTranscription = invocationContext.runConfig.inputAudioTranscription;
+      llmRequest.liveConnectConfig.realtimeInputConfig = invocationContext.runConfig.realtimeInputConfig;
+      llmRequest.liveConnectConfig.enableAffectiveDialog = invocationContext.runConfig.enableAffectiveDialog;
+      llmRequest.liveConnectConfig.proactivity = invocationContext.runConfig.proactivity;
+    }
+  }
+}
+const BASIC_LLM_REQUEST_PROCESSOR = new BasicLlmRequestProcessor();
+class IdentityLlmRequestProcessor extends BaseLlmRequestProcessor {
+  async *runAsync(invocationContext, llmRequest) {
+    const agent = invocationContext.agent;
+    const si = [`You are an agent. Your internal name is "${agent.name}".`];
+    if (agent.description) {
+      si.push(`The description about you is "${agent.description}"`);
+    }
+    appendInstructions(llmRequest, si);
+  }
+}
+const IDENTITY_LLM_REQUEST_PROCESSOR = new IdentityLlmRequestProcessor();
+class InstructionsLlmRequestProcessor extends BaseLlmRequestProcessor {
+  /**
+   * Handles instructions and global instructions for LLM flow.
+   */
+  async *runAsync(invocationContext, llmRequest) {
+    const agent = invocationContext.agent;
+    if (!(agent instanceof LlmAgent) || !(agent.rootAgent instanceof LlmAgent)) {
+      return;
+    }
+    const rootAgent = agent.rootAgent;
+    if (rootAgent instanceof LlmAgent && rootAgent.globalInstruction) {
+      const { instruction, requireStateInjection } = await rootAgent.canonicalGlobalInstruction(
+        new ReadonlyContext(invocationContext)
+      );
+      let instructionWithState = instruction;
+      if (requireStateInjection) {
+        instructionWithState = await injectSessionState(
+          instruction,
+          new ReadonlyContext(invocationContext)
+        );
+      }
+      appendInstructions(llmRequest, [instructionWithState]);
+    }
+    if (agent.instruction) {
+      const { instruction, requireStateInjection } = await agent.canonicalInstruction(
+        new ReadonlyContext(invocationContext)
+      );
+      let instructionWithState = instruction;
+      if (requireStateInjection) {
+        instructionWithState = await injectSessionState(
+          instruction,
+          new ReadonlyContext(invocationContext)
+        );
+      }
+      appendInstructions(llmRequest, [instructionWithState]);
+    }
+  }
+}
+const INSTRUCTIONS_LLM_REQUEST_PROCESSOR = new InstructionsLlmRequestProcessor();
+class ContentRequestProcessor {
+  async *runAsync(invocationContext, llmRequest) {
+    const agent = invocationContext.agent;
+    if (!agent || !(agent instanceof LlmAgent)) {
+      return;
+    }
+    if (agent.includeContents === "default") {
+      llmRequest.contents = getContents(
+        invocationContext.session.events,
+        agent.name,
+        invocationContext.branch
+      );
+    } else {
+      llmRequest.contents = getCurrentTurnContents(
+        invocationContext.session.events,
+        agent.name,
+        invocationContext.branch
+      );
+    }
+    return;
+  }
+}
+const CONTENT_REQUEST_PROCESSOR = new ContentRequestProcessor();
+class AgentTransferLlmRequestProcessor extends BaseLlmRequestProcessor {
+  constructor() {
+    super(...arguments);
+    this.toolName = "transfer_to_agent";
+    this.tool = new FunctionTool({
+      name: this.toolName,
+      description: "Transfer the question to another agent. This tool hands off control to another agent when it is more suitable to answer the user question according to the agent description.",
+      parameters: z.object({
+        agentName: z.string().describe("the agent name to transfer to.")
+      }),
+      execute: function(args, toolContext) {
+        if (!toolContext) {
+          throw new Error("toolContext is required.");
+        }
+        toolContext.actions.transferToAgent = args.agentName;
+        return "Transfer queued";
+      }
+    });
+  }
+  async *runAsync(invocationContext, llmRequest) {
+    if (!(invocationContext.agent instanceof LlmAgent)) {
+      return;
+    }
+    const transferTargets = this.getTransferTargets(invocationContext.agent);
+    if (!transferTargets.length) {
+      return;
+    }
+    appendInstructions(llmRequest, [
+      this.buildTargetAgentsInstructions(
+        invocationContext.agent,
+        transferTargets
+      )
+    ]);
+    const toolContext = new ToolContext({ invocationContext });
+    await this.tool.processLlmRequest({ toolContext, llmRequest });
+  }
+  buildTargetAgentsInfo(targetAgent) {
+    return `
+Agent name: ${targetAgent.name}
+Agent description: ${targetAgent.description}
+`;
+  }
+  buildTargetAgentsInstructions(agent, targetAgents) {
+    let instructions = `
+You have a list of other agents to transfer to:
+
+${targetAgents.map(this.buildTargetAgentsInfo).join("\n")}
+
+If you are the best to answer the question according to your description, you
+can answer it.
+
+If another agent is better for answering the question according to its
+description, call \`${this.toolName}\` function to transfer the
+question to that agent. When transferring, do not generate any text other than
+the function call.
+`;
+    if (agent.parentAgent && !agent.disallowTransferToParent) {
+      instructions += `
+Your parent agent is ${agent.parentAgent.name}. If neither the other agents nor
+you are best for answering the question according to the descriptions, transfer
+to your parent agent.
+`;
+    }
+    return instructions;
+  }
+  getTransferTargets(agent) {
+    const targets = [];
+    targets.push(...agent.subAgents);
+    if (!agent.parentAgent || !(agent.parentAgent instanceof LlmAgent)) {
+      return targets;
+    }
+    if (!agent.disallowTransferToParent) {
+      targets.push(agent.parentAgent);
+    }
+    if (!agent.disallowTransferToPeers) {
+      targets.push(
+        ...agent.parentAgent.subAgents.filter(
+          (peerAgent) => peerAgent.name !== agent.name
+        )
+      );
+    }
+    return targets;
+  }
+}
+const AGENT_TRANSFER_LLM_REQUEST_PROCESSOR = new AgentTransferLlmRequestProcessor();
+class RequestConfirmationLlmRequestProcessor extends BaseLlmRequestProcessor {
+  /** Handles tool confirmation information to build the LLM request. */
+  async *runAsync(invocationContext, llmRequest) {
+    const agent = invocationContext.agent;
+    if (!(agent instanceof LlmAgent)) {
+      return;
+    }
+    const events = invocationContext.session.events;
+    if (!events || events.length === 0) {
+      return;
+    }
+    const requestConfirmationFunctionResponses = {};
+    let confirmationEventIndex = -1;
+    for (let i = events.length - 1; i >= 0; i--) {
+      const event = events[i];
+      if (event.author !== "user") {
+        continue;
+      }
+      const responses = getFunctionResponses(event);
+      if (!responses) {
+        continue;
+      }
+      let foundConfirmation = false;
+      for (const functionResponse of responses) {
+        if (functionResponse.name !== REQUEST_CONFIRMATION_FUNCTION_CALL_NAME) {
+          continue;
+        }
+        foundConfirmation = true;
+        let toolConfirmation = null;
+        if (functionResponse.response && Object.keys(functionResponse.response).length === 1 && "response" in functionResponse.response) {
+          toolConfirmation = JSON.parse(functionResponse.response["response"]);
+        } else if (functionResponse.response) {
+          toolConfirmation = new ToolConfirmation({
+            hint: functionResponse.response["hint"],
+            payload: functionResponse.response["payload"],
+            confirmed: functionResponse.response["confirmed"]
+          });
+        }
+        if (functionResponse.id && toolConfirmation) {
+          requestConfirmationFunctionResponses[functionResponse.id] = toolConfirmation;
+        }
+      }
+      if (foundConfirmation) {
+        confirmationEventIndex = i;
+        break;
+      }
+    }
+    if (Object.keys(requestConfirmationFunctionResponses).length === 0) {
+      return;
+    }
+    for (let i = confirmationEventIndex - 1; i >= 0; i--) {
+      const event = events[i];
+      const functionCalls = getFunctionCalls(event);
+      if (!functionCalls) {
+        continue;
+      }
+      const toolsToResumeWithConfirmation = {};
+      const toolsToResumeWithArgs = {};
+      for (const functionCall of functionCalls) {
+        if (!functionCall.id || !(functionCall.id in requestConfirmationFunctionResponses)) {
+          continue;
+        }
+        const args = functionCall.args;
+        if (!args || !("originalFunctionCall" in args)) {
+          continue;
+        }
+        const originalFunctionCall = args["originalFunctionCall"];
+        if (originalFunctionCall.id) {
+          toolsToResumeWithConfirmation[originalFunctionCall.id] = requestConfirmationFunctionResponses[functionCall.id];
+          toolsToResumeWithArgs[originalFunctionCall.id] = originalFunctionCall;
+        }
+      }
+      if (Object.keys(toolsToResumeWithConfirmation).length === 0) {
+        continue;
+      }
+      for (let j = events.length - 1; j > confirmationEventIndex; j--) {
+        const eventToCheck = events[j];
+        const functionResponses = getFunctionResponses(eventToCheck);
+        if (!functionResponses) {
+          continue;
+        }
+        for (const fr of functionResponses) {
+          if (fr.id && fr.id in toolsToResumeWithConfirmation) {
+            delete toolsToResumeWithConfirmation[fr.id];
+            delete toolsToResumeWithArgs[fr.id];
+          }
+        }
+        if (Object.keys(toolsToResumeWithConfirmation).length === 0) {
+          break;
+        }
+      }
+      if (Object.keys(toolsToResumeWithConfirmation).length === 0) {
+        continue;
+      }
+      const toolsList = await agent.canonicalTools(new ReadonlyContext(invocationContext));
+      const toolsDict = Object.fromEntries(toolsList.map((tool) => [tool.name, tool]));
+      const functionResponseEvent = await handleFunctionCallList({
+        invocationContext,
+        functionCalls: Object.values(toolsToResumeWithArgs),
+        toolsDict,
+        beforeToolCallbacks: agent.canonicalBeforeToolCallbacks,
+        afterToolCallbacks: agent.canonicalAfterToolCallbacks,
+        filters: new Set(Object.keys(toolsToResumeWithConfirmation)),
+        toolConfirmationDict: toolsToResumeWithConfirmation
+      });
+      if (functionResponseEvent) {
+        yield functionResponseEvent;
+      }
+      return;
+    }
+  }
+}
+const REQUEST_CONFIRMATION_LLM_REQUEST_PROCESSOR = new RequestConfirmationLlmRequestProcessor();
+class CodeExecutionRequestProcessor extends BaseLlmRequestProcessor {
+  async *runAsync(invocationContext, llmRequest) {
+    if (!(invocationContext.agent instanceof LlmAgent)) {
+      return;
+    }
+    if (!invocationContext.agent.codeExecutor) {
+      return;
+    }
+    for await (const event of runPreProcessor(invocationContext, llmRequest)) {
+      yield event;
+    }
+    if (!(invocationContext.agent.codeExecutor instanceof BaseCodeExecutor)) {
+      return;
+    }
+    for (const content of llmRequest.contents) {
+      const delimeters = invocationContext.agent.codeExecutor.codeBlockDelimiters.length ? invocationContext.agent.codeExecutor.codeBlockDelimiters[0] : ["", ""];
+      const codeExecutionParts = convertCodeExecutionParts(
+        content,
+        delimeters,
+        invocationContext.agent.codeExecutor.executionResultDelimiters
+      );
+    }
+  }
+}
+const DATA_FILE_UTIL_MAP = {
+  "text/csv": {
+    extension: ".csv",
+    loaderCodeTemplate: "pd.read_csv('{filename}')"
+  }
+};
+const DATA_FILE_HELPER_LIB = `
+import pandas as pd
+
+def explore_df(df: pd.DataFrame) -> None:
+  """Prints some information about a pandas DataFrame."""
+
+  with pd.option_context(
+      'display.max_columns', None, 'display.expand_frame_repr', False
+  ):
+    # Print the column names to never encounter KeyError when selecting one.
+    df_dtypes = df.dtypes
+
+    # Obtain information about data types and missing values.
+    df_nulls = (len(df) - df.isnull().sum()).apply(
+        lambda x: f'{x} / {df.shape[0]} non-null'
+    )
+
+    # Explore unique total values in columns using \`.unique()\`.
+    df_unique_count = df.apply(lambda x: len(x.unique()))
+
+    # Explore unique values in columns using \`.unique()\`.
+    df_unique = df.apply(lambda x: crop(str(list(x.unique()))))
+
+    df_info = pd.concat(
+        (
+            df_dtypes.rename('Dtype'),
+            df_nulls.rename('Non-Null Count'),
+            df_unique_count.rename('Unique Values Count'),
+            df_unique.rename('Unique Values'),
+        ),
+        axis=1,
+    )
+    df_info.index.name = 'Columns'
+    print(f"""Total rows: {df.shape[0]}
+Total columns: {df.shape[1]}
+
+{df_info}""")
+`;
+class CodeExecutionResponseProcessor {
+  /**
+   * Processes the LLM response asynchronously.
+   *
+   * @param invocationContext The invocation context
+   * @param llmResponse The LLM response to process
+   * @returns An async generator yielding events
+   */
+  async *runAsync(invocationContext, llmResponse) {
+    if (llmResponse.partial) {
+      return;
+    }
+    for await (const event of runPostProcessor(invocationContext, llmResponse)) {
+      yield event;
+    }
+  }
+}
+const responseProcessor = new CodeExecutionResponseProcessor();
+async function* runPreProcessor(invocationContext, llmRequest) {
+  const agent = invocationContext.agent;
+  if (!(agent instanceof LlmAgent)) {
+    return;
+  }
+  const codeExecutor = agent.codeExecutor;
+  if (!codeExecutor || !(codeExecutor instanceof BaseCodeExecutor)) {
+    return;
+  }
+  if (codeExecutor instanceof BuiltInCodeExecutor) {
+    codeExecutor.processLlmRequest(llmRequest);
+    return;
+  }
+  if (!codeExecutor.optimizeDataFile) {
+    return;
+  }
+  const codeExecutorContext = new CodeExecutorContext(new State(invocationContext.session.state));
+  if (codeExecutorContext.getErrorCount(invocationContext.invocationId) >= codeExecutor.errorRetryAttempts) {
+    return;
+  }
+  const allInputFiles = extractAndReplaceInlineFiles(codeExecutorContext, llmRequest);
+  const processedFileNames = new Set(codeExecutorContext.getProcessedFileNames());
+  const filesToProcess = allInputFiles.filter((f) => !processedFileNames.has(f.name));
+  for (const file of filesToProcess) {
+    const codeStr = getDataFilePreprocessingCode(file);
+    if (!codeStr) {
+      return;
+    }
+    const codeContent = {
+      role: "model",
+      parts: [
+        { text: `Processing input file: \`${file.name}\`` },
+        buildExecutableCodePart(codeStr)
+      ]
+    };
+    llmRequest.contents.push(deepClone(codeContent));
+    yield createEvent({
+      invocationId: invocationContext.invocationId,
+      author: agent.name,
+      branch: invocationContext.branch,
+      content: codeContent
+    });
+    const executionId = getOrSetExecutionId(invocationContext, codeExecutorContext);
+    const codeExecutionResult = await codeExecutor.executeCode({
+      invocationContext,
+      codeExecutionInput: {
+        code: codeStr,
+        inputFiles: [file],
+        executionId
+      }
+    });
+    codeExecutorContext.updateCodeExecutionResult({
+      invocationId: invocationContext.invocationId,
+      code: codeStr,
+      resultStdout: codeExecutionResult.stdout,
+      resultStderr: codeExecutionResult.stderr
+    });
+    codeExecutorContext.addProcessedFileNames([file.name]);
+    const executionResultEvent = await postProcessCodeExecutionResult(
+      invocationContext,
+      codeExecutorContext,
+      codeExecutionResult
+    );
+    yield executionResultEvent;
+    llmRequest.contents.push(deepClone(executionResultEvent.content));
+  }
+}
+async function* runPostProcessor(invocationContext, llmResponse) {
+  const agent = invocationContext.agent;
+  if (!(agent instanceof LlmAgent)) {
+    return;
+  }
+  const codeExecutor = agent.codeExecutor;
+  if (!codeExecutor || !(codeExecutor instanceof BaseCodeExecutor)) {
+    return;
+  }
+  if (!llmResponse || !llmResponse.content) {
+    return;
+  }
+  if (codeExecutor instanceof BuiltInCodeExecutor) {
+    return;
+  }
+  const codeExecutorContext = new CodeExecutorContext(new State(invocationContext.session.state));
+  if (codeExecutorContext.getErrorCount(invocationContext.invocationId) >= codeExecutor.errorRetryAttempts) {
+    return;
+  }
+  const responseContent = llmResponse.content;
+  const codeStr = extractCodeAndTruncateContent(
+    responseContent,
+    codeExecutor.codeBlockDelimiters
+  );
+  if (!codeStr) {
+    return;
+  }
+  yield createEvent({
+    invocationId: invocationContext.invocationId,
+    author: agent.name,
+    branch: invocationContext.branch,
+    content: responseContent
+  });
+  const executionId = getOrSetExecutionId(invocationContext, codeExecutorContext);
+  const codeExecutionResult = await codeExecutor.executeCode({
+    invocationContext,
+    codeExecutionInput: {
+      code: codeStr,
+      inputFiles: codeExecutorContext.getInputFiles(),
+      executionId
+    }
+  });
+  codeExecutorContext.updateCodeExecutionResult({
+    invocationId: invocationContext.invocationId,
+    code: codeStr,
+    resultStdout: codeExecutionResult.stdout,
+    resultStderr: codeExecutionResult.stderr
+  });
+  yield await postProcessCodeExecutionResult(
+    invocationContext,
+    codeExecutorContext,
+    codeExecutionResult
+  );
+  llmResponse.content = null;
+}
+function extractAndReplaceInlineFiles(codeExecutorContext, llmRequest) {
+  var _a;
+  const allInputFiles = codeExecutorContext.getInputFiles();
+  const savedFileNames = new Set(allInputFiles.map((f) => f.name));
+  for (let i = 0; i < llmRequest.contents.length; i++) {
+    const content = llmRequest.contents[i];
+    if (content.role !== "user" || !content.parts) {
+      continue;
+    }
+    for (let j = 0; j < content.parts.length; j++) {
+      const part = content.parts[j];
+      const mimeType = (_a = part.inlineData) == null ? void 0 : _a.mimeType;
+      if (!mimeType || !part.inlineData || !DATA_FILE_UTIL_MAP[mimeType]) {
+        continue;
+      }
+      const fileName = `data_${i + 1}_${j + 1}${DATA_FILE_UTIL_MAP[mimeType].extension}`;
+      part.text = `
+Available file: \`${fileName}\`
+`;
+      const file = {
+        name: fileName,
+        content: base64Decode(part.inlineData.data),
+        mimeType
+      };
+      if (!savedFileNames.has(fileName)) {
+        codeExecutorContext.addInputFiles([file]);
+        allInputFiles.push(file);
+      }
+    }
+  }
+  return allInputFiles;
+}
+function getOrSetExecutionId(invocationContext, codeExecutorContext) {
+  var _a;
+  const agent = invocationContext.agent;
+  if (!(agent instanceof LlmAgent) || !((_a = agent.codeExecutor) == null ? void 0 : _a.stateful)) {
+    return void 0;
+  }
+  let executionId = codeExecutorContext.getExecutionId();
+  if (!executionId) {
+    executionId = invocationContext.session.id;
+    codeExecutorContext.setExecutionId(executionId);
+  }
+  return executionId;
+}
+async function postProcessCodeExecutionResult(invocationContext, codeExecutorContext, codeExecutionResult) {
+  if (!invocationContext.artifactService) {
+    throw new Error("Artifact service is not initialized.");
+  }
+  const resultContent = {
+    role: "model",
+    parts: [buildCodeExecutionResultPart(codeExecutionResult)]
+  };
+  const eventActions = createEventActions({ stateDelta: codeExecutorContext.getStateDelta() });
+  if (codeExecutionResult.stderr) {
+    codeExecutorContext.incrementErrorCount(invocationContext.invocationId);
+  } else {
+    codeExecutorContext.resetErrorCount(invocationContext.invocationId);
+  }
+  for (const outputFile of codeExecutionResult.outputFiles) {
+    const version = await invocationContext.artifactService.saveArtifact({
+      appName: invocationContext.appName || "",
+      userId: invocationContext.userId || "",
+      sessionId: invocationContext.session.id,
+      filename: outputFile.name,
+      artifact: {
+        inlineData: { data: outputFile.content, mimeType: outputFile.mimeType }
+      }
+    });
+    eventActions.artifactDelta[outputFile.name] = version;
+  }
+  return createEvent({
+    invocationId: invocationContext.invocationId,
+    author: invocationContext.agent.name,
+    branch: invocationContext.branch,
+    content: resultContent,
+    actions: eventActions
+  });
+}
+function getDataFilePreprocessingCode(file) {
+  function getNormalizedFileName(fileName) {
+    const [varName2] = fileName.split(".");
+    let normalizedName = varName2.replace(/[^a-zA-Z0-9_]/g, "_");
+    if (/^\d/.test(normalizedName)) {
+      normalizedName = "_" + normalizedName;
+    }
+    return normalizedName;
+  }
+  if (!DATA_FILE_UTIL_MAP[file.mimeType]) {
+    return void 0;
+  }
+  const varName = getNormalizedFileName(file.name);
+  const loaderCode = DATA_FILE_UTIL_MAP[file.mimeType].loaderCodeTemplate.replace(
+    "{filename}",
+    file.name
+  );
+  return `
+${DATA_FILE_HELPER_LIB}
+
+# Load the dataframe.
+${varName} = ${loaderCode}
+
+# Use \`explore_df\` to guide my analysis.
+explore_df(${varName})
+`;
+}
+const CODE_EXECUTION_REQUEST_PROCESSOR = new CodeExecutionRequestProcessor();
+const _LlmAgent = class _LlmAgent extends BaseAgent {
+  constructor(config) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i;
+    super(config);
+    this.model = config.model;
+    this.instruction = (_a = config.instruction) != null ? _a : "";
+    this.globalInstruction = (_b = config.globalInstruction) != null ? _b : "";
+    this.tools = (_c = config.tools) != null ? _c : [];
+    this.generateContentConfig = config.generateContentConfig;
+    this.disallowTransferToParent = (_d = config.disallowTransferToParent) != null ? _d : false;
+    this.disallowTransferToPeers = (_e = config.disallowTransferToPeers) != null ? _e : false;
+    this.includeContents = (_f = config.includeContents) != null ? _f : "default";
+    this.inputSchema = config.inputSchema;
+    this.outputSchema = config.outputSchema;
+    this.outputKey = config.outputKey;
+    this.beforeModelCallback = config.beforeModelCallback;
+    this.afterModelCallback = config.afterModelCallback;
+    this.beforeToolCallback = config.beforeToolCallback;
+    this.afterToolCallback = config.afterToolCallback;
+    this.codeExecutor = config.codeExecutor;
+    this.requestProcessors = (_g = config.requestProcessors) != null ? _g : [
+      BASIC_LLM_REQUEST_PROCESSOR,
+      IDENTITY_LLM_REQUEST_PROCESSOR,
+      INSTRUCTIONS_LLM_REQUEST_PROCESSOR,
+      REQUEST_CONFIRMATION_LLM_REQUEST_PROCESSOR,
+      CONTENT_REQUEST_PROCESSOR,
+      CODE_EXECUTION_REQUEST_PROCESSOR
+    ];
+    this.responseProcessors = (_h = config.responseProcessors) != null ? _h : [];
+    const agentTransferDisabled = this.disallowTransferToParent && this.disallowTransferToPeers && !((_i = this.subAgents) == null ? void 0 : _i.length);
+    if (!agentTransferDisabled) {
+      this.requestProcessors.push(AGENT_TRANSFER_LLM_REQUEST_PROCESSOR);
+    }
+    if (config.generateContentConfig) {
+      if (config.generateContentConfig.tools) {
+        throw new Error("All tools must be set via LlmAgent.tools.");
+      }
+      if (config.generateContentConfig.systemInstruction) {
+        throw new Error(
+          "System instruction must be set via LlmAgent.instruction."
+        );
+      }
+      if (config.generateContentConfig.responseSchema) {
+        throw new Error(
+          "Response schema must be set via LlmAgent.output_schema."
+        );
+      }
+    } else {
+      this.generateContentConfig = {};
+    }
+    if (this.outputSchema) {
+      if (!this.disallowTransferToParent || !this.disallowTransferToPeers) {
+        logger.warn(
+          `Invalid config for agent ${this.name}: outputSchema cannot co-exist with agent transfer configurations. Setting disallowTransferToParent=true, disallowTransferToPeers=true`
+        );
+        this.disallowTransferToParent = true;
+        this.disallowTransferToPeers = true;
+      }
+      if (this.subAgents && this.subAgents.length > 0) {
+        throw new Error(
+          `Invalid config for agent ${this.name}: if outputSchema is set, subAgents must be empty to disable agent transfer.`
+        );
+      }
+      if (this.tools && this.tools.length > 0) {
+        throw new Error(
+          `Invalid config for agent ${this.name}: if outputSchema is set, tools must be empty`
+        );
+      }
+    }
+  }
+  /**
+   * The resolved BaseLlm instance.
+   *
+   * When not set, the agent will inherit the model from its ancestor.
+   */
+  get canonicalModel() {
+    if (isBaseLlm(this.model)) {
+      return this.model;
+    }
+    if (typeof this.model === "string" && this.model) {
+      return LLMRegistry.newLlm(this.model);
+    }
+    let ancestorAgent = this.parentAgent;
+    while (ancestorAgent) {
+      if (ancestorAgent instanceof _LlmAgent) {
+        return ancestorAgent.canonicalModel;
+      }
+      ancestorAgent = ancestorAgent.parentAgent;
+    }
+    throw new Error(`No model found for ${this.name}.`);
+  }
+  /**
+   * The resolved self.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 self.instruction field.
+   */
+  async canonicalInstruction(context) {
+    if (typeof this.instruction === "string") {
+      return { instruction: this.instruction, requireStateInjection: true };
+    }
+    return {
+      instruction: await this.instruction(context),
+      requireStateInjection: false
+    };
+  }
+  /**
+   * The resolved self.instruction 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 self.global_instruction field.
+   */
+  async canonicalGlobalInstruction(context) {
+    if (typeof this.globalInstruction === "string") {
+      return { instruction: this.globalInstruction, requireStateInjection: true };
+    }
+    return {
+      instruction: await this.globalInstruction(context),
+      requireStateInjection: false
+    };
+  }
+  /**
+   * The resolved self.tools field as a list of BaseTool based on the context.
+   *
+   * This method is only for use by Agent Development Kit.
+   */
+  async canonicalTools(context) {
+    const resolvedTools = [];
+    for (const toolUnion of this.tools) {
+      const tools = await convertToolUnionToTools(toolUnion, context);
+      resolvedTools.push(...tools);
+    }
+    return resolvedTools;
+  }
+  /**
+   * 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.
+   */
+  static normalizeCallbackArray(callback) {
+    if (!callback) {
+      return [];
+    }
+    if (Array.isArray(callback)) {
+      return callback;
+    }
+    return [callback];
+  }
+  /**
+   * The resolved self.before_model_callback field as a list of
+   * SingleBeforeModelCallback.
+   *
+   * This method is only for use by Agent Development Kit.
+   */
+  get canonicalBeforeModelCallbacks() {
+    return _LlmAgent.normalizeCallbackArray(this.beforeModelCallback);
+  }
+  /**
+   * The resolved self.after_model_callback field as a list of
+   * SingleAfterModelCallback.
+   *
+   * This method is only for use by Agent Development Kit.
+   */
+  get canonicalAfterModelCallbacks() {
+    return _LlmAgent.normalizeCallbackArray(this.afterModelCallback);
+  }
+  /**
+   * The resolved self.before_tool_callback field as a list of
+   * BeforeToolCallback.
+   *
+   * This method is only for use by Agent Development Kit.
+   */
+  get canonicalBeforeToolCallbacks() {
+    return _LlmAgent.normalizeCallbackArray(this.beforeToolCallback);
+  }
+  /**
+   * The resolved self.after_tool_callback field as a list of AfterToolCallback.
+   *
+   * This method is only for use by Agent Development Kit.
+   */
+  get canonicalAfterToolCallbacks() {
+    return _LlmAgent.normalizeCallbackArray(this.afterToolCallback);
+  }
+  /**
+   * 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.
+   */
+  maybeSaveOutputToState(event) {
+    var _a, _b;
+    if (event.author !== this.name) {
+      logger.debug(
+        `Skipping output save for agent ${this.name}: event authored by ${event.author}`
+      );
+      return;
+    }
+    if (!this.outputKey) {
+      logger.debug(
+        `Skipping output save for agent ${this.name}: outputKey is not set`
+      );
+      return;
+    }
+    if (!isFinalResponse(event)) {
+      logger.debug(
+        `Skipping output save for agent ${this.name}: event is not a final response`
+      );
+      return;
+    }
+    if (!((_b = (_a = event.content) == null ? void 0 : _a.parts) == null ? void 0 : _b.length)) {
+      logger.debug(
+        `Skipping output save for agent ${this.name}: event content is empty`
+      );
+      return;
+    }
+    const resultStr = event.content.parts.map((part) => part.text ? part.text : "").join("");
+    let result = resultStr;
+    if (this.outputSchema) {
+      if (!resultStr.trim()) {
+        return;
+      }
+      try {
+        result = JSON.parse(resultStr);
+      } catch (e) {
+        logger.error(`Error parsing output for agent ${this.name}`, e);
+      }
+    }
+    event.actions.stateDelta[this.outputKey] = result;
+  }
+  async *runAsyncImpl(context) {
+    while (true) {
+      let lastEvent = void 0;
+      for await (const event of this.runOneStepAsync(context)) {
+        lastEvent = event;
+        this.maybeSaveOutputToState(event);
+        yield event;
+      }
+      if (!lastEvent || isFinalResponse(lastEvent)) {
+        break;
+      }
+      if (lastEvent.partial) {
+        logger.warn("The last event is partial, which is not expected.");
+        break;
+      }
+    }
+  }
+  async *runLiveImpl(context) {
+    for await (const event of this.runLiveFlow(context)) {
+      this.maybeSaveOutputToState(event);
+      yield event;
+    }
+    if (context.endInvocation) {
+      return;
+    }
+  }
+  // --------------------------------------------------------------------------
+  // #START LlmFlow Logic
+  // --------------------------------------------------------------------------
+  async *runLiveFlow(invocationContext) {
+    await Promise.resolve();
+    throw new Error("LlmAgent.runLiveFlow not implemented");
+  }
+  async *runOneStepAsync(invocationContext) {
+    const llmRequest = {
+      contents: [],
+      toolsDict: {},
+      liveConnectConfig: {}
+    };
+    for (const processor of this.requestProcessors) {
+      for await (const event of processor.runAsync(invocationContext, llmRequest)) {
+        yield event;
+      }
+    }
+    for (const toolUnion of this.tools) {
+      const toolContext = new ToolContext({ invocationContext });
+      const tools = await convertToolUnionToTools(
+        toolUnion,
+        new ReadonlyContext(invocationContext)
+      );
+      for (const tool of tools) {
+        await tool.processLlmRequest({ toolContext, llmRequest });
+      }
+    }
+    if (invocationContext.endInvocation) {
+      return;
+    }
+    const modelResponseEvent = createEvent({
+      invocationId: invocationContext.invocationId,
+      author: this.name,
+      branch: invocationContext.branch
+    });
+    for await (const llmResponse of this.callLlmAsync(
+      invocationContext,
+      llmRequest,
+      modelResponseEvent
+    )) {
+      try {
+        for await (const event of this.postprocess(
+          invocationContext,
+          llmRequest,
+          llmResponse,
+          modelResponseEvent
+        )) {
+          modelResponseEvent.id = createNewEventId();
+          modelResponseEvent.timestamp = (/* @__PURE__ */ new Date()).getTime();
+          yield event;
+        }
+      } catch (postprocessError) {
+        const errMsg = postprocessError instanceof Error ? postprocessError.message : String(postprocessError);
+        logger.error(`Postprocess error: ${errMsg}`);
+        yield createEvent({
+          invocationId: invocationContext.invocationId,
+          author: this.name,
+          branch: invocationContext.branch,
+          errorCode: "POSTPROCESS_ERROR",
+          errorMessage: errMsg
+        });
+      }
+    }
+  }
+  async *postprocess(invocationContext, llmRequest, llmResponse, modelResponseEvent) {
+    var _a, _b;
+    for (const processor of this.responseProcessors) {
+      for await (const event of processor.runAsync(invocationContext, llmResponse)) {
+        yield event;
+      }
+    }
+    if (!llmResponse.content && !llmResponse.errorCode && !llmResponse.interrupted) {
+      return;
+    }
+    const mergedEvent = createEvent({
+      ...modelResponseEvent,
+      ...llmResponse
+    });
+    if (mergedEvent.content) {
+      const functionCalls = getFunctionCalls(mergedEvent);
+      if (functionCalls == null ? void 0 : functionCalls.length) {
+        populateClientFunctionCallId(mergedEvent);
+        mergedEvent.longRunningToolIds = Array.from(
+          getLongRunningFunctionCalls(functionCalls, llmRequest.toolsDict)
+        );
+        const hasSignature = (_a = mergedEvent.content.parts) == null ? void 0 : _a.some(
+          (p) => p.thoughtSignature
+        );
+        if (!hasSignature) {
+          logger.warn(
+            `[postprocess] Function calls (${functionCalls.length}) without thoughtSignature`
+          );
+        }
+      }
+    }
+    yield mergedEvent;
+    if (!((_b = getFunctionCalls(mergedEvent)) == null ? void 0 : _b.length)) {
+      return;
+    }
+    const functionResponseEvent = await handleFunctionCallsAsync({
+      invocationContext,
+      functionCallEvent: mergedEvent,
+      toolsDict: llmRequest.toolsDict,
+      beforeToolCallbacks: this.canonicalBeforeToolCallbacks,
+      afterToolCallbacks: this.canonicalAfterToolCallbacks
+    });
+    if (!functionResponseEvent) {
+      return;
+    }
+    const authEvent = generateAuthEvent(invocationContext, functionResponseEvent);
+    if (authEvent) {
+      yield authEvent;
+    }
+    const toolConfirmationEvent = generateRequestConfirmationEvent({
+      invocationContext,
+      functionCallEvent: mergedEvent,
+      functionResponseEvent
+    });
+    if (toolConfirmationEvent) {
+      yield toolConfirmationEvent;
+    }
+    yield functionResponseEvent;
+    const nextAgentName = functionResponseEvent.actions.transferToAgent;
+    if (nextAgentName) {
+      const nextAgent = this.getAgentByName(invocationContext, nextAgentName);
+      for await (const event of nextAgent.runAsync(invocationContext)) {
+        yield event;
+      }
+    }
+  }
+  /**
+   * 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.
+   */
+  getAgentByName(invocationContext, agentName) {
+    const rootAgent = invocationContext.agent.rootAgent;
+    const agentToRun = rootAgent.findAgent(agentName);
+    if (!agentToRun) {
+      throw new Error(`Agent ${agentName} not found in the agent tree.`);
+    }
+    return agentToRun;
+  }
+  async *callLlmAsync(invocationContext, llmRequest, modelResponseEvent) {
+    var _a, _b, _c, _d, _e;
+    const beforeModelResponse = await this.handleBeforeModelCallback(
+      invocationContext,
+      llmRequest,
+      modelResponseEvent
+    );
+    if (beforeModelResponse) {
+      yield beforeModelResponse;
+      return;
+    }
+    (_a = llmRequest.config) != null ? _a : llmRequest.config = {};
+    (_c = (_b = llmRequest.config).labels) != null ? _c : _b.labels = {};
+    if (!llmRequest.config.labels[ADK_AGENT_NAME_LABEL_KEY]) {
+      llmRequest.config.labels[ADK_AGENT_NAME_LABEL_KEY] = this.name;
+    }
+    const llm = this.canonicalModel;
+    if ((_d = invocationContext.runConfig) == null ? void 0 : _d.supportCfc) {
+      throw new Error("CFC is not yet supported in callLlmAsync");
+    } else {
+      invocationContext.incrementLlmCallCount();
+      const isStreaming = ((_e = invocationContext.runConfig) == null ? void 0 : _e.streamingMode) === StreamingMode.SSE;
+      const maxRetries = _LlmAgent.LLM_TRANSIENT_ERROR_MAX_RETRIES;
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        if (attempt > 0) {
+          const delay = Math.min(
+            _LlmAgent.LLM_TRANSIENT_ERROR_BASE_DELAY_MS * Math.pow(2, attempt - 1),
+            _LlmAgent.LLM_TRANSIENT_ERROR_MAX_DELAY_MS
+          );
+          logger.warn(
+            `[callLlmAsync] Retrying LLM call after transient error (attempt ${attempt + 1}/${maxRetries + 1}), waiting ${delay}ms`
+          );
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+        const responsesGenerator = llm.generateContentAsync(
+          llmRequest,
+          isStreaming
+        );
+        let shouldRetry = false;
+        let contentYielded = false;
+        for await (const llmResponse of this.runAndHandleError(
+          responsesGenerator,
+          invocationContext,
+          llmRequest,
+          modelResponseEvent
+        )) {
+          if (llmResponse.content) {
+            contentYielded = true;
+          }
+          if (llmResponse.errorCode && _LlmAgent.LLM_RETRYABLE_ERROR_CODES.has(llmResponse.errorCode) && !contentYielded && attempt < maxRetries) {
+            shouldRetry = true;
+            logger.warn(
+              `[callLlmAsync] Transient LLM error: ${llmResponse.errorCode}, usage: ${JSON.stringify(llmResponse.usageMetadata)}`
+            );
+            break;
+          }
+          const alteredLlmResponse = await this.handleAfterModelCallback(
+            invocationContext,
+            llmResponse,
+            modelResponseEvent
+          );
+          yield alteredLlmResponse != null ? alteredLlmResponse : llmResponse;
+        }
+        if (!shouldRetry) {
+          return;
+        }
+      }
+    }
+  }
+  async handleBeforeModelCallback(invocationContext, llmRequest, modelResponseEvent) {
+    const callbackContext = new CallbackContext(
+      { invocationContext, eventActions: modelResponseEvent.actions }
+    );
+    const beforeModelCallbackResponse = await invocationContext.pluginManager.runBeforeModelCallback(
+      { callbackContext, llmRequest }
+    );
+    if (beforeModelCallbackResponse) {
+      return beforeModelCallbackResponse;
+    }
+    for (const callback of this.canonicalBeforeModelCallbacks) {
+      const callbackResponse = await callback({ context: callbackContext, request: llmRequest });
+      if (callbackResponse) {
+        return callbackResponse;
+      }
+    }
+    return void 0;
+  }
+  async handleAfterModelCallback(invocationContext, llmResponse, modelResponseEvent) {
+    const callbackContext = new CallbackContext(
+      { invocationContext, eventActions: modelResponseEvent.actions }
+    );
+    const afterModelCallbackResponse = await invocationContext.pluginManager.runAfterModelCallback(
+      { callbackContext, llmResponse }
+    );
+    if (afterModelCallbackResponse) {
+      return afterModelCallbackResponse;
+    }
+    for (const callback of this.canonicalAfterModelCallbacks) {
+      const callbackResponse = await callback({ context: callbackContext, response: llmResponse });
+      if (callbackResponse) {
+        return callbackResponse;
+      }
+    }
+    return void 0;
+  }
+  async *runAndHandleError(responseGenerator, invocationContext, llmRequest, modelResponseEvent) {
+    try {
+      for await (const response of responseGenerator) {
+        yield response;
+      }
+    } catch (modelError) {
+      const callbackContext = new CallbackContext(
+        { invocationContext, eventActions: modelResponseEvent.actions }
+      );
+      if (modelError instanceof Error) {
+        const onModelErrorCallbackResponse = await invocationContext.pluginManager.runOnModelErrorCallback({
+          callbackContext,
+          llmRequest,
+          error: modelError
+        });
+        if (onModelErrorCallbackResponse) {
+          yield onModelErrorCallbackResponse;
+        } else {
+          try {
+            const errorResponse = JSON.parse(modelError.message);
+            yield {
+              errorCode: String(errorResponse.error.code),
+              errorMessage: errorResponse.error.message
+            };
+          } catch {
+            logger.warn(
+              `LLM error message is not valid JSON, using raw message: ${modelError.message.substring(0, 200)}`
+            );
+            yield {
+              errorCode: "UNKNOWN_ERROR",
+              errorMessage: modelError.message
+            };
+          }
+        }
+      } else {
+        logger.error("Unknown error during response generation", modelError);
+        throw modelError;
+      }
+    }
+  }
+  // --------------------------------------------------------------------------
+  // #END LlmFlow Logic
+  // --------------------------------------------------------------------------
+  // TODO - b/425992518: omitted Py LlmAgent features.
+  // - code_executor
+  // - configurable agents by yaml config
+};
+_LlmAgent.LLM_TRANSIENT_ERROR_MAX_RETRIES = 2;
+_LlmAgent.LLM_TRANSIENT_ERROR_BASE_DELAY_MS = 1e3;
+_LlmAgent.LLM_TRANSIENT_ERROR_MAX_DELAY_MS = 4e3;
+_LlmAgent.LLM_RETRYABLE_ERROR_CODES = /* @__PURE__ */ new Set([
+  "UNKNOWN_ERROR"
+]);
+let LlmAgent = _LlmAgent;
+export {
+  LlmAgent,
+  REQUEST_CONFIRMATION_LLM_REQUEST_PROCESSOR,
+  responseProcessor
+};