@assistant-ui/mcp-docs-server 0.2.2 → 0.3.0

package/.docs/raw/docs/runtimes/google-adk/hooks.mdx

@@ -1,784 +0,0 @@
----
-title: Hooks
-description: Tool confirmations, auth, input requests, artifacts, escalation, metadata, structured events.
----
-
-Reference for the runtime's React hooks. These expose ADK-specific state and HITL primitives. Start with [quickstart](/docs/runtimes/google-adk/quickstart) if you have not wired up a basic runtime yet.
-
-## Agent and session state
-
-```ts
-import {
-  useAdkAgentInfo,
-  useAdkSessionState,
-  useAdkSend,
-} from "@assistant-ui/react-google-adk";
-
-function MyComponent() {
-  // Current active agent name and branch path (multi-agent)
-  const agentInfo = useAdkAgentInfo();
-  // agentInfo?.name = "search_agent"
-  // agentInfo?.branch = "root.search_agent"
-
-  // Accumulated session state delta
-  const state = useAdkSessionState();
-
-  // Send raw ADK messages programmatically
-  const send = useAdkSend();
-}
-```
-
-## Tool confirmations
-
-When ADK's `SecurityPlugin` or tool callbacks request user confirmation before executing a tool, use `useAdkToolConfirmations` to read pending requests and `useAdkConfirmTool` to respond:
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx
-import {
-  useAdkToolConfirmations,
-  useAdkConfirmTool,
-} from "@assistant-ui/react-google-adk";
-
-function ToolConfirmationUI() {
-  const confirmations = useAdkToolConfirmations();
-  const confirmTool = useAdkConfirmTool();
-
-  if (confirmations.length === 0) return null;
-
-  return confirmations.map((conf) => (
-    <div key={conf.toolCallId}>
-      <p>
-        Tool "{conf.toolName}" wants to run. {conf.hint}
-      </p>
-      <button onClick={() => confirmTool(conf.toolCallId, true)}>Approve</button>
-      <button onClick={() => confirmTool(conf.toolCallId, false)}>Deny</button>
-    </div>
-  ));
-}
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx
-import {
-  useAdkToolConfirmations,
-  useAdkConfirmTool,
-} from "@assistant-ui/react-google-adk";
-import { Pressable, Text, View } from "react-native";
-
-function ToolConfirmationUI() {
-  const confirmations = useAdkToolConfirmations();
-  const confirmTool = useAdkConfirmTool();
-
-  if (confirmations.length === 0) return null;
-
-  return (
-    <View>
-      {confirmations.map((conf) => (
-        <View key={conf.toolCallId}>
-          <Text>
-            Tool "{conf.toolName}" wants to run. {conf.hint}
-          </Text>
-          <Pressable onPress={() => confirmTool(conf.toolCallId, true)}>
-            <Text>Approve</Text>
-          </Pressable>
-          <Pressable onPress={() => confirmTool(conf.toolCallId, false)}>
-            <Text>Deny</Text>
-          </Pressable>
-        </View>
-      ))}
-    </View>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx
-import {
-  useAdkToolConfirmations,
-  useAdkConfirmTool,
-} from "@assistant-ui/react-google-adk";
-import { Box, Text, useInput } from "ink";
-
-function ToolConfirmationUI() {
-  const confirmations = useAdkToolConfirmations();
-  const confirmTool = useAdkConfirmTool();
-  const active = confirmations[0];
-
-  useInput((input) => {
-    if (!active) return;
-    if (input === "y") confirmTool(active.toolCallId, true);
-    if (input === "n") confirmTool(active.toolCallId, false);
-  });
-
-  if (!active) return null;
-
-  return (
-    <Box flexDirection="column">
-      <Text>
-        Tool "{active.toolName}" wants to run. {active.hint}
-      </Text>
-      <Text>Press y to approve, n to deny.</Text>
-    </Box>
-  );
-}
-```
-
-</Tab>
-</PlatformTabs>
-
-## Auth requests
-
-When a tool requires OAuth or other authentication, use `useAdkAuthRequests` to read pending requests and `useAdkSubmitAuth` to submit credentials:
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx
-import {
-  useAdkAuthRequests,
-  useAdkSubmitAuth,
-  type AdkAuthCredential,
-} from "@assistant-ui/react-google-adk";
-
-function AuthUI() {
-  const authRequests = useAdkAuthRequests();
-  const submitAuth = useAdkSubmitAuth();
-
-  if (authRequests.length === 0) return null;
-
-  return authRequests.map((req) => (
-    <div key={req.toolCallId}>
-      <button
-        onClick={() => {
-          const credential: AdkAuthCredential = {
-            authType: "oauth2",
-            oauth2: { accessToken: "..." },
-          };
-          submitAuth(req.toolCallId, credential);
-        }}
-      >
-        Authenticate
-      </button>
-    </div>
-  ));
-}
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx
-import {
-  useAdkAuthRequests,
-  useAdkSubmitAuth,
-  type AdkAuthCredential,
-} from "@assistant-ui/react-google-adk";
-import { Pressable, Text, View } from "react-native";
-
-function AuthUI() {
-  const authRequests = useAdkAuthRequests();
-  const submitAuth = useAdkSubmitAuth();
-
-  if (authRequests.length === 0) return null;
-
-  return (
-    <View>
-      {authRequests.map((req) => (
-        <Pressable
-          key={req.toolCallId}
-          onPress={() => {
-            const credential: AdkAuthCredential = {
-              authType: "oauth2",
-              oauth2: { accessToken: "..." },
-            };
-            submitAuth(req.toolCallId, credential);
-          }}
-        >
-          <Text>Authenticate</Text>
-        </Pressable>
-      ))}
-    </View>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx
-import {
-  useAdkAuthRequests,
-  useAdkSubmitAuth,
-  type AdkAuthCredential,
-} from "@assistant-ui/react-google-adk";
-import { Box, Text, useInput } from "ink";
-
-function AuthUI() {
-  const authRequests = useAdkAuthRequests();
-  const submitAuth = useAdkSubmitAuth();
-  const active = authRequests[0];
-
-  useInput((input) => {
-    if (!active || input !== "a") return;
-    const credential: AdkAuthCredential = {
-      authType: "oauth2",
-      oauth2: { accessToken: "..." },
-    };
-    submitAuth(active.toolCallId, credential);
-  });
-
-  if (!active) return null;
-
-  return (
-    <Box flexDirection="column">
-      <Text>Authentication required for a tool call.</Text>
-      <Text>Press a after completing your auth flow.</Text>
-    </Box>
-  );
-}
-```
-
-</Tab>
-</PlatformTabs>
-
-`AdkAuthCredential` supports all ADK auth types: `apiKey`, `http`, `oauth2`, `openIdConnect`, `serviceAccount`.
-
-## Input requests
-
-When an ADK Python 2.0+ Workflow's `RequestInput` node pauses execution to ask the user a question, ADK emits an `adk_request_input` function call marked as long-running. Respond with `useAdkSubmitInput` inside a tool UI; the helper wraps the answer as `{ result }` to match ADK's `unwrap_response` contract, so the Workflow node resumes with the unwrapped value:
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx
-import type { ToolCallMessagePartComponent } from "@assistant-ui/react";
-import { useAdkSubmitInput } from "@assistant-ui/react-google-adk";
-
-type RequestInputArgs = {
-  interrupt_id?: string;
-  message?: string;
-  payload?: unknown;
-  response_schema?: unknown;
-};
-
-export const RequestInputToolUI: ToolCallMessagePartComponent<
-  RequestInputArgs,
-  unknown
-> = function RequestInputUI({ toolCallId, args, result }) {
-    const submitInput = useAdkSubmitInput();
-
-    if (result !== undefined) {
-      return <p>Answered: {String(result)}</p>;
-    }
-
-    return (
-      <form
-        onSubmit={(e) => {
-          e.preventDefault();
-          const value = (
-            e.currentTarget.elements.namedItem("answer") as HTMLInputElement
-          ).value;
-          submitInput(toolCallId, value);
-        }}
-      >
-        <p>{args.message ?? "Please provide input:"}</p>
-        <input name="answer" autoFocus />
-        <button type="submit">Submit</button>
-      </form>
-    );
-};
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx
-import type { ToolCallMessagePartComponent } from "@assistant-ui/react-native";
-import { useAdkSubmitInput } from "@assistant-ui/react-google-adk";
-import { useState } from "react";
-import { Pressable, Text, TextInput, View } from "react-native";
-
-type RequestInputArgs = {
-  interrupt_id?: string;
-  message?: string;
-  payload?: unknown;
-  response_schema?: unknown;
-};
-
-export const RequestInputToolUI: ToolCallMessagePartComponent<
-  RequestInputArgs,
-  unknown
-> = function RequestInputUI({ toolCallId, args, result }) {
-    const submitInput = useAdkSubmitInput();
-    const [value, setValue] = useState("");
-
-    if (result !== undefined) {
-      return <Text>Answered: {String(result)}</Text>;
-    }
-
-    return (
-      <View>
-        <Text>{args.message ?? "Please provide input:"}</Text>
-        <TextInput value={value} onChangeText={setValue} autoFocus />
-        <Pressable onPress={() => submitInput(toolCallId, value)}>
-          <Text>Submit</Text>
-        </Pressable>
-      </View>
-    );
-};
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx
-import type { ToolCallMessagePartComponent } from "@assistant-ui/react-ink";
-import { useAdkSubmitInput } from "@assistant-ui/react-google-adk";
-import { useState } from "react";
-import { Box, Text, useInput } from "ink";
-
-type RequestInputArgs = {
-  interrupt_id?: string;
-  message?: string;
-  payload?: unknown;
-  response_schema?: unknown;
-};
-
-export const RequestInputToolUI: ToolCallMessagePartComponent<
-  RequestInputArgs,
-  unknown
-> = function RequestInputUI({ toolCallId, args, result }) {
-    const submitInput = useAdkSubmitInput();
-    const [value, setValue] = useState("");
-
-    useInput((input, key) => {
-      if (result !== undefined) return;
-      if (key.return) submitInput(toolCallId, value);
-      else if (key.backspace || key.delete) setValue((text) => text.slice(0, -1));
-      else if (input) setValue((text) => text + input);
-    });
-
-    if (result !== undefined) {
-      return <Text>Answered: {String(result)}</Text>;
-    }
-
-    return (
-      <Box flexDirection="column">
-        <Text>{args.message ?? "Please provide input:"}</Text>
-        <Text>{value}</Text>
-        <Text dimColor>Press enter to submit.</Text>
-      </Box>
-    );
-};
-```
-
-</Tab>
-</PlatformTabs>
-
-Register the renderer with a backend toolkit entry inside `AssistantRuntimeProvider`:
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx
-import {
-  AssistantRuntimeProvider,
-  AuiConfig,
-  defineToolkit,
-  Tools,
-} from "@assistant-ui/react";
-import {
-  createAdkStream,
-  useAdkRuntime,
-} from "@assistant-ui/react-google-adk";
-import { Thread } from "@/components/assistant-ui/thread";
-
-const toolkit = defineToolkit({
-  adk_request_input: {
-    type: "backend",
-    render: RequestInputToolUI,
-  },
-});
-
-function App() {
-  const runtime = useAdkRuntime({
-    stream: createAdkStream({ api: "/api/chat" }),
-  });
-  const config = AuiConfig({ tools: Tools({ toolkit }) });
-  return (
-    <AssistantRuntimeProvider runtime={runtime} config={config}>
-      <Thread />
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx
-import {
-  AssistantRuntimeProvider,
-  AuiConfig,
-  defineToolkit,
-  Tools,
-} from "@assistant-ui/react-native";
-import {
-  createAdkStream,
-  useAdkRuntime,
-} from "@assistant-ui/react-google-adk";
-import { View } from "react-native";
-import { Thread } from "@/components/assistant-ui/thread";
-
-const API_URL = process.env.EXPO_PUBLIC_API_URL ?? "http://localhost:3000";
-
-const toolkit = defineToolkit({
-  adk_request_input: {
-    type: "backend",
-    render: RequestInputToolUI,
-  },
-});
-
-function App() {
-  const runtime = useAdkRuntime({
-    stream: createAdkStream({ api: `${API_URL}/api/chat` }),
-  });
-  const config = AuiConfig({ tools: Tools({ toolkit }) });
-  return (
-    <AssistantRuntimeProvider runtime={runtime} config={config}>
-      <View style={{ flex: 1 }}>
-        <Thread />
-      </View>
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx
-import {
-  AssistantRuntimeProvider,
-  AuiConfig,
-  defineToolkit,
-  Tools,
-} from "@assistant-ui/react-ink";
-import {
-  createAdkStream,
-  useAdkRuntime,
-} from "@assistant-ui/react-google-adk";
-import { Box } from "ink";
-import { Thread } from "./components/thread.js";
-
-const toolkit = defineToolkit({
-  adk_request_input: {
-    type: "backend",
-    render: RequestInputToolUI,
-  },
-});
-
-function App() {
-  const runtime = useAdkRuntime({
-    stream: createAdkStream({ api: "http://localhost:3000/api/chat" }),
-  });
-  const config = AuiConfig({ tools: Tools({ toolkit }) });
-  return (
-    <AssistantRuntimeProvider runtime={runtime} config={config}>
-      <Box flexDirection="column">
-        <Thread />
-      </Box>
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-</PlatformTabs>
-
-<Callout type="info">
-`adk_request_input` is emitted only by ADK Python 2.0+ Workflow `RequestInput` nodes; ADK JS has no equivalent. Always respond via a tool UI with `useAdkSubmitInput`. HITL interrupts are automatically exempt from `autoCancelPendingToolCalls`, so typing a normal message in the composer will not overwrite the pending interrupt.
-</Callout>
-
-`useAdkSubmitInput` is sugar over the generic `addResult`. If you prefer, call `addResult({ result: value })` from inside the render function directly. The `{ result }` wrapper is required either way: the adapter JSON-stringifies the value before sending, and ADK's `unwrap_response` unwraps it on the backend before the Workflow node resumes.
-
-## Artifacts
-
-Track file artifacts created or modified by the agent:
-
-```ts
-import { useAdkArtifacts } from "@assistant-ui/react-google-adk";
-
-function ArtifactList() {
-  const artifacts = useAdkArtifacts();
-  // Record<string, number> — filename to version number
-}
-```
-
-### Artifact fetching
-
-When using `createAdkSessionAdapter` (see [api reference](/docs/runtimes/google-adk/api#direct-adk-server-connection)), the returned `artifacts` object provides functions to fetch artifact content from the ADK server:
-
-```ts
-const { artifacts } = createAdkSessionAdapter({ apiUrl, appName, userId });
-
-// List all artifact filenames in a session
-const filenames = await artifacts.list(sessionId);
-
-// Load artifact content (latest version)
-const data = await artifacts.load(sessionId, "document.pdf");
-// data.inlineData?.data — base64 content
-// data.inlineData?.mimeType — MIME type
-// data.text — text content (if text artifact)
-
-// Load a specific version
-const v1 = await artifacts.load(sessionId, "document.pdf", 1);
-
-// List all versions
-const versions = await artifacts.listVersions(sessionId, "document.pdf");
-
-// Delete an artifact
-await artifacts.delete(sessionId, "document.pdf");
-```
-
-## Escalation
-
-Detect when an agent requests escalation to a human operator:
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx
-import { useAdkEscalation } from "@assistant-ui/react-google-adk";
-
-function EscalationBanner() {
-  const escalated = useAdkEscalation();
-  if (!escalated) return null;
-  return <div>Agent has requested human assistance.</div>;
-}
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx
-import { useAdkEscalation } from "@assistant-ui/react-google-adk";
-import { Text } from "react-native";
-
-function EscalationBanner() {
-  const escalated = useAdkEscalation();
-  if (!escalated) return null;
-  return <Text>Agent has requested human assistance.</Text>;
-}
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx
-import { useAdkEscalation } from "@assistant-ui/react-google-adk";
-import { Text } from "ink";
-
-function EscalationBanner() {
-  const escalated = useAdkEscalation();
-  if (!escalated) return null;
-  return <Text>Agent has requested human assistance.</Text>;
-}
-```
-
-</Tab>
-</PlatformTabs>
-
-## Long-running tools
-
-Track tools that are executing asynchronously and awaiting external input:
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx
-import { useAdkLongRunningToolIds } from "@assistant-ui/react-google-adk";
-
-function PendingToolsIndicator() {
-  const pendingToolIds = useAdkLongRunningToolIds();
-  if (pendingToolIds.length === 0) return null;
-  return <div>{pendingToolIds.length} tool(s) awaiting input</div>;
-}
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx
-import { useAdkLongRunningToolIds } from "@assistant-ui/react-google-adk";
-import { Text } from "react-native";
-
-function PendingToolsIndicator() {
-  const pendingToolIds = useAdkLongRunningToolIds();
-  if (pendingToolIds.length === 0) return null;
-  return <Text>{pendingToolIds.length} tool(s) awaiting input</Text>;
-}
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx
-import { useAdkLongRunningToolIds } from "@assistant-ui/react-google-adk";
-import { Text } from "ink";
-
-function PendingToolsIndicator() {
-  const pendingToolIds = useAdkLongRunningToolIds();
-  if (pendingToolIds.length === 0) return null;
-  return <Text>{pendingToolIds.length} tool(s) awaiting input</Text>;
-}
-```
-
-</Tab>
-</PlatformTabs>
-
-This hook reports every tool call ADK marked via `long_running_tool_ids`, including HITL interrupts. To respond to a specific HITL type, see [tool confirmations](#tool-confirmations), [auth requests](#auth-requests), or [input requests](#input-requests).
-
-## Per-message metadata
-
-Access grounding, citation, and token usage metadata per message:
-
-```ts
-import { useAdkMessageMetadata } from "@assistant-ui/react-google-adk";
-
-function MessageMetadata({ messageId }: { messageId: string }) {
-  const metadataMap = useAdkMessageMetadata();
-  const meta = metadataMap.get(messageId);
-  // meta?.groundingMetadata — Google Search grounding sources
-  // meta?.citationMetadata — citation references
-  // meta?.usageMetadata — token counts
-}
-```
-
-## Session state by scope
-
-ADK uses key prefixes to scope state. These helpers filter and strip the prefix:
-
-```ts
-import {
-  useAdkAppState,
-  useAdkUserState,
-  useAdkTempState,
-} from "@assistant-ui/react-google-adk";
-
-function StateDebug() {
-  const appState = useAdkAppState(); // app:* keys (app-level, shared)
-  const userState = useAdkUserState(); // user:* keys (user-level)
-  const tempState = useAdkTempState(); // temp:* keys (not persisted)
-}
-```
-
-Use `useAdkSessionState()` for the full unfiltered state delta.
-
-## Structured events
-
-Convert raw ADK events into typed, structured events for custom renderers:
-
-```ts
-import {
-  toAdkStructuredEvents,
-  AdkEventType,
-  type AdkStructuredEvent,
-} from "@assistant-ui/react-google-adk";
-
-const structured = toAdkStructuredEvents(event);
-for (const e of structured) {
-  switch (e.type) {
-    case AdkEventType.CONTENT:
-      console.log("Text:", e.content);
-      break;
-    case AdkEventType.THOUGHT:
-      console.log("Reasoning:", e.content);
-      break;
-    case AdkEventType.TOOL_CALL:
-      console.log("Tool:", e.call.name, e.call.args);
-      break;
-    case AdkEventType.ERROR:
-      console.error(e.errorMessage);
-      break;
-  }
-}
-```
-
-## Hooks reference
-
-| Hook | Description |
-| --- | --- |
-| `useAdkAgentInfo()` | Current agent name and branch path. |
-| `useAdkSessionState()` | Full accumulated session state delta. |
-| `useAdkAppState()` | App-level state (`app:*` prefix, stripped). |
-| `useAdkUserState()` | User-level state (`user:*` prefix, stripped). |
-| `useAdkTempState()` | Temp state (`temp:*` prefix, stripped, not persisted). |
-| `useAdkSend()` | Send raw ADK messages. |
-| `useAdkConfirmTool()` | Confirm or deny a pending tool confirmation. |
-| `useAdkSubmitAuth()` | Submit auth credentials for a pending auth request. |
-| `useAdkSubmitInput()` | Submit the user's answer for a pending `adk_request_input` HITL interrupt. |
-| `useAdkToolConfirmations()` | Pending tool confirmation requests. |
-| `useAdkAuthRequests()` | Pending auth credential requests. |
-| `useAdkLongRunningToolIds()` | IDs of long-running tools awaiting input. |
-| `useAdkArtifacts()` | Artifact delta (filename → version). |
-| `useAdkEscalation()` | Whether escalation was requested. |
-| `useAdkMessageMetadata()` | Per-message grounding, citation, and usage metadata. |
-
-## Feature support
-
-| Feature | Status |
-| --- | --- |
-| Streaming text (SSE) | Supported |
-| Tool calls and results | Supported |
-| Tool confirmations (`useAdkConfirmTool`) | Supported |
-| Auth credential flow (`useAdkSubmitAuth`) | Supported |
-| Workflow input requests (`useAdkSubmitInput`, ADK Python 2.0+) | Supported |
-| Multi-agent (author and branch tracking) | Supported |
-| Agent transfer events | Supported |
-| Escalation detection | Supported |
-| Chain-of-thought / reasoning | Supported |
-| Code execution (executableCode + result) | Supported |
-| Inline images and file data | Supported |
-| Session state delta + scoped state | Supported |
-| Artifact delta tracking + fetching | Supported |
-| Long-running tools (HITL) | Supported |
-| Grounding / citation / usage metadata | Supported |
-| Structured events (`toAdkStructuredEvents`) | Supported |
-| Typed `AdkRunConfig` | Supported |
-| Client → server `stateDelta` | Supported |
-| `finishReason` mapping (17 values) | Supported |
-| `interrupted` event handling | Supported |
-| Snake_case events (Python ADK) | Supported |
-| Cloud thread persistence | Supported |
-| ADK session-backed thread persistence | Supported |
-| Direct ADK server connection (no proxy) | Supported |
-| One-liner API route (`createAdkApiRoute`) | Supported |
-| Message editing and regeneration | Supported |
-| Automatic tool invocations | Supported |
-
-## Related
-
-<Cards>
-  <Card
-    title="API reference"
-    description="createAdkStream, server helpers, session adapter, threads."
-    href="/docs/runtimes/google-adk/api"
-  />
-  <Card
-    title="Quickstart"
-    description="Minimal API route + client setup."
-    href="/docs/runtimes/google-adk/quickstart"
-  />
-  <Card
-    title="Adapters"
-    description="Attachments, speech, feedback, history, threads."
-    href="/docs/runtimes/concepts/adapters"
-  />
-</Cards>