@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/core1.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/client1.x,因为旧客户端会在任何应用代码运行前拒绝这些事件类型- 默认值为
off