---
title: "Google ADK JavaScript 快速开始"
description: "在 AG-UI 端点后运行原生 Google ADK JavaScript 智能体。"
---

> Documentation Index
> Fetch the complete documentation index at: https://ag-ui.ndjp.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Google ADK JavaScript 快速开始

`@ag-ui/adk-js` 把服务端的 Google ADK JavaScript `Runner` 适配为 AG-UI `AbstractAgent`。当智能体与 Web 运行时都跑在 Node.js 中时使用它。现有的 `@ag-ui/adk` 包仍是 Python ADK 中间件的 HTTP 客户端。

## 前置条件

- Node.js 20.19 或更新版本
- `@ag-ui/client` 与 `@ag-ui/core` 1.x（使用能解析到 1.x 的 CopilotKit 版本）
- 来自 [Google AI Studio](https://aistudio.google.com/apikey) 的 Gemini API key

## 将 ADK JavaScript 添加到应用

安装服务端依赖：

```bash
npm install @ag-ui/adk-js @google/adk @copilotkit/runtime hono
```

`@ag-ui/adk-js` 需要 `@google/adk` 2.x。

在服务端读取的环境变量中设置 Gemini key：

```dotenv
GOOGLE_GENAI_API_KEY=your-api-key
GOOGLE_GENAI_USE_VERTEXAI=0
```

创建 `app/api/copilotkit/route.ts`：

```ts
import { ADKJSAgent } from "@ag-ui/adk-js"
import {
  CopilotRuntime,
  InMemoryAgentRunner,
  createCopilotEndpointSingleRoute,
} from "@copilotkit/runtime/v2"
import { Agent, InMemorySessionService } from "@google/adk"
import { handle } from "hono/vercel"

export const runtime = "nodejs"

const rootAgent = new Agent({
  name: "assistant",
  model: "gemini-2.5-flash",
  instruction: "Be concise and use frontend tools when appropriate.",
})

const copilotRuntime = new CopilotRuntime({
  agents: {
    assistant: new ADKJSAgent({
      appName: "assistant_app",
      sessionService: new InMemorySessionService(),
      agent: rootAgent,
      userId: "user-123", // 从服务端鉴权解析
    }),
  },
  runner: new InMemoryAgentRunner(),
})

const endpoint = createCopilotEndpointSingleRoute({
  runtime: copilotRuntime,
  basePath: "/api/copilotkit",
})

export const POST = handle(endpoint)
```

前端现在可以通过任意 AG-UI 客户端选择 `assistant` 智能体。CopilotKit React 应用在其 `CopilotKit` provider 上使用 `runtimeUrl="/api/copilotkit"` 与 `agent="assistant"`。

## 运行与并发

不同线程在共享的智能体实例上并发运行；同一用户与线程上的第二次运行会以 `THREAD_BUSY` 被拒绝。ADK 在每次运行后关闭每个 toolset，因此对共享可关闭 toolset 的根智能体（或需要每次运行独立状态时），使用工厂为每次运行提供实例（`agent: () => new Workflow(...)`），或传入 `runner:` 以提供完整配置的 Runner。客户端断开后的失败会交给 `logger`（默认 `console`）。

## 支持的集成行为

- 流式助手消息与生命周期事件
- 后端与前端工具调用
- AG-UI 状态快照与 RFC 6902 状态增量
- ADK 的输入、确认与凭据请求作为可恢复中断。运行时自行抛出确认的工具还必须从 `checkRequireConfirmation` 返回 `true`（或在 `FunctionTool` 上声明 `requireConfirmation`），因为 ADK 2.x 会把审批绑定到它所命名的工具
- 恢复的消息历史与稳定消息 ID
- ADK 报告时的提供商/模型 token 用量
- 裸 ADK `Workflow` 作为 `Runner` 根（其工作流节点作为子智能体报告，并发现其前端工具）
- 面向 ADK 多智能体树的 AG-UI 子智能体协议（见下文）

该集成**仅限服务端**。绝不要从浏览器组件导入 `@ag-ui/adk-js` 或 `@google/adk`。工具、共享状态、生成式 UI 与中断的在线示例见 [Dojo](https://dojo.ag-ui.com/adk-js/feature/agentic_chat?openCopilot=true)。

## 子智能体

- `subagents: "steps"`：在 ADK 子智能体工作前后发射 `STEP_STARTED`/`STEP_FINISHED`（`agent:<name>`）与 `CUSTOM` 的 `MultiAgentHandoff` 事件——对所有客户端安全，也是 Dojo 多智能体页面读取的内容
- `subagents: "attributed"`：额外启用 AG-UI 子智能体协议（`SUBAGENT_STARTED/FINISHED/ERROR`、事件/消息/中断上的 `subagentRunId`、恢复时同一 id 下继续挂起的子智能体）；消费客户端需要 `@ag-ui/client` 1.x，因为旧客户端会在任何应用代码运行前拒绝这些事件类型
- 默认值为 `off`

## 相关页面

- [生态与集成](https://ag-ui.ndjp.net/integrations/)
- [子智能体](https://ag-ui.ndjp.net/concepts/subagents/)
- [中断](https://ag-ui.ndjp.net/concepts/interrupts/)

Source: https://ag-ui.ndjp.net/integrations/google-adk-js/index.mdx
