@softactivate/adk 1.1.0

package/dist/esm/agents/functions.js

@@ -0,0 +1,489 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createUserContent } from "@google/genai";
+import { isEmpty } from "lodash-es";
+import { createEvent, getFunctionCalls } from "../events/event.js";
+import { mergeEventActions } from "../events/event_actions.js";
+import { isAgentTool } from "../tools/agent_tool.js";
+import { randomUUID } from "../utils/env_aware_utils.js";
+import { logger } from "../utils/logger.js";
+import { Context } from "./context.js";
+import {
+  traceMergedToolCalls,
+  tracer,
+  traceToolCall
+} from "../telemetry/tracing.js";
+const AF_FUNCTION_CALL_ID_PREFIX = "adk-";
+const REQUEST_EUC_FUNCTION_CALL_NAME = "adk_request_credential";
+const REQUEST_CONFIRMATION_FUNCTION_CALL_NAME = "adk_request_confirmation";
+const functionsExportedForTestingOnly = {
+  handleFunctionCallList,
+  generateAuthEvent,
+  generateRequestConfirmationEvent
+};
+function generateClientFunctionCallId() {
+  return `${AF_FUNCTION_CALL_ID_PREFIX}${randomUUID()}`;
+}
+function populateClientFunctionCallId(modelResponseEvent) {
+  const functionCalls = getFunctionCalls(modelResponseEvent);
+  if (!functionCalls) {
+    return;
+  }
+  for (const functionCall of functionCalls) {
+    if (!functionCall.id) {
+      functionCall.id = generateClientFunctionCallId();
+    }
+  }
+}
+function removeClientFunctionCallId(content) {
+  if (content && content.parts) {
+    for (const part of content.parts) {
+      if (part.functionCall && part.functionCall.id && part.functionCall.id.startsWith(AF_FUNCTION_CALL_ID_PREFIX)) {
+        part.functionCall.id = void 0;
+      }
+      if (part.functionResponse && part.functionResponse.id && part.functionResponse.id.startsWith(AF_FUNCTION_CALL_ID_PREFIX)) {
+        part.functionResponse.id = void 0;
+      }
+    }
+  }
+}
+function getLongRunningFunctionCalls(functionCalls, toolsDict) {
+  const longRunningToolIds = /* @__PURE__ */ new Set();
+  for (const functionCall of functionCalls) {
+    if (functionCall.name && functionCall.name in toolsDict && toolsDict[functionCall.name].isLongRunning && functionCall.id) {
+      longRunningToolIds.add(functionCall.id);
+    }
+  }
+  return longRunningToolIds;
+}
+function generateAuthEvent(invocationContext, functionResponseEvent) {
+  var _a;
+  if (!((_a = functionResponseEvent.actions) == null ? void 0 : _a.requestedAuthConfigs) || isEmpty(functionResponseEvent.actions.requestedAuthConfigs)) {
+    return void 0;
+  }
+  const parts = [];
+  const longRunningToolIds = /* @__PURE__ */ new Set();
+  for (const [functionCallId, authConfig] of Object.entries(
+    functionResponseEvent.actions.requestedAuthConfigs
+  )) {
+    const requestEucFunctionCall = {
+      name: REQUEST_EUC_FUNCTION_CALL_NAME,
+      args: {
+        "function_call_id": functionCallId,
+        "auth_config": authConfig
+      },
+      id: generateClientFunctionCallId()
+    };
+    longRunningToolIds.add(requestEucFunctionCall.id);
+    parts.push({ functionCall: requestEucFunctionCall });
+  }
+  return createEvent({
+    invocationId: invocationContext.invocationId,
+    author: invocationContext.agent.name,
+    branch: invocationContext.branch,
+    content: {
+      parts,
+      role: functionResponseEvent.content.role
+    },
+    longRunningToolIds: Array.from(longRunningToolIds)
+  });
+}
+function generateRequestConfirmationEvent({
+  invocationContext,
+  functionCallEvent,
+  functionResponseEvent
+}) {
+  var _a, _b;
+  if (!((_a = functionResponseEvent.actions) == null ? void 0 : _a.requestedToolConfirmations) || isEmpty(functionResponseEvent.actions.requestedToolConfirmations)) {
+    return;
+  }
+  const parts = [];
+  const longRunningToolIds = /* @__PURE__ */ new Set();
+  const functionCalls = getFunctionCalls(functionCallEvent);
+  for (const [functionCallId, toolConfirmation] of Object.entries(
+    functionResponseEvent.actions.requestedToolConfirmations
+  )) {
+    const originalFunctionCall = (_b = functionCalls.find((call) => call.id === functionCallId)) != null ? _b : void 0;
+    if (!originalFunctionCall) {
+      continue;
+    }
+    const requestConfirmationFunctionCall = {
+      name: REQUEST_CONFIRMATION_FUNCTION_CALL_NAME,
+      args: {
+        "originalFunctionCall": originalFunctionCall,
+        "toolConfirmation": toolConfirmation
+      },
+      id: generateClientFunctionCallId()
+    };
+    longRunningToolIds.add(requestConfirmationFunctionCall.id);
+    parts.push({ functionCall: requestConfirmationFunctionCall });
+  }
+  return createEvent({
+    invocationId: invocationContext.invocationId,
+    author: invocationContext.agent.name,
+    branch: invocationContext.branch,
+    content: {
+      parts,
+      role: functionResponseEvent.content.role
+    },
+    actions: functionResponseEvent.actions,
+    longRunningToolIds: Array.from(longRunningToolIds)
+  });
+}
+async function callToolAsync(tool, args, toolContext) {
+  return tracer.startActiveSpan(`execute_tool ${tool.name}`, async (span) => {
+    try {
+      logger.debug(`callToolAsync ${tool.name}`);
+      const result = await tool.runAsync({ args, toolContext });
+      traceToolCall({
+        tool,
+        args,
+        functionResponseEvent: buildResponseEvent(
+          tool,
+          result,
+          toolContext,
+          toolContext.invocationContext
+        )
+      });
+      return result;
+    } finally {
+      span.end();
+    }
+  });
+}
+function buildResponseEvent(tool, functionResult, toolContext, invocationContext) {
+  let responseResult;
+  if (typeof functionResult !== "object" || functionResult == null) {
+    responseResult = { result: functionResult };
+  } else {
+    responseResult = functionResult;
+  }
+  const partFunctionResponse = {
+    functionResponse: {
+      name: tool.name,
+      response: responseResult,
+      id: toolContext.functionCallId
+    }
+  };
+  const content = {
+    role: "user",
+    parts: [partFunctionResponse]
+  };
+  return createEvent({
+    invocationId: invocationContext.invocationId,
+    author: invocationContext.agent.name,
+    content,
+    actions: toolContext.actions,
+    branch: invocationContext.branch
+  });
+}
+async function handleFunctionCallsAsync({
+  invocationContext,
+  functionCallEvent,
+  toolsDict,
+  beforeToolCallbacks,
+  afterToolCallbacks,
+  filters,
+  toolConfirmationDict
+}) {
+  const functionCalls = getFunctionCalls(functionCallEvent);
+  return await handleFunctionCallList({
+    invocationContext,
+    functionCalls,
+    toolsDict,
+    beforeToolCallbacks,
+    afterToolCallbacks,
+    filters,
+    toolConfirmationDict
+  });
+}
+async function* handleFunctionCallsStreamingAsync({
+  invocationContext,
+  functionCallEvent,
+  toolsDict,
+  beforeToolCallbacks,
+  afterToolCallbacks,
+  toolConfirmationDict
+}) {
+  var _a, _b;
+  const functionCalls = getFunctionCalls(functionCallEvent);
+  if (!functionCalls.length) {
+    return;
+  }
+  const agentToolCalls = [];
+  const regularCalls = [];
+  for (const functionCall of functionCalls) {
+    const tool = functionCall.name ? toolsDict[functionCall.name] : void 0;
+    if (tool && isAgentTool(tool)) {
+      agentToolCalls.push({ call: functionCall, tool });
+    } else {
+      regularCalls.push(functionCall);
+    }
+  }
+  const agentToolResponseEvents = [];
+  for (const { call, tool } of agentToolCalls) {
+    const toolContext = new Context({
+      invocationContext,
+      functionCallId: call.id || void 0,
+      toolConfirmation: toolConfirmationDict && call.id ? toolConfirmationDict[call.id] : void 0
+    });
+    let lastContent;
+    for await (const event of tool.runAsyncWithEvents({
+      args: (_a = call.args) != null ? _a : {},
+      toolContext
+    })) {
+      if ((_b = invocationContext.abortSignal) == null ? void 0 : _b.aborted) {
+        return;
+      }
+      if (event.content) {
+        lastContent = event.content;
+      }
+      yield event;
+    }
+    const toolResult = tool.buildToolResultFromContent(lastContent);
+    const responseValue = typeof toolResult !== "object" || toolResult == null ? { result: toolResult } : toolResult;
+    agentToolResponseEvents.push(
+      createEvent({
+        invocationId: invocationContext.invocationId,
+        author: invocationContext.agent.name,
+        content: createUserContent({
+          functionResponse: {
+            id: call.id,
+            name: tool.name,
+            response: responseValue
+          }
+        }),
+        actions: toolContext.actions,
+        branch: invocationContext.branch
+      })
+    );
+  }
+  let regularResponseEvent = null;
+  if (regularCalls.length) {
+    regularResponseEvent = await handleFunctionCallList({
+      invocationContext,
+      functionCalls: regularCalls,
+      toolsDict,
+      beforeToolCallbacks,
+      afterToolCallbacks,
+      toolConfirmationDict
+    });
+  }
+  const allResponseEvents = [];
+  if (regularResponseEvent) {
+    allResponseEvents.push(regularResponseEvent);
+  }
+  allResponseEvents.push(...agentToolResponseEvents);
+  if (!allResponseEvents.length) {
+    return;
+  }
+  yield allResponseEvents.length === 1 ? allResponseEvents[0] : mergeParallelFunctionResponseEvents(allResponseEvents);
+}
+async function handleFunctionCallList({
+  invocationContext,
+  functionCalls,
+  toolsDict,
+  beforeToolCallbacks,
+  afterToolCallbacks,
+  filters,
+  toolConfirmationDict
+}) {
+  var _a;
+  const functionResponseEvents = [];
+  const filteredFunctionCalls = functionCalls.filter((functionCall) => {
+    return !filters || functionCall.id && filters.has(functionCall.id);
+  });
+  for (const functionCall of filteredFunctionCalls) {
+    let toolConfirmation = void 0;
+    if (toolConfirmationDict && functionCall.id) {
+      toolConfirmation = toolConfirmationDict[functionCall.id];
+    }
+    const { tool, toolContext } = getToolAndContext({
+      invocationContext,
+      functionCall,
+      toolsDict,
+      toolConfirmation
+    });
+    logger.debug(`execute_tool ${tool.name}`);
+    const functionArgs = (_a = functionCall.args) != null ? _a : {};
+    let functionResponse = null;
+    let functionResponseError;
+    functionResponse = await invocationContext.pluginManager.runBeforeToolCallback({
+      tool,
+      toolArgs: functionArgs,
+      toolContext
+    });
+    if (functionResponse == null) {
+      for (const callback of beforeToolCallbacks) {
+        functionResponse = await callback({
+          tool,
+          args: functionArgs,
+          context: toolContext
+        });
+        if (functionResponse) {
+          break;
+        }
+      }
+    }
+    if (functionResponse == null) {
+      try {
+        functionResponse = await callToolAsync(tool, functionArgs, toolContext);
+      } catch (e) {
+        if (e instanceof Error) {
+          const onToolErrorResponse = await invocationContext.pluginManager.runOnToolErrorCallback({
+            tool,
+            toolArgs: functionArgs,
+            toolContext,
+            error: e
+          });
+          if (onToolErrorResponse) {
+            functionResponse = onToolErrorResponse;
+          } else {
+            functionResponseError = e.message;
+          }
+        } else {
+          functionResponseError = e;
+        }
+      }
+    }
+    let alteredFunctionResponse = await invocationContext.pluginManager.runAfterToolCallback({
+      tool,
+      toolArgs: functionArgs,
+      toolContext,
+      result: functionResponse
+    });
+    if (alteredFunctionResponse == null) {
+      for (const callback of afterToolCallbacks) {
+        alteredFunctionResponse = await callback({
+          tool,
+          args: functionArgs,
+          context: toolContext,
+          response: functionResponse
+        });
+        if (alteredFunctionResponse) {
+          break;
+        }
+      }
+    }
+    if (alteredFunctionResponse != null) {
+      functionResponse = alteredFunctionResponse;
+    }
+    if (tool.isLongRunning && !functionResponse) {
+      continue;
+    }
+    if (functionResponseError) {
+      functionResponse = { error: functionResponseError };
+    } else if (typeof functionResponse !== "object" || functionResponse == null) {
+      functionResponse = { result: functionResponse };
+    }
+    const functionResponseEvent = createEvent({
+      invocationId: invocationContext.invocationId,
+      author: invocationContext.agent.name,
+      content: createUserContent({
+        functionResponse: {
+          id: toolContext.functionCallId,
+          name: tool.name,
+          response: functionResponse
+        }
+      }),
+      actions: toolContext.actions,
+      branch: invocationContext.branch
+    });
+    logger.debug("traceToolCall", {
+      tool: tool.name,
+      args: functionArgs,
+      functionResponseEvent: functionResponseEvent.id
+    });
+    functionResponseEvents.push(functionResponseEvent);
+  }
+  if (!functionResponseEvents.length) {
+    return null;
+  }
+  const mergedEvent = mergeParallelFunctionResponseEvents(
+    functionResponseEvents
+  );
+  if (functionResponseEvents.length > 1) {
+    tracer.startActiveSpan("execute_tool (merged)", (span) => {
+      try {
+        logger.debug("execute_tool (merged)");
+        logger.debug("traceMergedToolCalls", {
+          responseEventId: mergedEvent.id,
+          functionResponseEvent: mergedEvent.id
+        });
+        traceMergedToolCalls({
+          responseEventId: mergedEvent.id,
+          functionResponseEvent: mergedEvent
+        });
+      } finally {
+        span.end();
+      }
+    });
+  }
+  return mergedEvent;
+}
+function getToolAndContext({
+  invocationContext,
+  functionCall,
+  toolsDict,
+  toolConfirmation
+}) {
+  if (!functionCall.name || !(functionCall.name in toolsDict)) {
+    throw new Error(
+      `Function ${functionCall.name} is not found in the toolsDict.`
+    );
+  }
+  const toolContext = new Context({
+    invocationContext,
+    functionCallId: functionCall.id || void 0,
+    toolConfirmation
+  });
+  const tool = toolsDict[functionCall.name];
+  return { tool, toolContext };
+}
+function mergeParallelFunctionResponseEvents(functionResponseEvents) {
+  if (!functionResponseEvents.length) {
+    throw new Error("No function response events provided.");
+  }
+  if (functionResponseEvents.length === 1) {
+    return functionResponseEvents[0];
+  }
+  const mergedParts = [];
+  for (const event of functionResponseEvents) {
+    if (event.content && event.content.parts) {
+      mergedParts.push(...event.content.parts);
+    }
+  }
+  const baseEvent = functionResponseEvents[0];
+  const actionsList = functionResponseEvents.map(
+    (event) => event.actions || {}
+  );
+  const mergedActions = mergeEventActions(actionsList);
+  return createEvent({
+    invocationId: baseEvent.invocationId,
+    author: baseEvent.author,
+    branch: baseEvent.branch,
+    content: { role: "user", parts: mergedParts },
+    actions: mergedActions,
+    timestamp: baseEvent.timestamp
+  });
+}
+export {
+  REQUEST_CONFIRMATION_FUNCTION_CALL_NAME,
+  REQUEST_EUC_FUNCTION_CALL_NAME,
+  functionsExportedForTestingOnly,
+  generateAuthEvent,
+  generateClientFunctionCallId,
+  generateRequestConfirmationEvent,
+  getLongRunningFunctionCalls,
+  handleFunctionCallList,
+  handleFunctionCallsAsync,
+  handleFunctionCallsStreamingAsync,
+  mergeParallelFunctionResponseEvents,
+  populateClientFunctionCallId,
+  removeClientFunctionCallId
+};

package/dist/esm/agents/instructions.js

@@ -0,0 +1,82 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { State } from "../sessions/state.js";
+async function injectSessionState(template, readonlyContext) {
+  const invocationContext = readonlyContext.invocationContext;
+  async function replaceMatchedKeyWithItsValue(match) {
+    let key = match[0].replace(/^\{+/, "").replace(/\}+$/, "").trim();
+    const isOptional = key.endsWith("?");
+    if (isOptional) {
+      key = key.slice(0, -1);
+    }
+    if (key.startsWith("artifact.")) {
+      const fileName = key.substring("artifact.".length);
+      if (invocationContext.artifactService === void 0) {
+        throw new Error("Artifact service is not initialized.");
+      }
+      const artifact = await invocationContext.artifactService.loadArtifact({
+        appName: invocationContext.session.appName,
+        userId: invocationContext.session.userId,
+        sessionId: invocationContext.session.id,
+        filename: fileName
+      });
+      if (!artifact) {
+        throw new Error(`Artifact ${fileName} not found.`);
+      }
+      return String(artifact);
+    }
+    if (!isValidStateName(key)) {
+      return match[0];
+    }
+    if (key in invocationContext.session.state) {
+      return String(invocationContext.session.state[key]);
+    }
+    if (isOptional) {
+      return "";
+    }
+    throw new Error(`Context variable not found: \`${key}\`.`);
+  }
+  const pattern = /\{+[^{}]*}+/g;
+  const result = [];
+  let lastEnd = 0;
+  const matches = template.matchAll(pattern);
+  for (const match of matches) {
+    result.push(template.slice(lastEnd, match.index));
+    const replacement = await replaceMatchedKeyWithItsValue(match);
+    result.push(replacement);
+    lastEnd = match.index + match[0].length;
+  }
+  result.push(template.slice(lastEnd));
+  return result.join("");
+}
+const isIdentifierPattern = /* @__PURE__ */ (() => {
+  return /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+})();
+function isIdentifier(s) {
+  if (s === "" || s === void 0) {
+    return false;
+  }
+  return isIdentifierPattern.test(s);
+}
+const VALID_PREFIXES = [State.APP_PREFIX, State.USER_PREFIX, State.TEMP_PREFIX];
+function isValidStateName(variableName) {
+  const parts = variableName.split(":");
+  if (parts.length === 0 || parts.length > 2) {
+    return false;
+  }
+  if (parts.length === 1) {
+    return isIdentifier(variableName);
+  }
+  if (VALID_PREFIXES.includes(parts[0] + ":")) {
+    return isIdentifier(parts[1]);
+  }
+  return false;
+}
+export {
+  injectSessionState
+};

package/dist/esm/agents/invocation_context.js

@@ -0,0 +1,81 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { randomUUID } from "../utils/env_aware_utils.js";
+class InvocationCostManager {
+  constructor() {
+    this.numberOfLlmCalls = 0;
+  }
+  /**
+   * Increments the number of llm calls and enforces the limit.
+   *
+   * @param runConfig the run config of the invocation.
+   * @throws If number of llm calls made exceed the set threshold.
+   */
+  incrementAndEnforceLlmCallsLimit(runConfig) {
+    this.numberOfLlmCalls++;
+    if (runConfig && runConfig.maxLlmCalls > 0 && this.numberOfLlmCalls > runConfig.maxLlmCalls) {
+      throw new Error(
+        `Max number of llm calls limit of ${runConfig.maxLlmCalls} exceeded`
+      );
+    }
+  }
+}
+class InvocationContext {
+  /**
+   * @param params The parameters for creating an invocation context.
+   */
+  constructor(params) {
+    /**
+     * A container to keep track of different kinds of costs incurred as a part of
+     * this invocation.
+     */
+    this.invocationCostManager = new InvocationCostManager();
+    this.artifactService = params.artifactService;
+    this.sessionService = params.sessionService;
+    this.memoryService = params.memoryService;
+    this.invocationId = params.invocationId;
+    this.branch = params.branch;
+    this.agent = params.agent;
+    this.userContent = params.userContent;
+    this.session = params.session;
+    this.endInvocation = params.endInvocation || false;
+    this.transcriptionCache = params.transcriptionCache;
+    this.runConfig = params.runConfig;
+    this.liveRequestQueue = params.liveRequestQueue;
+    this.activeStreamingTools = params.activeStreamingTools;
+    this.pluginManager = params.pluginManager;
+    this.abortSignal = params.abortSignal;
+  }
+  /**
+   * The app name of the current session.
+   */
+  get appName() {
+    return this.session.appName;
+  }
+  /**
+   * The user ID of the current session.
+   */
+  get userId() {
+    return this.session.userId;
+  }
+  /**
+   * Tracks number of llm calls made.
+   *
+   * @throws If number of llm calls made exceed the set threshold.
+   */
+  incrementLlmCallCount() {
+    this.invocationCostManager.incrementAndEnforceLlmCallsLimit(this.runConfig);
+  }
+}
+function newInvocationContextId() {
+  return `e-${randomUUID()}`;
+}
+export {
+  InvocationContext,
+  newInvocationContextId
+};