@google/adk 0.4.0 → 0.6.0

package/dist/esm/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 ${source}: ${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: `${sub.name}_${subSkill.id}`,
+        name: `${sub.name}: ${subSkill.name}`,
+        description: subSkill.description,
+        tags: [`sub_agent:${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: ${tool.name}`;
+  }
+  return {
+    id: `${prefix}-${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: `${agent.name}-sub-agents`,
+      name: "sub-agents",
+      description: `Orchestrates: ${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 ${sub.name} agent`;
+    }
+    if (i === 0) {
+      descriptions.push(`First, this agent will ${subDescription}.`);
+    } else if (i === subAgents.length - 1) {
+      descriptions.push(`Finally, this agent will ${subDescription}.`);
+    } else {
+      descriptions.push(`Then, this agent will ${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 ${sub.name} agent`;
+    }
+    if (i === 0) {
+      descriptions.push(`This agent will ${subDescription}`);
+    } else if (i === subAgents.length - 1) {
+      descriptions.push(`and ${subDescription}`);
+    } else {
+      descriptions.push(`, ${subDescription}`);
+    }
+  });
+  return `${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 ${sub.name} agent`;
+    }
+    if (i === 0) {
+      descriptions.push(`This agent will ${subDescription}`);
+    } else if (i === subAgents.length - 1) {
+      descriptions.push(`and ${subDescription}`);
+    } else {
+      descriptions.push(`, ${subDescription}`);
+    }
+  });
+  return `${descriptions.join(" ")} in a loop (max ${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${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
+};

package/dist/esm/a2a/agent_executor.js

@@ -0,0 +1,202 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { isRunner, Runner } from "../runner/runner.js";
+import { randomUUID } from "../utils/env_aware_utils.js";
+import { logger } from "../utils/logger.js";
+import {
+  createTask,
+  createTaskArtifactUpdateEvent,
+  createTaskFailedEvent,
+  createTaskWorkingEvent
+} from "./a2a_event.js";
+import {
+  getFinalTaskStatusUpdate,
+  getTaskInputRequiredEvent
+} from "./event_processor_utils.js";
+import { createExecutorContext } from "./executor_context.js";
+import {
+  getA2AEventMetadata,
+  getA2ASessionMetadata
+} from "./metadata_converter_utils.js";
+import { toA2AParts, toGenAIContent } from "./part_converter_utils.js";
+class A2AAgentExecutor {
+  constructor(config) {
+    this.config = config;
+    this.agentPartialArtifactIdsMap = {};
+  }
+  async execute(ctx, eventBus) {
+    var _a, _b;
+    const a2aUserMessage = ctx.userMessage;
+    if (!a2aUserMessage) {
+      throw new Error("message not provided");
+    }
+    const userId = `A2A_USER_${ctx.contextId}`;
+    const sessionId = ctx.contextId;
+    const genAIUserMessage = toGenAIContent(a2aUserMessage);
+    const adkRunner = await getAdkRunner(this.config.runner);
+    const session = await getAdkSession(
+      userId,
+      sessionId,
+      adkRunner.sessionService,
+      adkRunner.appName
+    );
+    const executorContext = createExecutorContext({
+      session,
+      userContent: genAIUserMessage,
+      requestContext: ctx
+    });
+    try {
+      if (this.config.beforeExecuteCallback) {
+        await this.config.beforeExecuteCallback(ctx);
+      }
+      if (ctx.task) {
+        const inputRequiredEvent = getTaskInputRequiredEvent(
+          ctx.task,
+          genAIUserMessage
+        );
+        if (inputRequiredEvent) {
+          await this.publishFinalTaskStatus({
+            executorContext,
+            eventBus,
+            event: inputRequiredEvent
+          });
+          return;
+        }
+      }
+      if (!ctx.task) {
+        eventBus.publish(
+          createTask({
+            taskId: ctx.taskId,
+            contextId: ctx.contextId,
+            message: a2aUserMessage
+          })
+        );
+      }
+      eventBus.publish(
+        createTaskWorkingEvent({
+          taskId: ctx.taskId,
+          contextId: ctx.contextId
+        })
+      );
+      const adkEvents = [];
+      for await (const adkEvent of adkRunner.runAsync({
+        userId,
+        sessionId,
+        newMessage: genAIUserMessage,
+        runConfig: this.config.runConfig
+      })) {
+        adkEvents.push(adkEvent);
+        const a2aEvent = this.convertAdkEventToA2AEvent(
+          adkEvent,
+          executorContext
+        );
+        if (!a2aEvent) {
+          continue;
+        }
+        await ((_b = (_a = this.config).afterEventCallback) == null ? void 0 : _b.call(
+          _a,
+          executorContext,
+          adkEvent,
+          a2aEvent
+        ));
+        eventBus.publish(a2aEvent);
+      }
+      await this.publishFinalTaskStatus({
+        executorContext,
+        eventBus,
+        event: getFinalTaskStatusUpdate(adkEvents, executorContext)
+      });
+    } catch (e) {
+      const error = e;
+      await this.publishFinalTaskStatus({
+        executorContext,
+        eventBus,
+        error,
+        event: createTaskFailedEvent({
+          taskId: ctx.taskId,
+          contextId: ctx.contextId,
+          error: new Error(`Agent run failed: ${error.message}`),
+          metadata: getA2ASessionMetadata(executorContext)
+        })
+      });
+    }
+  }
+  // Task cancellation is not supported in this implementation yet.
+  async cancelTask(_taskId) {
+    throw new Error("Task cancellation is not supported yet.");
+  }
+  convertAdkEventToA2AEvent(adkEvent, executorContext) {
+    var _a;
+    const a2aParts = toA2AParts(
+      (_a = adkEvent.content) == null ? void 0 : _a.parts,
+      adkEvent.longRunningToolIds
+    );
+    if (a2aParts.length === 0) {
+      return void 0;
+    }
+    const artifactId = this.agentPartialArtifactIdsMap[adkEvent.author] || randomUUID();
+    const a2aEvent = createTaskArtifactUpdateEvent({
+      taskId: executorContext.requestContext.taskId,
+      contextId: executorContext.requestContext.contextId,
+      artifactId,
+      parts: a2aParts,
+      metadata: getA2AEventMetadata(adkEvent, executorContext),
+      append: adkEvent.partial,
+      lastChunk: !adkEvent.partial
+    });
+    if (adkEvent.partial) {
+      this.agentPartialArtifactIdsMap[adkEvent.author] = artifactId;
+    } else {
+      delete this.agentPartialArtifactIdsMap[adkEvent.author];
+    }
+    return a2aEvent;
+  }
+  /**
+   * Writes the final status event to the queue.
+   */
+  async publishFinalTaskStatus({
+    executorContext,
+    eventBus,
+    event,
+    error
+  }) {
+    var _a, _b;
+    try {
+      await ((_b = (_a = this.config).afterExecuteCallback) == null ? void 0 : _b.call(_a, executorContext, event, error));
+    } catch (e) {
+      logger.error("Error in afterExecuteCallback:", e);
+    }
+    eventBus.publish(event);
+  }
+}
+async function getAdkSession(userId, sessionId, sessionService, appName) {
+  const session = await sessionService.getSession({
+    appName,
+    userId,
+    sessionId
+  });
+  if (session) {
+    return session;
+  }
+  return sessionService.createSession({
+    appName,
+    userId,
+    sessionId
+  });
+}
+async function getAdkRunner(runnerOrConfig) {
+  if (typeof runnerOrConfig === "function") {
+    const result = await runnerOrConfig();
+    return getAdkRunner(result);
+  }
+  if (isRunner(runnerOrConfig)) {
+    return runnerOrConfig;
+  }
+  return new Runner(runnerOrConfig);
+}
+export {
+  A2AAgentExecutor
+};

package/dist/esm/a2a/agent_to_a2a.js

@@ -0,0 +1,80 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AGENT_CARD_PATH } from "@a2a-js/sdk";
+import { DefaultRequestHandler, InMemoryTaskStore } from "@a2a-js/sdk/server";
+import {
+  agentCardHandler,
+  jsonRpcHandler,
+  restHandler,
+  UserBuilder
+} from "@a2a-js/sdk/server/express";
+import express from "express";
+import { StreamingMode } from "../agents/run_config.js";
+import { InMemorySessionService } from "../sessions/in_memory_session_service.js";
+import { getA2AAgentCard, resolveAgentCard } from "./agent_card.js";
+import { A2AAgentExecutor } from "./agent_executor.js";
+async function toA2a(agent, options = {}) {
+  var _a, _b, _c, _d;
+  const host = (_a = options.host) != null ? _a : "localhost";
+  const port = (_b = options.port) != null ? _b : 8e3;
+  const protocol = (_c = options.protocol) != null ? _c : "http";
+  const basePath = options.basePath || "";
+  const rpcUrl = `${protocol}://${host}:${port}${basePath}`;
+  const agentCard = options.agentCard ? await resolveAgentCard(options.agentCard) : await getA2AAgentCard(agent, [
+    {
+      url: `${rpcUrl}/jsonrpc`,
+      transport: "JSONRPC"
+    },
+    {
+      url: `${rpcUrl}/rest`,
+      transport: "HTTP+JSON"
+    }
+  ]);
+  const agentExecutor = new A2AAgentExecutor({
+    runner: options.runner || {
+      agent,
+      appName: agent.name,
+      sessionService: options.sessionService || new InMemorySessionService(),
+      memoryService: options.memoryService,
+      artifactService: options.artifactService
+    },
+    runConfig: {
+      streamingMode: StreamingMode.SSE
+    }
+  });
+  const requestHandler = new DefaultRequestHandler(
+    agentCard,
+    new InMemoryTaskStore(),
+    agentExecutor
+  );
+  const app = (_d = options.app) != null ? _d : express();
+  if (!options.app) {
+    app.use(express.urlencoded({ limit: "50mb", extended: true }));
+    app.use(express.json({ limit: "50mb" }));
+  }
+  app.use(
+    `${basePath}/${AGENT_CARD_PATH}`,
+    agentCardHandler({ agentCardProvider: requestHandler })
+  );
+  app.use(
+    `${basePath}/rest`,
+    restHandler({
+      requestHandler,
+      userBuilder: UserBuilder.noAuthentication
+    })
+  );
+  app.use(
+    `${basePath}/jsonrpc`,
+    jsonRpcHandler({
+      requestHandler,
+      userBuilder: UserBuilder.noAuthentication
+    })
+  );
+  return app;
+}
+export {
+  toA2a
+};