@softactivate/adk 1.1.0

package/dist/esm/agents/base_agent.js

@@ -0,0 +1,268 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var _a;
+import { context, trace } from "@opentelemetry/api";
+import { createEvent } from "../events/event.js";
+import {
+  runAsyncGeneratorWithOtelContext,
+  traceAgentInvocation,
+  tracer
+} from "../telemetry/tracing.js";
+import { Context } from "./context.js";
+import { InvocationContext } from "./invocation_context.js";
+const BASE_AGENT_SIGNATURE_SYMBOL = Symbol.for("google.adk.baseAgent");
+function isBaseAgent(obj) {
+  return typeof obj === "object" && obj !== null && BASE_AGENT_SIGNATURE_SYMBOL in obj && obj[BASE_AGENT_SIGNATURE_SYMBOL] === true;
+}
+_a = BASE_AGENT_SIGNATURE_SYMBOL;
+class BaseAgent {
+  constructor(config) {
+    /**
+     * A unique symbol to identify ADK agent classes.
+     */
+    this[_a] = true;
+    this.name = validateAgentName(config.name);
+    this.description = config.description;
+    this.parentAgent = config.parentAgent;
+    this.subAgents = config.subAgents || [];
+    this.beforeAgentCallback = getCannonicalCallback(
+      config.beforeAgentCallback
+    );
+    this.afterAgentCallback = getCannonicalCallback(config.afterAgentCallback);
+    this.setParentAgentForSubAgents();
+  }
+  /**
+   * Root agent of this agent.
+   * Computed dynamically by traversing up the parent chain.
+   */
+  get rootAgent() {
+    return getRootAgent(this);
+  }
+  /**
+   * Entry method to run an agent via text-based conversation.
+   *
+   * @param parentContext The invocation context of the parent agent.
+   * @yields The events generated by the agent.
+   * @returns An AsyncGenerator that yields the events generated by the agent.
+   */
+  async *runAsync(parentContext) {
+    const span = tracer.startSpan(`invoke_agent ${this.name}`);
+    const ctx = trace.setSpan(context.active(), span);
+    try {
+      yield* runAsyncGeneratorWithOtelContext(
+        ctx,
+        this,
+        async function* () {
+          var _a2, _b;
+          const context2 = this.createInvocationContext(parentContext);
+          const beforeAgentCallbackEvent = await this.handleBeforeAgentCallback(context2);
+          if (beforeAgentCallbackEvent) {
+            yield beforeAgentCallbackEvent;
+          }
+          if (context2.endInvocation || ((_a2 = parentContext.abortSignal) == null ? void 0 : _a2.aborted)) {
+            return;
+          }
+          traceAgentInvocation({ agent: this, invocationContext: context2 });
+          for await (const event of this.runAsyncImpl(context2)) {
+            yield event;
+          }
+          if (context2.endInvocation || ((_b = parentContext.abortSignal) == null ? void 0 : _b.aborted)) {
+            return;
+          }
+          const afterAgentCallbackEvent = await this.handleAfterAgentCallback(context2);
+          if (afterAgentCallbackEvent) {
+            yield afterAgentCallbackEvent;
+          }
+        }
+      );
+    } finally {
+      span.end();
+    }
+  }
+  /**
+   * Entry method to run an agent via video/audio-based conversation.
+   *
+   * @param parentContext The invocation context of the parent agent.
+   * @yields The events generated by the agent.
+   * @returns An AsyncGenerator that yields the events generated by the agent.
+   */
+  async *runLive(parentContext) {
+    const span = tracer.startSpan(`invoke_agent ${this.name}`);
+    const ctx = trace.setSpan(context.active(), span);
+    try {
+      yield* runAsyncGeneratorWithOtelContext(
+        ctx,
+        this,
+        async function* () {
+        }
+      );
+      throw new Error("Live mode is not implemented yet.");
+    } finally {
+      span.end();
+    }
+  }
+  /**
+   * Finds the agent with the given name in this agent and its descendants.
+   *
+   * @param name The name of the agent to find.
+   * @return The agent with the given name, or undefined if not found.
+   */
+  findAgent(name) {
+    if (this.name === name) {
+      return this;
+    }
+    return this.findSubAgent(name);
+  }
+  /**
+   * Finds the agent with the given name in this agent's descendants.
+   *
+   * @param name The name of the agent to find.
+   * @return The agent with the given name, or undefined if not found.
+   */
+  findSubAgent(name) {
+    for (const subAgent of this.subAgents) {
+      const result = subAgent.findAgent(name);
+      if (result) {
+        return result;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Creates an invocation context for this agent.
+   *
+   * @param parentContext The invocation context of the parent agent.
+   * @return The invocation context for this agent.
+   */
+  createInvocationContext(parentContext) {
+    return new InvocationContext({
+      ...parentContext,
+      agent: this
+    });
+  }
+  /**
+   * Runs the before agent callback if it exists.
+   *
+   * @param invocationContext The invocation context of the agent.
+   * @return The event to return to the user, or undefined if no event is
+   *     generated.
+   */
+  async handleBeforeAgentCallback(invocationContext) {
+    var _a2;
+    if (this.beforeAgentCallback.length === 0) {
+      return void 0;
+    }
+    const callbackContext = new Context({ invocationContext });
+    for (const callback of this.beforeAgentCallback) {
+      const content = await callback(callbackContext);
+      if ((_a2 = invocationContext.abortSignal) == null ? void 0 : _a2.aborted) {
+        return;
+      }
+      if (content) {
+        invocationContext.endInvocation = true;
+        return createEvent({
+          invocationId: invocationContext.invocationId,
+          author: this.name,
+          branch: invocationContext.branch,
+          content,
+          actions: callbackContext.eventActions
+        });
+      }
+    }
+    if (callbackContext.state.hasDelta()) {
+      return createEvent({
+        invocationId: invocationContext.invocationId,
+        author: this.name,
+        branch: invocationContext.branch,
+        actions: callbackContext.eventActions
+      });
+    }
+    return void 0;
+  }
+  /**
+   * Runs the after agent callback if it exists.
+   *
+   * @param invocationContext The invocation context of the agent.
+   * @return The event to return to the user, or undefined if no event is
+   *     generated.
+   */
+  async handleAfterAgentCallback(invocationContext) {
+    var _a2;
+    if (this.afterAgentCallback.length === 0) {
+      return void 0;
+    }
+    const callbackContext = new Context({ invocationContext });
+    for (const callback of this.afterAgentCallback) {
+      const content = await callback(callbackContext);
+      if ((_a2 = invocationContext.abortSignal) == null ? void 0 : _a2.aborted) {
+        return;
+      }
+      if (content) {
+        return createEvent({
+          invocationId: invocationContext.invocationId,
+          author: this.name,
+          branch: invocationContext.branch,
+          content,
+          actions: callbackContext.eventActions
+        });
+      }
+    }
+    if (callbackContext.state.hasDelta()) {
+      return createEvent({
+        invocationId: invocationContext.invocationId,
+        author: this.name,
+        branch: invocationContext.branch,
+        actions: callbackContext.eventActions
+      });
+    }
+    return void 0;
+  }
+  setParentAgentForSubAgents() {
+    for (const subAgent of this.subAgents) {
+      if (subAgent.parentAgent) {
+        throw new Error(
+          `Agent "${subAgent.name}" already has a parent agent, current parent: "${subAgent.parentAgent.name}", trying to add: "${this.name}"`
+        );
+      }
+      subAgent.parentAgent = this;
+    }
+  }
+}
+function validateAgentName(name) {
+  if (!isIdentifier(name)) {
+    throw new Error(
+      `Found invalid agent name: "${name}". Agent name must be a valid identifier. It should start with a letter (a-z, A-Z) or an underscore (_), and can only contain letters, digits (0-9), underscores, and hyphens.`
+    );
+  }
+  if (name === "user") {
+    throw new Error(
+      `Agent name cannot be 'user'. 'user' is reserved for end-user's input.`
+    );
+  }
+  return name;
+}
+function isIdentifier(str) {
+  return /^[\p{ID_Start}$_][\p{ID_Continue}$_-]*$/u.test(str);
+}
+function getRootAgent(rootAgent) {
+  while (rootAgent.parentAgent) {
+    rootAgent = rootAgent.parentAgent;
+  }
+  return rootAgent;
+}
+function getCannonicalCallback(callbacks) {
+  if (!callbacks) {
+    return [];
+  }
+  return Array.isArray(callbacks) ? callbacks : [callbacks];
+}
+export {
+  BaseAgent,
+  getCannonicalCallback,
+  isBaseAgent
+};

package/dist/esm/agents/context.js

@@ -0,0 +1,152 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthHandler } from "../auth/auth_handler.js";
+import { createEventActions } from "../events/event_actions.js";
+import { State } from "../sessions/state.js";
+import { ToolConfirmation } from "../tools/tool_confirmation.js";
+import { ReadonlyContext } from "./readonly_context.js";
+class Context extends ReadonlyContext {
+  /**
+   * @param options The configuration options for the Context.
+   * @param options.invocationContext The invocation context.
+   * @param options.eventActions The event actions of the current call.
+   * @param options.functionCallId The function call id of the current tool call.
+   *     This id was returned in the function call event from LLM to identify a
+   *     function call. If LLM didn't return this id, ADK will assign one to it.
+   *     This id is used to map function call response to the original function
+   *     call.
+   * @param options.toolConfirmation The tool confirmation of the current tool
+   *     call.
+   */
+  constructor(options) {
+    super(options.invocationContext);
+    this.eventActions = options.eventActions || createEventActions();
+    this._state = new State(
+      options.invocationContext.session.state,
+      this.eventActions.stateDelta
+    );
+    this.functionCallId = options.functionCallId;
+    this.toolConfirmation = options.toolConfirmation;
+    this.abortSignal = options.invocationContext.abortSignal;
+  }
+  /**
+   * The delta-aware state of the current session.
+   */
+  get state() {
+    return this._state;
+  }
+  get actions() {
+    return this.eventActions;
+  }
+  /**
+   * Loads an artifact attached to the current session.
+   *
+   * @param filename The filename of the artifact.
+   * @param version The version of the artifact. If not provided, the latest
+   *     version will be used.
+   * @return A promise that resolves to the loaded artifact.
+   */
+  loadArtifact(filename, version) {
+    if (!this.invocationContext.artifactService) {
+      throw new Error("Artifact service is not initialized.");
+    }
+    return this.invocationContext.artifactService.loadArtifact({
+      appName: this.invocationContext.appName,
+      userId: this.invocationContext.userId,
+      sessionId: this.invocationContext.session.id,
+      filename,
+      version
+    });
+  }
+  /**
+   * Saves an artifact attached to the current session.
+   *
+   * @param filename The filename of the artifact.
+   * @param artifact The artifact to save.
+   * @return A promise that resolves to the version of the saved artifact.
+   */
+  async saveArtifact(filename, artifact) {
+    if (!this.invocationContext.artifactService) {
+      throw new Error("Artifact service is not initialized.");
+    }
+    const version = await this.invocationContext.artifactService.saveArtifact({
+      appName: this.invocationContext.appName,
+      userId: this.invocationContext.userId,
+      sessionId: this.invocationContext.session.id,
+      filename,
+      artifact
+    });
+    this.eventActions.artifactDelta[filename] = version;
+    return version;
+  }
+  requestCredential(authConfig) {
+    if (!this.functionCallId) {
+      throw new Error("functionCallId is not set.");
+    }
+    const authHandler = new AuthHandler(authConfig);
+    this.eventActions.requestedAuthConfigs[this.functionCallId] = authHandler.generateAuthRequest();
+  }
+  /**
+   * Gets the auth credential for the given auth config.
+   *
+   * @param authConfig The auth config to get the auth credential for.
+   * @return The auth credential for the given auth config.
+   */
+  getAuthResponse(authConfig) {
+    const authHandler = new AuthHandler(authConfig);
+    return authHandler.getAuthResponse(this.state);
+  }
+  /**
+   * Lists the filenames of the artifacts attached to the current session.
+   *
+   * @return A promise that resolves to a list of artifact filenames.
+   */
+  listArtifacts() {
+    if (!this.invocationContext.artifactService) {
+      throw new Error("Artifact service is not initialized.");
+    }
+    return this.invocationContext.artifactService.listArtifactKeys({
+      appName: this.invocationContext.session.appName,
+      userId: this.invocationContext.session.userId,
+      sessionId: this.invocationContext.session.id
+    });
+  }
+  /**
+   * Searches the memory of the current user.
+   *
+   * @param query The query to search memory for.
+   * @return A promise that resolves to SearchMemoryResponse containing the
+   *     matching memories.
+   */
+  searchMemory(query) {
+    if (!this.invocationContext.memoryService) {
+      throw new Error("Memory service is not initialized.");
+    }
+    return this.invocationContext.memoryService.searchMemory({
+      appName: this.invocationContext.session.appName,
+      userId: this.invocationContext.session.userId,
+      query
+    });
+  }
+  /**
+   * Requests confirmation for the current tool call.
+   */
+  requestConfirmation({ hint, payload }) {
+    if (!this.functionCallId) {
+      throw new Error("functionCallId is not set.");
+    }
+    this.eventActions.requestedToolConfirmations[this.functionCallId] = new ToolConfirmation({
+      hint,
+      confirmed: false,
+      payload
+    });
+  }
+}
+export {
+  Context
+};