跳到主要内容

Google ADK JavaScript 快速开始

在 AG-UI 端点后运行原生 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 的 Gemini API key

将 ADK JavaScript 添加到应用

安装服务端依赖:

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

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

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

GOOGLE_GENAI_API_KEY=your-api-key
GOOGLE_GENAI_USE_VERTEXAI=0

创建 app/api/copilotkit/route.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。

子智能体

  • 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

相关页面

Type to search…

↑↓ navigate↵ selectEsc close