@google/adk 0.4.0 → 0.5.0

package/dist/esm/agents/processors/agent_transfer_llm_request_processor.js

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from "zod";
+import { appendInstructions } from "../../models/llm_request.js";
+import { FunctionTool } from "../../tools/function_tool.js";
+import { Context } from "../context.js";
+import { isLlmAgent } from "../llm_agent.js";
+import { BaseLlmRequestProcessor } from "./base_llm_processor.js";
+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";
+      }
+    });
+  }
+  // eslint-disable-next-line require-yield
+  async *runAsync(invocationContext, llmRequest) {
+    if (!isLlmAgent(invocationContext.agent)) {
+      return;
+    }
+    const transferTargets = this.getTransferTargets(invocationContext.agent);
+    if (!transferTargets.length) {
+      return;
+    }
+    appendInstructions(llmRequest, [
+      this.buildTargetAgentsInstructions(
+        invocationContext.agent,
+        transferTargets
+      )
+    ]);
+    const toolContext = new Context({ 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((t) => this.buildTargetAgentsInfo(t)).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 || !isLlmAgent(agent.parentAgent)) {
+      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();
+export {
+  AGENT_TRANSFER_LLM_REQUEST_PROCESSOR,
+  AgentTransferLlmRequestProcessor
+};

package/dist/esm/agents/processors/basic_llm_request_processor.js

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { setOutputSchema } from "../../models/llm_request.js";
+import { isLlmAgent } from "../llm_agent.js";
+import { BaseLlmRequestProcessor } from "./base_llm_processor.js";
+class BasicLlmRequestProcessor extends BaseLlmRequestProcessor {
+  // eslint-disable-next-line require-yield
+  async *runAsync(invocationContext, llmRequest) {
+    var _a;
+    const agent = invocationContext.agent;
+    if (!isLlmAgent(agent)) {
+      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();
+export {
+  BASIC_LLM_REQUEST_PROCESSOR,
+  BasicLlmRequestProcessor
+};

package/dist/esm/agents/processors/code_execution_request_processor.js

@@ -0,0 +1,363 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { cloneDeep } from "lodash-es";
+import { isBaseCodeExecutor } from "../../code_executors/base_code_executor.js";
+import { isBuiltInCodeExecutor } 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 } from "../../events/event.js";
+import { createEventActions } from "../../events/event_actions.js";
+import { State } from "../../sessions/state.js";
+import { base64Decode } from "../../utils/env_aware_utils.js";
+import { isLlmAgent } from "../llm_agent.js";
+import {
+  BaseLlmRequestProcessor
+} from "./base_llm_processor.js";
+class CodeExecutionRequestProcessor extends BaseLlmRequestProcessor {
+  async *runAsync(invocationContext, llmRequest) {
+    if (!isLlmAgent(invocationContext.agent)) {
+      return;
+    }
+    if (!invocationContext.agent.codeExecutor) {
+      return;
+    }
+    for await (const event of runPreProcessor(invocationContext, llmRequest)) {
+      yield event;
+    }
+    if (!isBaseCodeExecutor(invocationContext.agent.codeExecutor)) {
+      return;
+    }
+    for (const content of llmRequest.contents) {
+      const delimeters = invocationContext.agent.codeExecutor.codeBlockDelimiters.length ? invocationContext.agent.codeExecutor.codeBlockDelimiters[0] : ["", ""];
+      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 (!isLlmAgent(agent)) {
+    return;
+  }
+  const codeExecutor = agent.codeExecutor;
+  if (!codeExecutor || !isBaseCodeExecutor(codeExecutor)) {
+    return;
+  }
+  if (isBuiltInCodeExecutor(codeExecutor)) {
+    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(cloneDeep(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(cloneDeep(executionResultEvent.content));
+  }
+}
+async function* runPostProcessor(invocationContext, llmResponse) {
+  const agent = invocationContext.agent;
+  if (!isLlmAgent(agent)) {
+    return;
+  }
+  const codeExecutor = agent.codeExecutor;
+  if (!codeExecutor || !isBaseCodeExecutor(codeExecutor)) {
+    return;
+  }
+  if (!llmResponse || !llmResponse.content) {
+    return;
+  }
+  if (isBuiltInCodeExecutor(codeExecutor)) {
+    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 = void 0;
+}
+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 (!isLlmAgent(agent) || !((_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();
+export {
+  CODE_EXECUTION_REQUEST_PROCESSOR,
+  CodeExecutionRequestProcessor,
+  CodeExecutionResponseProcessor,
+  responseProcessor
+};

package/dist/esm/agents/processors/content_request_processor.js

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  getContents,
+  getCurrentTurnContents
+} from "../content_processor_utils.js";
+import { isLlmAgent } from "../llm_agent.js";
+class ContentRequestProcessor {
+  // eslint-disable-next-line require-yield
+  async *runAsync(invocationContext, llmRequest) {
+    const agent = invocationContext.agent;
+    if (!agent || !isLlmAgent(agent)) {
+      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();
+export {
+  CONTENT_REQUEST_PROCESSOR,
+  ContentRequestProcessor
+};

package/dist/esm/agents/processors/identity_llm_request_processor.js

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { appendInstructions } from "../../models/llm_request.js";
+import { BaseLlmRequestProcessor } from "./base_llm_processor.js";
+class IdentityLlmRequestProcessor extends BaseLlmRequestProcessor {
+  // eslint-disable-next-line require-yield
+  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();
+export {
+  IDENTITY_LLM_REQUEST_PROCESSOR,
+  IdentityLlmRequestProcessor
+};

package/dist/esm/agents/processors/instructions_llm_request_processor.js

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { appendInstructions } from "../../models/llm_request.js";
+import { injectSessionState } from "../instructions.js";
+import { isLlmAgent } from "../llm_agent.js";
+import { ReadonlyContext } from "../readonly_context.js";
+import { BaseLlmRequestProcessor } from "./base_llm_processor.js";
+class InstructionsLlmRequestProcessor extends BaseLlmRequestProcessor {
+  /**
+   * Handles instructions and global instructions for LLM flow.
+   */
+  // eslint-disable-next-line require-yield
+  async *runAsync(invocationContext, llmRequest) {
+    const agent = invocationContext.agent;
+    if (!isLlmAgent(agent) || !isLlmAgent(agent.rootAgent)) {
+      return;
+    }
+    const rootAgent = agent.rootAgent;
+    if (isLlmAgent(rootAgent) && 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();
+export {
+  INSTRUCTIONS_LLM_REQUEST_PROCESSOR,
+  InstructionsLlmRequestProcessor
+};