Agent Development Kit (ADK) JS

Agent Development Kit (ADK) is an open-source, code-first TypeScript toolkit for building, evaluating, and deploying sophisticated AI agents. It is designed for both Node.js and browser environments, offering full type safety and Zod schema validation.

Key Capabilities:

• Multi-Agent Orchestration: Compose agents into sequential, parallel, loop, and routed workflows, or delegate to remote agents via the A2A protocol.
• Rich Tool Ecosystem: Includes built-in tools (Google Search, Google Maps, Vertex AI Search) and supports connecting MCP servers or wrapping any function as a tool.
• Deployment: Supports deployment to various environments, including Google Cloud Run via adk deploy cloud_run.

ADK TS provides mechanisms to manage agent state and prevent history leakage between runs:

• runEphemeral: Use this helper for temporary session creation. It ensures a clean slate for each run while allowing you to pass an initial stateDelta.
• Resumable Invocations: You can hydrate agent state from persisted sessions to support multi-turn conversations across separate execution instances (e.g., across different CLI calls).

To implement safety mechanisms where sensitive tool operations require user consent, use the Runner's confirmation callback mechanism:

1. Configure a Confirmation Callback: Provide a callback to the Runner to handle tool approval requests.
2. Handle Tool Confirmation Events: When a tool requires confirmation, the Runner yields a tool confirmation request event.
3. Suspend Execution: CRITICAL: The host application must explicitly suspend or exit the agent loop after yielding the confirmation event to return control to the user.
4. Resume Execution: Once the user provides approval, the host application resumes the agent execution with the result.

Once your agent is defined, you can test and debug it using the provided CLI commands from your agent project directory.

• Interactive CLI: Use npx adk run <file> to run an agent file interactively.
• Web UI: Use npx adk web to launch a development UI designed for testing and debugging agent workflows and function calls.

# Interactive CLI
npx adk run agent.ts

# Web UI
npx adk web

To use ADK in your TypeScript project, install the core SDK and the dev tools (CLI and dev UI) as a development dependency.

Prerequisite: Requires a current Node.js LTS release.

Using npm:

npm install @google/adk
npm install -D @google/adk-devtools

Using yarn:

yarn add @google/adk
yarn add -D @google/adk-devtools

To use the inputFile option in runAgent, provide a JSON file that follows this structure. This allows you to automate a sequence of queries and pre-set the agent's state.

{
  "state": {
    "key": "value"
  },
  "queries": [
    "Hello, agent!",
    "What is the current state?"
  ]
}

interface InputFile {
  state: Record<string, unknown>;
  queries: string[];
}

Session resumption allows an agent workflow to continue across tool boundaries or Long Running Operations (LROs). The Runner uses determineAgentForResumption to decide which agent should handle the next step in a session.

Resumption Logic:

1. Function Response Resumption: If the last event in a session is a function response and resumabilityConfig.isResumable is enabled, the Runner attempts to find the agent that originally made the function call.
2. Transferable Agent Scan: If Case 1 doesn't apply, the Runner scans the session events in reverse order to find the last agent that emitted a message. An agent is considered "routable" (transferable) if:
   • It is an instance of LlmAgent.
   • All its ancestors have disallowTransferToParent set to false.
3. Fallback: If no suitable agent is found, it defaults to the rootAgent.

A LongRunningFunctionTool is used for tasks that do not complete immediately (e.g., requiring human approval). Unlike a standard FunctionTool, its execute method can return a pending status.

Example of an approval tool:

import { LongRunningFunctionTool } from '@google/adk';
import { z } from 'zod';

export const askForApproval = new LongRunningFunctionTool({
  name: 'ask_for_approval',
  description: 'Ask for approval for the reimbursement.',
  parameters: z.object({
    purpose: z.string(),
    amount: z.number(),
  }),
  execute: ({purpose, amount}, context) => {
    return {
      status: 'pending',
      amount: amount,
      ticketId: 'reimbursement-ticket-001',
    };
  },
});

Callbacks allow you to intercept agent execution to modify state or inject content.

• Before Agent Callbacks: Executed before the agent processes a request. They can modify the Context.state or return Content to provide a direct response to the user, effectively short-circuiting the agent.
• After Agent Callbacks: Executed after the agent has finished its turn. These are useful for post-processing or logging.

Callbacks follow the SingleAgentCallback signature and receive a Context object. Returning Content (from @google/genai) allows you to provide a model-like response immediately.

The ADK uses StructuredEvent to represent the various types of output an agent can produce during a turn. When consuming an event stream, you can use the EventType enum to distinguish between different categories of information.

Common event types include:

• THOUGHT: A reasoning trace emitted by the model.
• CONTENT: Text deltas intended for the end user.
• TOOL_CALL: A request to execute a tool (function call).
• TOOL_RESULT: The result returned by a tool execution.
• CALL_CODE: A request to execute code.
• CODE_RESULT: The result of code execution.
• ERROR: A runtime error signaled via event.errorCode.
• ACTIVITY: A generic status update.
• TOOL_CONFIRMATION: A request for the user to confirm tool calls.
• FINISHED: Indicates the agent has completed its task for the current turn.