@google/adk 0.4.0 → 0.6.0

package/dist/web/a2a/a2a_remote_agent_run_processor.js

@@ -0,0 +1,175 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  createModelContent
+} from "@google/genai";
+import { createEvent } from "../events/event.js";
+import {
+  getEventMetadata,
+  isTask,
+  isTaskArtifactUpdateEvent,
+  isTaskStatusUpdateEvent
+} from "./a2a_event.js";
+import { A2AMetadataKeys } from "./metadata_converter_utils.js";
+class A2ARemoteAgentRunProcessor {
+  constructor(request) {
+    this.request = request;
+    this.aggregations = /* @__PURE__ */ new Map();
+    this.aggregationOrder = [];
+  }
+  /**
+   * aggregatePartial stores contents of partial events to emit them with the terminal event.
+   * It can return multiple events to emit instead of just the provided one.
+   */
+  aggregatePartial(context, a2aEvent, adkEvent) {
+    const metadata = getEventMetadata(a2aEvent);
+    if (metadata[A2AMetadataKeys.PARTIAL]) {
+      return [adkEvent];
+    }
+    if (isTaskStatusUpdateEvent(a2aEvent) && a2aEvent.final) {
+      const events = [];
+      for (const aid of this.aggregationOrder) {
+        const agg = this.aggregations.get(aid);
+        if (agg) {
+          events.push(this.buildNonPartialAggregation(context, agg));
+        }
+      }
+      this.aggregations.clear();
+      this.aggregationOrder = [];
+      return [...events, adkEvent];
+    }
+    if (isTask(a2aEvent)) {
+      this.aggregations.clear();
+      this.aggregationOrder = [];
+      return [adkEvent];
+    }
+    if (!isTaskArtifactUpdateEvent(a2aEvent)) {
+      return [adkEvent];
+    }
+    const artifactId = a2aEvent.artifact.artifactId;
+    if (!a2aEvent.append) {
+      this.removeAggregation(artifactId);
+      if (a2aEvent.lastChunk) {
+        adkEvent.partial = false;
+        return [adkEvent];
+      }
+    }
+    let aggregation = this.aggregations.get(artifactId);
+    if (!aggregation) {
+      aggregation = {
+        aggregatedText: "",
+        aggregatedThoughts: "",
+        parts: []
+      };
+      this.aggregations.set(artifactId, aggregation);
+      this.aggregationOrder.push(artifactId);
+    } else {
+      this.aggregationOrder = this.aggregationOrder.filter(
+        (id) => id !== artifactId
+      );
+      this.aggregationOrder.push(artifactId);
+    }
+    this.updateAggregation(aggregation, adkEvent);
+    if (!a2aEvent.lastChunk) {
+      return [adkEvent];
+    }
+    this.removeAggregation(artifactId);
+    return [adkEvent, this.buildNonPartialAggregation(context, aggregation)];
+  }
+  removeAggregation(artifactId) {
+    this.aggregations.delete(artifactId);
+    this.aggregationOrder = this.aggregationOrder.filter(
+      (id) => id !== artifactId
+    );
+  }
+  updateAggregation(agg, event) {
+    var _a;
+    const parts = ((_a = event.content) == null ? void 0 : _a.parts) || [];
+    for (const part of parts) {
+      if (part.text && part.text !== "") {
+        if (part.thought) {
+          agg.aggregatedThoughts += part.text;
+        } else {
+          agg.aggregatedText += part.text;
+        }
+      } else {
+        this.promoteTextBlocksToParts(agg);
+        agg.parts.push(part);
+      }
+    }
+    if (event.citationMetadata) {
+      if (!agg.citations) {
+        agg.citations = { citations: [] };
+      }
+      if (!agg.citations.citations) {
+        agg.citations.citations = [];
+      }
+      agg.citations.citations.push(...event.citationMetadata.citations || []);
+    }
+    if (event.customMetadata) {
+      if (!agg.customMeta) {
+        agg.customMeta = {};
+      }
+      Object.assign(agg.customMeta, event.customMetadata);
+    }
+    if (event.groundingMetadata) {
+      agg.grounding = event.groundingMetadata;
+    }
+    if (event.usageMetadata) {
+      agg.usage = event.usageMetadata;
+    }
+  }
+  buildNonPartialAggregation(context, agg) {
+    this.promoteTextBlocksToParts(agg);
+    const result = createEvent({
+      author: context.agent.name,
+      invocationId: context.invocationId,
+      content: agg.parts.length > 0 ? createModelContent([...agg.parts]) : void 0,
+      customMetadata: agg.customMeta,
+      groundingMetadata: agg.grounding,
+      citationMetadata: agg.citations,
+      usageMetadata: agg.usage,
+      turnComplete: false,
+      partial: false
+    });
+    return result;
+  }
+  promoteTextBlocksToParts(agg) {
+    if (agg.aggregatedThoughts !== "") {
+      agg.parts.push({ thought: true, text: agg.aggregatedThoughts });
+      agg.aggregatedThoughts = "";
+    }
+    if (agg.aggregatedText !== "") {
+      agg.parts.push({ text: agg.aggregatedText });
+      agg.aggregatedText = "";
+    }
+  }
+  /**
+   * Adds request and response metadata to the event.
+   */
+  updateCustomMetadata(event, response) {
+    const toAdd = {};
+    if (this.request && event.turnComplete) {
+      toAdd["request"] = this.request;
+    }
+    if (response) {
+      toAdd["response"] = response;
+    }
+    if (Object.keys(toAdd).length === 0) {
+      return;
+    }
+    if (!event.customMetadata) {
+      event.customMetadata = {};
+    }
+    for (const [k, v] of Object.entries(toAdd)) {
+      if (v === void 0 || v === null) continue;
+      event.customMetadata["a2a:".concat(k)] = v;
+    }
+  }
+}
+export {
+  A2ARemoteAgentRunProcessor
+};

package/dist/web/a2a/a2a_remote_agent_utils.js

@@ -0,0 +1,131 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createEvent } from "../events/event.js";
+import { AdkMetadataKeys } from "./metadata_converter_utils.js";
+import { toA2AParts } from "./part_converter_utils.js";
+function getUserFunctionCallAt(session, index) {
+  const events = session.events;
+  if (index < 0 || index >= events.length) {
+    return void 0;
+  }
+  const candidate = events[index];
+  if (candidate.author !== "user") {
+    return void 0;
+  }
+  const fnCallId = getFunctionResponseCallId(candidate);
+  if (!fnCallId) {
+    return void 0;
+  }
+  for (let i = index - 1; i >= 0; i--) {
+    const request = events[i];
+    if (!isFunctionCallEvent(request, fnCallId)) {
+      continue;
+    }
+    const metadata = request.customMetadata || {};
+    const taskId = metadata[AdkMetadataKeys.TASK_ID] || "";
+    const contextId = metadata[AdkMetadataKeys.CONTEXT_ID] || "";
+    return {
+      response: candidate,
+      taskId,
+      contextId
+    };
+  }
+  return void 0;
+}
+function isFunctionCallEvent(event, callId) {
+  if (!event || !event.content || !event.content.parts) {
+    return false;
+  }
+  return event.content.parts.some(
+    (part) => part.functionCall && part.functionCall.id === callId
+  );
+}
+function getFunctionResponseCallId(event) {
+  var _a;
+  if (!event || !event.content || !event.content.parts) {
+    return void 0;
+  }
+  const responsePart = event.content.parts.find(
+    (part) => part.functionResponse
+  );
+  return (_a = responsePart == null ? void 0 : responsePart.functionResponse) == null ? void 0 : _a.id;
+}
+function toMissingRemoteSessionParts(ctx, session) {
+  const events = session.events;
+  let contextId = void 0;
+  let lastRemoteResponseIndex = -1;
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i];
+    if (event.author === ctx.agent.name) {
+      lastRemoteResponseIndex = i;
+      const metadata = event.customMetadata || {};
+      contextId = metadata[AdkMetadataKeys.CONTEXT_ID];
+      break;
+    }
+  }
+  const missingParts = [];
+  for (let i = lastRemoteResponseIndex + 1; i < events.length; i++) {
+    let event = events[i];
+    if (event.author !== "user" && event.author !== ctx.agent.name) {
+      event = presentAsUserMessage(ctx, event);
+    }
+    if (!event.content || !event.content.parts || event.content.parts.length === 0) {
+      continue;
+    }
+    const parts = toA2AParts(event.content.parts, event.longRunningToolIds);
+    missingParts.push(...parts);
+  }
+  return {
+    parts: missingParts,
+    contextId
+  };
+}
+function presentAsUserMessage(ctx, agentEvent) {
+  const event = createEvent({
+    author: "user",
+    invocationId: ctx.invocationId
+  });
+  if (!agentEvent.content || !agentEvent.content.parts) {
+    return event;
+  }
+  const parts = [{ text: "For context:" }];
+  for (const part of agentEvent.content.parts) {
+    if (part.thought) {
+      continue;
+    }
+    if (part.text) {
+      parts.push({
+        text: "[".concat(agentEvent.author, "] said: ").concat(part.text)
+      });
+    } else if (part.functionCall) {
+      const call = part.functionCall;
+      parts.push({
+        text: "[".concat(agentEvent.author, "] called tool ").concat(call.name, " with parameters: ").concat(JSON.stringify(call.args))
+      });
+    } else if (part.functionResponse) {
+      const resp = part.functionResponse;
+      parts.push({
+        text: "[".concat(agentEvent.author, "] ").concat(resp.name, " tool returned result: ").concat(JSON.stringify(resp.response))
+      });
+    } else {
+      parts.push(part);
+    }
+  }
+  if (parts.length > 1) {
+    event.content = {
+      role: "user",
+      parts
+    };
+  }
+  return event;
+}
+export {
+  getFunctionResponseCallId,
+  getUserFunctionCallAt,
+  isFunctionCallEvent,
+  presentAsUserMessage,
+  toMissingRemoteSessionParts
+};

package/dist/web/a2a/agent_card.js

@@ -0,0 +1,340 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DefaultAgentCardResolver } from "@a2a-js/sdk/client";
+import * as fs from "node:fs/promises";
+import {
+  InvocationContext
+} from "../agents/invocation_context.js";
+import { isLlmAgent } from "../agents/llm_agent.js";
+import { isLoopAgent } from "../agents/loop_agent.js";
+import { isParallelAgent } from "../agents/parallel_agent.js";
+import { ReadonlyContext } from "../agents/readonly_context.js";
+import { isSequentialAgent } from "../agents/sequential_agent.js";
+import { isBaseTool } from "../tools/base_tool.js";
+import { isBaseToolset } from "../tools/base_toolset.js";
+import { logger } from "../utils/logger.js";
+async function resolveAgentCard(agentCard) {
+  if (typeof agentCard === "object") {
+    return agentCard;
+  }
+  const source = agentCard;
+  if (source.startsWith("http://") || source.startsWith("https://")) {
+    const resolver = new DefaultAgentCardResolver();
+    return await resolver.resolve(source);
+  }
+  try {
+    const content = await fs.readFile(source, "utf-8");
+    return JSON.parse(content);
+  } catch (err) {
+    throw new Error(
+      "Failed to read agent card from file ".concat(source, ": ").concat(err.message)
+    );
+  }
+}
+async function getA2AAgentCard(agent, transports) {
+  return {
+    name: agent.name,
+    description: agent.description || "",
+    protocolVersion: "0.3.0",
+    version: "1.0.0",
+    skills: await buildAgentSkills(agent),
+    url: transports[0].url,
+    preferredTransport: transports[0].transport,
+    capabilities: {
+      extensions: [],
+      stateTransitionHistory: false,
+      pushNotifications: false,
+      streaming: true
+    },
+    defaultInputModes: ["text"],
+    defaultOutputModes: ["text"],
+    additionalInterfaces: transports
+  };
+}
+async function buildAgentSkills(agent) {
+  const [primarySkills, subAgentSkills] = await Promise.all([
+    buildPrimarySkills(agent),
+    buildSubAgentSkills(agent)
+  ]);
+  return [...primarySkills, ...subAgentSkills];
+}
+async function buildPrimarySkills(agent) {
+  if (isLlmAgent(agent)) {
+    return buildLLMAgentSkills(agent);
+  }
+  return buildNonLLMAgentSkills(agent);
+}
+async function buildSubAgentSkills(agent) {
+  const subAgents = agent.subAgents;
+  const result = [];
+  for (const sub of subAgents) {
+    const skills = await buildPrimarySkills(sub);
+    for (const subSkill of skills) {
+      const skill = {
+        id: "".concat(sub.name, "_").concat(subSkill.id),
+        name: "".concat(sub.name, ": ").concat(subSkill.name),
+        description: subSkill.description,
+        tags: ["sub_agent:".concat(sub.name), ...subSkill.tags]
+      };
+      result.push(skill);
+    }
+  }
+  return result;
+}
+async function buildLLMAgentSkills(agent) {
+  const skills = [
+    {
+      id: agent.name,
+      name: "model",
+      description: await buildDescriptionFromInstructions(agent),
+      tags: ["llm"]
+    }
+  ];
+  if (agent.tools && agent.tools.length > 0) {
+    for (const toolUnion of agent.tools) {
+      if (isBaseTool(toolUnion)) {
+        skills.push(toolToSkill(agent.name, toolUnion));
+      } else if (isBaseToolset(toolUnion)) {
+        const tools = await toolUnion.getTools();
+        for (const tool of tools) {
+          skills.push(toolToSkill(agent.name, tool));
+        }
+      }
+    }
+  }
+  return skills;
+}
+function toolToSkill(prefix, tool) {
+  let description = tool.description;
+  if (!description) {
+    description = "Tool: ".concat(tool.name);
+  }
+  return {
+    id: "".concat(prefix, "-").concat(tool.name),
+    name: tool.name,
+    description,
+    tags: ["llm", "tools"]
+  };
+}
+function buildNonLLMAgentSkills(agent) {
+  const skills = [
+    {
+      id: agent.name,
+      name: getAgentSkillName(agent),
+      description: buildAgentDescription(agent),
+      tags: [getAgentTypeTag(agent)]
+    }
+  ];
+  const subAgents = agent.subAgents;
+  if (subAgents.length > 0) {
+    const descriptions = subAgents.map(
+      (sub) => sub.description || "No description"
+    );
+    skills.push({
+      id: "".concat(agent.name, "-sub-agents"),
+      name: "sub-agents",
+      description: "Orchestrates: ".concat(descriptions.join("; ")),
+      tags: [getAgentTypeTag(agent), "orchestration"]
+    });
+  }
+  return skills;
+}
+function buildAgentDescription(agent) {
+  const descriptionParts = [];
+  if (agent.description) {
+    descriptionParts.push(agent.description);
+  }
+  if (agent.subAgents.length > 0) {
+    if (isLoopAgent(agent)) {
+      descriptionParts.push(buildLoopAgentDescription(agent));
+    } else if (isParallelAgent(agent)) {
+      descriptionParts.push(buildParallelAgentDescription(agent));
+    } else if (isSequentialAgent(agent)) {
+      descriptionParts.push(buildSequentialAgentDescription(agent));
+    }
+  }
+  if (descriptionParts.length > 0) {
+    return descriptionParts.join(" ");
+  } else {
+    return getDefaultAgentDescription(agent);
+  }
+}
+function buildSequentialAgentDescription(agent) {
+  const subAgents = agent.subAgents;
+  const descriptions = [];
+  subAgents.forEach((sub, i) => {
+    let subDescription = sub.description;
+    if (!subDescription) {
+      subDescription = "execute the ".concat(sub.name, " agent");
+    }
+    if (i === 0) {
+      descriptions.push("First, this agent will ".concat(subDescription, "."));
+    } else if (i === subAgents.length - 1) {
+      descriptions.push("Finally, this agent will ".concat(subDescription, "."));
+    } else {
+      descriptions.push("Then, this agent will ".concat(subDescription, "."));
+    }
+  });
+  return descriptions.join(" ");
+}
+function buildParallelAgentDescription(agent) {
+  const subAgents = agent.subAgents;
+  const descriptions = [];
+  subAgents.forEach((sub, i) => {
+    let subDescription = sub.description;
+    if (!subDescription) {
+      subDescription = "execute the ".concat(sub.name, " agent");
+    }
+    if (i === 0) {
+      descriptions.push("This agent will ".concat(subDescription));
+    } else if (i === subAgents.length - 1) {
+      descriptions.push("and ".concat(subDescription));
+    } else {
+      descriptions.push(", ".concat(subDescription));
+    }
+  });
+  return "".concat(descriptions.join(" "), " simultaneously.");
+}
+function buildLoopAgentDescription(agent) {
+  const maxIterationsVal = agent.maxIterations;
+  let maxIterations = "unlimited";
+  if (typeof maxIterationsVal === "number" && maxIterationsVal < Number.MAX_SAFE_INTEGER) {
+    maxIterations = maxIterationsVal.toString();
+  }
+  const subAgents = agent.subAgents;
+  const descriptions = [];
+  subAgents.forEach((sub, i) => {
+    let subDescription = sub.description;
+    if (!subDescription) {
+      subDescription = "execute the ".concat(sub.name, " agent");
+    }
+    if (i === 0) {
+      descriptions.push("This agent will ".concat(subDescription));
+    } else if (i === subAgents.length - 1) {
+      descriptions.push("and ".concat(subDescription));
+    } else {
+      descriptions.push(", ".concat(subDescription));
+    }
+  });
+  return "".concat(descriptions.join(" "), " in a loop (max ").concat(maxIterations, " iterations).");
+}
+async function buildDescriptionFromInstructions(agent) {
+  const descriptionParts = [];
+  if (agent.description) {
+    descriptionParts.push(agent.description);
+  }
+  if (agent.instruction) {
+    let instructionStr;
+    if (typeof agent.instruction === "function") {
+      const dummyContext = new ReadonlyContext(
+        new InvocationContext({
+          agent
+        })
+      );
+      try {
+        instructionStr = await agent.instruction(dummyContext);
+      } catch (e) {
+        logger.warn("Failed to resolve dynamic instruction for AgentCard", e);
+        instructionStr = "";
+      }
+    } else {
+      instructionStr = agent.instruction;
+    }
+    if (instructionStr) {
+      descriptionParts.push(replacePronouns(instructionStr));
+    }
+  }
+  const root = agent.rootAgent;
+  if (isLlmAgent(root) && root.globalInstruction) {
+    let globalInstructionStr;
+    if (typeof root.globalInstruction === "function") {
+      const dummyContext = new ReadonlyContext(
+        new InvocationContext({
+          agent
+        })
+      );
+      try {
+        globalInstructionStr = await root.globalInstruction(dummyContext);
+      } catch (e) {
+        logger.warn(
+          "Failed to resolve dynamic global instruction for AgentCard",
+          e
+        );
+        globalInstructionStr = "";
+      }
+    } else {
+      globalInstructionStr = root.globalInstruction;
+    }
+    if (globalInstructionStr) {
+      descriptionParts.push(replacePronouns(globalInstructionStr));
+    }
+  }
+  if (descriptionParts.length > 0) {
+    return descriptionParts.join(" ");
+  } else {
+    return getDefaultAgentDescription(agent);
+  }
+}
+function replacePronouns(instruction) {
+  const substitutions = [
+    { original: "you were", target: "I was" },
+    { original: "you are", target: "I am" },
+    { original: "you're", target: "I am" },
+    { original: "you've", target: "I have" },
+    { original: "yours", target: "mine" },
+    { original: "your", target: "my" },
+    { original: "you", target: "I" }
+  ];
+  let result = instruction;
+  for (const sub of substitutions) {
+    const pattern = new RegExp("\\b".concat(sub.original, "\\b"), "gi");
+    result = result.replace(pattern, sub.target);
+  }
+  return result;
+}
+function getDefaultAgentDescription(agent) {
+  if (isLoopAgent(agent)) {
+    return "A loop workflow agent";
+  } else if (isSequentialAgent(agent)) {
+    return "A sequential workflow agent";
+  } else if (isParallelAgent(agent)) {
+    return "A parallel workflow agent";
+  } else if (isLlmAgent(agent)) {
+    return "An LLM-based agent";
+  } else {
+    return "A custom agent";
+  }
+}
+function getAgentTypeTag(agent) {
+  if (isLoopAgent(agent)) {
+    return "loop_workflow";
+  } else if (isSequentialAgent(agent)) {
+    return "sequential_workflow";
+  } else if (isParallelAgent(agent)) {
+    return "parallel_workflow";
+  } else if (isLlmAgent(agent)) {
+    return "llm_agent";
+  } else {
+    return "custom_agent";
+  }
+}
+function getAgentSkillName(agent) {
+  if (isLlmAgent(agent)) {
+    return "model";
+  }
+  if (isWorkflowAgent(agent)) {
+    return "workflow";
+  }
+  return "custom";
+}
+function isWorkflowAgent(agent) {
+  return isLoopAgent(agent) || isSequentialAgent(agent) || isParallelAgent(agent);
+}
+export {
+  buildAgentSkills,
+  getA2AAgentCard,
+  resolveAgentCard
+};