@google/adk 2.1.0 → 2.2.1

package/dist/cjs/planners/plan_re_act_planner.js

@@ -0,0 +1,172 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var plan_re_act_planner_exports = {};
+__export(plan_re_act_planner_exports, {
+  PlanReActPlanner: () => PlanReActPlanner
+});
+module.exports = __toCommonJS(plan_re_act_planner_exports);
+var import_base_planner = require("./base_planner.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const PLANNING_TAG = "/*PLANNING*/";
+const REPLANNING_TAG = "/*REPLANNING*/";
+const REASONING_TAG = "/*REASONING*/";
+const ACTION_TAG = "/*ACTION*/";
+const FINAL_ANSWER_TAG = "/*FINAL_ANSWER*/";
+const THOUGHT_PREFIX_TAGS = [
+  PLANNING_TAG,
+  REASONING_TAG,
+  ACTION_TAG,
+  REPLANNING_TAG
+];
+const _PlanReActPlanner = class _PlanReActPlanner extends import_base_planner.BasePlanner {
+  buildPlanningInstruction(_readonlyContext, _llmRequest) {
+    return buildNlPlannerInstruction();
+  }
+  processPlanningResponse(_callbackContext, responseParts) {
+    if (!responseParts || responseParts.length === 0) {
+      return void 0;
+    }
+    const preservedParts = [];
+    let firstFcPartIndex = -1;
+    for (let i = 0; i < responseParts.length; i++) {
+      const part = responseParts[i];
+      if (part.functionCall) {
+        if (!part.functionCall.name) {
+          continue;
+        }
+        preservedParts.push(part);
+        firstFcPartIndex = i;
+        break;
+      }
+      handleNonFunctionCallPart(part, preservedParts);
+    }
+    if (firstFcPartIndex > 0) {
+      for (let j = firstFcPartIndex + 1; j < responseParts.length; j++) {
+        if (!responseParts[j].functionCall) {
+          break;
+        }
+        preservedParts.push(responseParts[j]);
+      }
+    }
+    return preservedParts;
+  }
+};
+__name(_PlanReActPlanner, "PlanReActPlanner");
+let PlanReActPlanner = _PlanReActPlanner;
+function splitByLastPattern(text, separator) {
+  const index = text.lastIndexOf(separator);
+  if (index === -1) {
+    return [text, ""];
+  }
+  const end = index + separator.length;
+  return [text.slice(0, end), text.slice(end)];
+}
+__name(splitByLastPattern, "splitByLastPattern");
+function handleNonFunctionCallPart(responsePart, preservedParts) {
+  var _a;
+  if (responsePart.text && responsePart.text.includes(FINAL_ANSWER_TAG)) {
+    const [reasoningText, finalAnswerText] = splitByLastPattern(
+      responsePart.text,
+      FINAL_ANSWER_TAG
+    );
+    if (reasoningText) {
+      preservedParts.push(markAsThought({ text: reasoningText }));
+    }
+    if (finalAnswerText) {
+      preservedParts.push({ text: finalAnswerText });
+    }
+    return;
+  }
+  const responseText = (_a = responsePart.text) != null ? _a : "";
+  if (responseText && THOUGHT_PREFIX_TAGS.some((tag) => responseText.startsWith(tag))) {
+    preservedParts.push(markAsThought(responsePart));
+    return;
+  }
+  preservedParts.push(responsePart);
+}
+__name(handleNonFunctionCallPart, "handleNonFunctionCallPart");
+function markAsThought(responsePart) {
+  if (responsePart.text) {
+    return { ...responsePart, thought: true };
+  }
+  return responsePart;
+}
+__name(markAsThought, "markAsThought");
+function buildNlPlannerInstruction() {
+  const highLevelPreamble = `
+When answering the question, try to leverage the available tools to gather the information instead of your memorized knowledge.
+
+Follow this process when answering the question: (1) first come up with a plan in natural language text format; (2) Then use tools to execute the plan and provide reasoning between tool code snippets to make a summary of current state and next step. Tool code snippets and reasoning should be interleaved with each other. (3) In the end, return one final answer.
+
+Follow this format when answering the question: (1) The planning part should be under ${PLANNING_TAG}. (2) The tool code snippets should be under ${ACTION_TAG}, and the reasoning parts should be under ${REASONING_TAG}. (3) The final answer part should be under ${FINAL_ANSWER_TAG}.
+`;
+  const planningPreamble = `
+Below are the requirements for the planning:
+The plan is made to answer the user query if following the plan. The plan is coherent and covers all aspects of information from user query, and only involves the tools that are accessible by the agent. The plan contains the decomposed steps as a numbered list where each step should use one or multiple available tools. By reading the plan, you can intuitively know which tools to trigger or what actions to take.
+If the initial plan cannot be successfully executed, you should learn from previous execution results and revise your plan. The revised plan should be be under ${REPLANNING_TAG}. Then use tools to follow the new plan.
+`;
+  const reasoningPreamble = `
+Below are the requirements for the reasoning:
+The reasoning makes a summary of the current trajectory based on the user query and tool outputs. Based on the tool outputs and plan, the reasoning also comes up with instructions to the next steps, making the trajectory closer to the final answer.
+`;
+  const finalAnswerPreamble = `
+Below are the requirements for the final answer:
+The final answer should be precise and follow query formatting requirements. Some queries may not be answerable with the available tools and information. In those cases, inform the user why you cannot process their query and ask for more information.
+`;
+  const toolCodeWithoutPythonLibrariesPreamble = `
+Below are the requirements for the tool code:
+
+**Custom Tools:** The available tools are described in the context and can be directly used.
+- Code must be valid self-contained Python snippets with no imports and no references to tools or Python libraries that are not in the context.
+- You cannot use any parameters or fields that are not explicitly defined in the APIs in the context.
+- The code snippets should be readable, efficient, and directly relevant to the user query and reasoning steps.
+- When using the tools, you should use the library name together with the function name, e.g., vertex_search.search().
+- If Python libraries are not provided in the context, NEVER write your own code other than the function calls using the provided tools.
+`;
+  const userInputPreamble = `
+VERY IMPORTANT instruction that you MUST follow in addition to the above instructions:
+
+You should ask for clarification if you need more information to answer the question.
+You should prefer using the information available in the context instead of repeated tool use.
+`;
+  return [
+    highLevelPreamble,
+    planningPreamble,
+    reasoningPreamble,
+    finalAnswerPreamble,
+    toolCodeWithoutPythonLibrariesPreamble,
+    userInputPreamble
+  ].join("\n\n");
+}
+__name(buildNlPlannerInstruction, "buildNlPlannerInstruction");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PlanReActPlanner
+});

package/dist/cjs/plugins/base_plugin.js

@@ -65,14 +65,13 @@ const _BasePlugin = class _BasePlugin {
    * This callback helps logging and modifying the user message before the
    * runner starts the invocation.
    *
-   * @param params.invocationContext The context for the entire invocation.
-   * @param params.userMessage The message content input by user.
+   * @param _params.invocationContext The context for the entire invocation.
+   * @param _params.userMessage The message content input by user.
    * @returns An optional `Content` to be returned to the ADK. Returning a
    *     value to replace the user message. Returning `undefined` to proceed
    *     normally.
    */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async onUserMessageCallback(params) {
+  async onUserMessageCallback(_params) {
     return;
   }
   /**
@@ -81,14 +80,13 @@ const _BasePlugin = class _BasePlugin {
    * This is the first callback to be called in the lifecycle, ideal for global
    * setup or initialization tasks.
    *
-   * @param params.invocationContext The context for the entire invocation, containing
+   * @param _params.invocationContext The context for the entire invocation, containing
    *     session information, the root agent, etc.
    * @returns An optional `Event` to be returned to the ADK. Returning a value
    *     to halt execution of the runner and ends the runner with that event.
    *     Return `undefined` to proceed normally.
    */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async beforeRunCallback(params) {
+  async beforeRunCallback(_params) {
     return;
   }
   /**
@@ -97,16 +95,15 @@ const _BasePlugin = class _BasePlugin {
    * This is the ideal place to make modification to the event before the event
    * is handled by the underlying agent app.
    *
-   * @param params.invocationContext The context for the entire invocation.
-   * @param params.event The event raised by the runner.
+   * @param _params.invocationContext The context for the entire invocation.
+   * @param _params.event The event raised by the runner.
    * @returns An optional value. A non-`undefined` return may be used by the
-   *     framework to modify or replace the response. Copy `params.event` when
-   *     constructing a replacement to preserve fields that are not being
-   *     modified, such as event actions. Returning `undefined` allows the
+   *     framework to modify or replace the response. Copy the incoming
+   *     `event` when constructing a replacement to preserve fields that are not
+   *     being modified, such as event actions. Returning `undefined` allows the
    *     original response to be used.
    */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async onEventCallback(params) {
+  async onEventCallback(_params) {
     return;
   }
   /**
@@ -115,11 +112,10 @@ const _BasePlugin = class _BasePlugin {
    * This is the final callback in the ADK lifecycle, suitable for cleanup,
    * final logging, or reporting tasks.
    *
-   * @param params.invocationContext The context for the entire invocation.
+   * @param _params.invocationContext The context for the entire invocation.
    * @returns undefined
    */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async afterRunCallback(params) {
+  async afterRunCallback(_params) {
     return;
   }
   /**
@@ -128,14 +124,13 @@ const _BasePlugin = class _BasePlugin {
    * This callback can be used for logging, setup, or to short-circuit the
    * agent's execution by returning a value.
    *
-   * @param params.agent The agent that is about to run.
-   * @param params.callbackContext The context for the agent invocation.
+   * @param _params.agent The agent that is about to run.
+   * @param _params.callbackContext The context for the agent invocation.
    * @returns An optional `Content` object. If a value is returned, it will
    *     bypass the agent's callbacks and its execution, and return this value
    *     directly. Returning `undefined` allows the agent to proceed normally.
    */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async beforeAgentCallback(params) {
+  async beforeAgentCallback(_params) {
     return;
   }
   /**
@@ -144,14 +139,13 @@ const _BasePlugin = class _BasePlugin {
    * This callback can be used to inspect, log, or modify the agent's final
    * result before it is returned.
    *
-   * @param params.agent The agent that has just run.
-   * @param params.callbackContext The context for the agent invocation.
+   * @param _params.agent The agent that has just run.
+   * @param _params.callbackContext The context for the agent invocation.
    * @returns An optional `Content` object. If a value is returned, it will
    *     replace the agent's original result. Returning `undefined` uses the
    *     original, unmodified result.
    */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async afterAgentCallback(params) {
+  async afterAgentCallback(_params) {
     return;
   }
   /**
@@ -192,14 +186,13 @@ const _BasePlugin = class _BasePlugin {
    * object. It can also be used to implement caching by returning a cached
    * `LlmResponse`, which would skip the actual model call.
    *
-   * @param params.callbackContext The context for the current agent call.
-   * @param params.llmRequest The prepared request object to be sent to the model.
+   * @param _params.callbackContext The context for the current agent call.
+   * @param _params.llmRequest The prepared request object to be sent to the model.
    * @returns An optional value. The interpretation of a non-`undefined`
    *     trigger an early exit and returns the response immediately. Returning
    *     `undefined` allows the LLM request to proceed normally.
    */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async beforeModelCallback(params) {
+  async beforeModelCallback(_params) {
     return;
   }
   /**
@@ -208,14 +201,13 @@ const _BasePlugin = class _BasePlugin {
    * This is the ideal place to log model responses, collect metrics on token
    * usage, or perform post-processing on the raw `LlmResponse`.
    *
-   * @param params.callbackContext The context for the current agent call.
-   * @param params.llmResponse The response object received from the model.
+   * @param _params.callbackContext The context for the current agent call.
+   * @param _params.llmResponse The response object received from the model.
    * @returns An optional value. A non-`undefined` return may be used by the
    *     framework to modify or replace the response. Returning `undefined`
    *     allows the original response to be used.
    */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async afterModelCallback(params) {
+  async afterModelCallback(_params) {
     return;
   }
   /**
@@ -224,28 +216,24 @@ const _BasePlugin = class _BasePlugin {
    * This callback provides an opportunity to handle model errors gracefully,
    * potentially providing alternative responses or recovery mechanisms.
    *
-   * @param params.callbackContext The context for the current agent call.
-   * @param params.llmRequest The request that was sent to the model when the error
+   * @param _params.callbackContext The context for the current agent call.
+   * @param _params.llmRequest The request that was sent to the model when the error
    *     occurred.
-   * @param params.error The exception that was raised during model execution.
+   * @param _params.error The exception that was raised during model execution.
    * @returns An optional LlmResponse. If an LlmResponse is returned, it will be
    *     used instead of propagating the error. Returning `undefined` allows
    *     the original error to be raised.
    */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async onModelErrorCallback(params) {
+  async onModelErrorCallback(_params) {
     return;
   }
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async beforeToolSelection(params) {
+  async beforeToolSelection(_params) {
     return;
   }
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async beforeContextCompaction(params) {
+  async beforeContextCompaction(_params) {
     return;
   }
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async afterContextCompaction(params) {
+  async afterContextCompaction(_params) {
     return;
   }
   /**
@@ -254,16 +242,15 @@ const _BasePlugin = class _BasePlugin {
    * This callback is useful for logging tool usage, input validation, or
    * modifying the arguments before they are passed to the tool.
    *
-   * @param params.tool The tool instance that is about to be executed.
-   * @param params.toolArgs The dictionary of arguments to be used for invoking the
+   * @param _params.tool The tool instance that is about to be executed.
+   * @param _params.toolArgs The dictionary of arguments to be used for invoking the
    *     tool.
-   * @param params.toolContext The context specific to the tool execution.
+   * @param _params.toolContext The context specific to the tool execution.
    * @returns An optional dictionary. If a dictionary is returned, it will stop
    *     the tool execution and return this response immediately. Returning
    *     `undefined` uses the original, unmodified arguments.
    */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async beforeToolCallback(params) {
+  async beforeToolCallback(_params) {
     return;
   }
   /**
@@ -272,17 +259,16 @@ const _BasePlugin = class _BasePlugin {
    * This callback allows for inspecting, logging, or modifying the result
    * returned by a tool.
    *
-   * @param params.tool The tool instance that has just been executed.
-   * @param params.toolArgs The original arguments that were passed to the tool.
-   * @param params.toolContext The context specific to the tool execution.
-   * @param params.result The dictionary returned by the tool invocation.
+   * @param _params.tool The tool instance that has just been executed.
+   * @param _params.toolArgs The original arguments that were passed to the tool.
+   * @param _params.toolContext The context specific to the tool execution.
+   * @param _params.result The dictionary returned by the tool invocation.
    * @returns An optional dictionary. If a dictionary is returned, it will
    *     **replace** the original result from the tool. This allows for
    *     post-processing or altering tool outputs. Returning `undefined` uses
    *     the original, unmodified result.
    */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async afterToolCallback(params) {
+  async afterToolCallback(_params) {
     return;
   }
   /**
@@ -301,16 +287,15 @@ const _BasePlugin = class _BasePlugin {
      * This callback provides an opportunity to handle tool errors gracefully,
      * potentially providing alternative responses or recovery mechanisms.
      *
-     * @param params.tool The tool instance that encountered an error.
-     * @param params.toolArgs The arguments that were passed to the tool.
-     * @param params.toolContext The context specific to the tool execution.
-     * @param params.error The exception that was raised during tool execution.
+     * @param _params.tool The tool instance that encountered an error.
+     * @param _params.toolArgs The arguments that were passed to the tool.
+     * @param _params.toolContext The context specific to the tool execution.
+     * @param _params.error The exception that was raised during tool execution.
      * @returns An optional dictionary. If a dictionary is returned, it will be
      *     used as the tool response instead of propagating the error. Returning
      *     `undefined` allows the original error to be raised.
      */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async onToolErrorCallback(params) {
+  async onToolErrorCallback(_params) {
     return;
   }
 };