@ag-ui/adk-js adapts a server-side Google ADK JavaScript Runner to an AG-UI
AbstractAgent. Use it when the agent and web runtime run in Node.js. The
existing @ag-ui/adk package remains the HTTP client for the Python ADK
middleware.
Prerequisites
- Node.js 20.19 or newer
@ag-ui/clientand@ag-ui/core1.x (use a CopilotKit release that resolves the 1.x line)- A Gemini API key from Google AI Studio
Add ADK JavaScript to an application
Install the server dependencies:@ag-ui/adk-js requires @google/adk 2.x.
Set your Gemini key in the environment the server reads:
app/api/copilotkit/route.ts:
assistant agent through any AG-UI client. A
CopilotKit React application uses runtimeUrl="/api/copilotkit" and
agent="assistant" on its CopilotKit provider.
Runs and concurrency
Different threads run concurrently on one shared agent instance; a second run on the same user and thread is refused withTHREAD_BUSY. ADK closes every
toolset after each run, so give roots that share a closable toolset (or keep
per-run state) per-run instances with a factory
(agent: () => new Workflow(...)), or pass runner: to bring a fully
configured Runner. Failures after the client disconnected go to logger
(default console).
Supported integration behavior
- Streaming assistant messages and lifecycle events
- Backend and frontend tool calls
- AG-UI state snapshots and RFC 6902 state deltas
- ADK input, confirmation, and credential requests as resumable interrupts.
A tool that raises its own confirmation at runtime must also answer
truefromcheckRequireConfirmation(or declarerequireConfirmationon aFunctionTool), because ADK 2.x binds an approval to the tool it names. - Restored message history with stable message IDs
- Provider/model token usage when ADK reports it
- A bare ADK
Workflowas theRunnerroot (its workflow nodes are reported as sub-agents and their frontend tools are discovered) - The AG-UI subagent protocol for ADK multi-agent trees (see below)
@ag-ui/adk-js or @google/adk
from a browser component. See the
live Dojo examples
for tools, shared state, generative UI, and interrupts.
Sub-agents
subagents: "steps" emits STEP_STARTED / STEP_FINISHED (agent:<name>) and
CUSTOM MultiAgentHandoff events around ADK sub-agent work — safe for every
client and what the Dojo multi-agent page reads. subagents: "attributed" adds
the AG-UI subagent protocol (SUBAGENT_STARTED/FINISHED/ERROR, subagentRunId
on events, messages, and interrupts, continuation of a suspended sub-agent under
the same id on resume); the consuming client needs @ag-ui/client 1.x,
because older clients reject those event types before any application code
runs. The default is off.