@assistant-ui/mcp-docs-server 0.1.29 → 0.1.31

package/.docs/raw/docs/runtimes/a2a/client-and-hooks.mdx

@@ -0,0 +1,396 @@
+---
+title: Client and hooks
+description: A2AClient, useA2ARuntime options, hooks, task states, artifacts, errors.
+---
+
+import { Network } from "lucide-react";
+
+Deep dive on the runtime's API surface. Start with [overview](/docs/runtimes/a2a) and [quickstart](/docs/runtimes/a2a/quickstart) if you have not already.
+
+## A2AClient
+
+The built-in `A2AClient` handles all communication with the A2A server: JSON serialization, SSE streaming, ProtoJSON enum normalization, and structured error handling.
+
+```ts
+import { A2AClient } from "@assistant-ui/react-a2a";
+
+const client = new A2AClient({
+  baseUrl: "https://my-agent.example.com",
+  headers: { Authorization: "Bearer <token>" },
+  tenant: "my-org",
+  extensions: ["urn:a2a:ext:my-extension"],
+});
+```
+
+Pass a pre-built client to `useA2ARuntime`:
+
+```tsx
+const runtime = useA2ARuntime({ client });
+```
+
+### Client options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `baseUrl` | `string` | Base URL of the A2A server. |
+| `basePath` | `string` | Optional path prefix for API endpoints (e.g. `"/v1"`). Does not affect agent card discovery. |
+| `headers` | `Record<string, string>` or `() => Record<string, string>` | Static or dynamic headers (e.g. for auth tokens). |
+| `tenant` | `string` | Tenant ID for multi-tenant servers (prepended to URL paths). |
+| `extensions` | `string[]` | Extension URIs to negotiate via `A2A-Extensions` header. |
+
+### Client methods
+
+| Method | Description |
+| --- | --- |
+| `sendMessage(message, configuration?, metadata?)` | Send a message (non-streaming). |
+| `streamMessage(message, configuration?, metadata?)` | Send a message with SSE streaming. |
+| `getTask(taskId, historyLength?)` | Get a task by ID. |
+| `listTasks(request?)` | List tasks with filtering and pagination. |
+| `cancelTask(taskId, metadata?)` | Cancel an in-progress task. |
+| `subscribeToTask(taskId)` | Subscribe to SSE updates for a task. |
+| `getAgentCard()` | Fetch the agent card from `/.well-known/agent-card.json`. |
+| `getExtendedAgentCard()` | Fetch the extended (authenticated) agent card. |
+| `createTaskPushNotificationConfig(config)` | Create a push notification config. |
+| `getTaskPushNotificationConfig(taskId, configId)` | Get a push notification config. |
+| `listTaskPushNotificationConfigs(taskId)` | List push notification configs. |
+| `deleteTaskPushNotificationConfig(taskId, configId)` | Delete a push notification config. |
+
+## useA2ARuntime options
+
+Pass either a pre-built `client` or a `baseUrl` (the runtime creates a client for you). Other options layer on top.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `client` | `A2AClient` | Pre-built A2A client instance (provide this OR `baseUrl`). |
+| `baseUrl` | `string` | A2A server URL (creates a client automatically). |
+| `basePath` | `string` | Path prefix for API endpoints. Only used with `baseUrl`. |
+| `tenant` | `string` | Tenant ID for multi-tenant servers. Only used with `baseUrl`. |
+| `headers` | `Record<string, string>` or `() => Record<string, string>` | Headers for the auto-created client. |
+| `extensions` | `string[]` | Extension URIs to negotiate. Only used with `baseUrl`. |
+| `contextId` | `string` | Initial context ID for the conversation. |
+| `configuration` | `A2ASendMessageConfiguration` | Default send message configuration. |
+| `onError` | `(error: Error) => void` | Error callback. |
+| `onCancel` | `() => void` | Cancellation callback. |
+| `onArtifactComplete` | `(artifact: A2AArtifact) => void` | Fired when an incremental artifact finishes. |
+| `adapters.attachments` | `AttachmentAdapter` | Custom attachment handling. See [adapters](/docs/runtimes/concepts/adapters#attachment-adapter). |
+| `adapters.speech` | `SpeechSynthesisAdapter` | Text-to-speech. See [adapters](/docs/runtimes/concepts/adapters#speech-adapter). |
+| `adapters.feedback` | `FeedbackAdapter` | Feedback collection. See [adapters](/docs/runtimes/concepts/adapters#feedback-adapter). |
+| `adapters.history` | `ThreadHistoryAdapter` | Message persistence. See [adapters](/docs/runtimes/concepts/adapters#history-adapter). |
+| `adapters.threadList` | `UseA2AThreadListAdapter` | Thread switching. See [threads](/docs/runtimes/concepts/threads). |
+
+## Hooks
+
+### Task state
+
+`useA2ATask` returns the current A2A task object, including task state and status message.
+
+<PlatformTabs>
+<Tab value="React">
+
+```tsx
+import { useA2ATask } from "@assistant-ui/react-a2a";
+
+function TaskStatus() {
+  const task = useA2ATask();
+  if (!task) return null;
+  return (
+    <div>
+      Task {task.id}: {task.status.state}
+    </div>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx
+import { useA2ATask } from "@assistant-ui/react-a2a";
+import { Text, View } from "react-native";
+
+function TaskStatus() {
+  const task = useA2ATask();
+  if (!task) return null;
+  return (
+    <View>
+      <Text>
+        Task {task.id}: {task.status.state}
+      </Text>
+    </View>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx
+import { useA2ATask } from "@assistant-ui/react-a2a";
+import { Text } from "ink";
+
+function TaskStatus() {
+  const task = useA2ATask();
+  if (!task) return null;
+  return (
+    <Text>
+      Task {task.id}: {task.status.state}
+    </Text>
+  );
+}
+```
+
+</Tab>
+</PlatformTabs>
+
+### Artifacts list
+
+`useA2AArtifacts` returns the artifacts generated by the current task.
+
+<PlatformTabs>
+<Tab value="React">
+
+```tsx
+import { useA2AArtifacts } from "@assistant-ui/react-a2a";
+
+function ArtifactList() {
+  const artifacts = useA2AArtifacts();
+  return (
+    <ul>
+      {artifacts.map((artifact) => (
+        <li key={artifact.artifactId}>
+          {artifact.name}: {artifact.parts.length} parts
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx
+import { useA2AArtifacts } from "@assistant-ui/react-a2a";
+import { Text, View } from "react-native";
+
+function ArtifactList() {
+  const artifacts = useA2AArtifacts();
+  return (
+    <View>
+      {artifacts.map((artifact) => (
+        <Text key={artifact.artifactId}>
+          {artifact.name}: {artifact.parts.length} parts
+        </Text>
+      ))}
+    </View>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx
+import { useA2AArtifacts } from "@assistant-ui/react-a2a";
+import { Box, Text } from "ink";
+
+function ArtifactList() {
+  const artifacts = useA2AArtifacts();
+  return (
+    <Box flexDirection="column">
+      {artifacts.map((artifact) => (
+        <Text key={artifact.artifactId}>
+          {artifact.name}: {artifact.parts.length} parts
+        </Text>
+      ))}
+    </Box>
+  );
+}
+```
+
+</Tab>
+</PlatformTabs>
+
+### Agent card
+
+`useA2AAgentCard` returns the agent card fetched from the server on initialization.
+
+<PlatformTabs>
+<Tab value="React">
+
+```tsx
+import { useA2AAgentCard } from "@assistant-ui/react-a2a";
+
+function AgentInfo() {
+  const card = useA2AAgentCard();
+  if (!card) return null;
+  return (
+    <div>
+      <h3>{card.name}</h3>
+      <p>{card.description}</p>
+      <div>Skills: {card.skills.map((s) => s.name).join(", ")}</div>
+    </div>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx
+import { useA2AAgentCard } from "@assistant-ui/react-a2a";
+import { Text, View } from "react-native";
+
+function AgentInfo() {
+  const card = useA2AAgentCard();
+  if (!card) return null;
+  return (
+    <View>
+      <Text>{card.name}</Text>
+      <Text>{card.description}</Text>
+      <Text>Skills: {card.skills.map((s) => s.name).join(", ")}</Text>
+    </View>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx
+import { useA2AAgentCard } from "@assistant-ui/react-a2a";
+import { Box, Text } from "ink";
+
+function AgentInfo() {
+  const card = useA2AAgentCard();
+  if (!card) return null;
+  return (
+    <Box flexDirection="column">
+      <Text bold>{card.name}</Text>
+      <Text>{card.description}</Text>
+      <Text>Skills: {card.skills.map((s) => s.name).join(", ")}</Text>
+    </Box>
+  );
+}
+```
+
+</Tab>
+</PlatformTabs>
+
+## Task states
+
+The A2A protocol defines 9 task states. The runtime maps them to assistant-ui message statuses:
+
+| A2A task state | Description | Message status |
+| --- | --- | --- |
+| `unspecified` | Unknown or default state. | `running` |
+| `submitted` | Task acknowledged. | `running` |
+| `working` | Task in progress. | `running` |
+| `completed` | Task finished. | `complete` |
+| `failed` | Task errored. | `incomplete (error)` |
+| `canceled` | Task cancelled. | `incomplete (cancelled)` |
+| `rejected` | Agent declined task. | `incomplete (error)` |
+| `input_required` | Agent needs user input. | `requires-action` |
+| `auth_required` | Authentication needed. | `requires-action` |
+
+<Callout type="info">
+When a task enters `input_required`, the user can continue the conversation normally. The runtime sends the next message with the same `taskId` to resume the task.
+</Callout>
+
+## Artifacts
+
+A2A agents can produce artifacts (files, code, data) alongside their responses. Artifacts are accumulated during streaming and accessible via `useA2AArtifacts`.
+
+The runtime supports:
+
+- **Incremental artifact streaming** via `append` mode.
+- **Artifact completion notification** via the `onArtifactComplete` callback.
+- **Automatic reset** of artifacts on each new run.
+
+```tsx
+const runtime = useA2ARuntime({
+  baseUrl: "http://localhost:9999",
+  onArtifactComplete: (artifact) => {
+    console.log("Artifact ready:", artifact.name);
+  },
+});
+```
+
+## Streaming vs non-streaming
+
+The runtime automatically selects the communication mode based on the agent's capabilities:
+
+- If the agent card indicates `capabilities.streaming: true` (or the field is unset), the runtime uses `POST /message:stream` with SSE.
+- If `capabilities.streaming: false`, the runtime falls back to `POST /message:send`.
+
+## Error handling
+
+The client throws `A2AError` instances with structured error information following the `google.rpc.Status` format:
+
+```tsx
+import { A2AError } from "@assistant-ui/react-a2a";
+
+const runtime = useA2ARuntime({
+  baseUrl: "http://localhost:9999",
+  onError: (error) => {
+    if (error instanceof A2AError) {
+      console.log(error.code); // HTTP status code
+      console.log(error.status); // e.g. "NOT_FOUND"
+      console.log(error.details); // google.rpc.ErrorInfo details
+    }
+  },
+});
+```
+
+## Multi-tenancy
+
+For multi-tenant A2A servers, pass a `tenant` option:
+
+```ts
+const client = new A2AClient({
+  baseUrl: "https://agent.example.com",
+  tenant: "my-org",
+});
+```
+
+This prepends `/{tenant}` to all API paths (e.g. `/my-org/message:send`).
+
+## Feature support
+
+| Feature | Supported |
+| --- | --- |
+| Streaming (SSE) | Yes |
+| Non-streaming fallback | Yes |
+| All 9 task states | Yes |
+| Artifacts (text, data, file) | Yes |
+| Agent card discovery | Yes |
+| Multi-tenancy | Yes |
+| Structured errors | Yes |
+| Push notifications CRUD | Yes |
+| Extension negotiation | Yes |
+| Task cancellation | Yes |
+| Message editing | Yes |
+| Message reload | Yes |
+| History persistence | Via [history adapter](/docs/runtimes/concepts/adapters#history-adapter) |
+| Thread list management | Via [thread list adapter](/docs/runtimes/concepts/threads) |
+
+## Related
+
+<Cards>
+  <Card
+    icon={<Network width={20} height={20} />}
+    title="A2A overview"
+    description="What A2A is and when to pick it."
+    href="/docs/runtimes/a2a"
+  />
+  <Card
+    title="Quickstart"
+    description="Minimal runtime + Thread setup."
+    href="/docs/runtimes/a2a/quickstart"
+  />
+  <Card
+    title="Adapters"
+    description="Attachments, speech, feedback, history, threads."
+    href="/docs/runtimes/concepts/adapters"
+  />
+</Cards>

package/.docs/raw/docs/runtimes/a2a/overview.mdx

@@ -0,0 +1,60 @@
+---
+title: Overview
+description: Connect to any A2A v1.0 protocol-compliant agent server.
+---
+
+`@assistant-ui/react-a2a` is a runtime adapter for the [A2A (Agent-to-Agent) v1.0 protocol](https://github.com/a2aproject/A2A). Use it when your backend speaks A2A; the adapter handles the wire protocol so you can focus on the UI.
+
+## When to use it
+
+Pick the A2A runtime when:
+
+- You have an A2A v1.0 compatible agent server, or you are building one and want a reference client.
+- You want streaming task state, artifacts, and the protocol's full state machine surfaced in the UI.
+- You need multi-tenant or extension-aware A2A clients.
+
+If your backend is not A2A-compliant, see [picking a runtime](/docs/runtimes/pick-a-runtime) for alternatives.
+
+## Architecture
+
+`@assistant-ui/react-a2a` is layered on `ExternalStoreRuntime` (see [architecture](/docs/runtimes/concepts/architecture)). Features that ship as runtime adapters (attachments, speech, feedback, history, threads) work the same way they do everywhere else; see [adapters](/docs/runtimes/concepts/adapters).
+
+## Requirements
+
+- An A2A v1.0 compatible agent server.
+- React 18 or 19.
+
+## Install
+
+<PlatformTabs>
+<Tab value="React">
+
+<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-a2a"]} />
+
+</Tab>
+<Tab value="React Native">
+
+<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/react-a2a"]} />
+
+</Tab>
+<Tab value="React Ink">
+
+<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/react-a2a", "ink", "react"]} />
+
+</Tab>
+</PlatformTabs>
+
+## Next
+
+<Cards>
+  <Card
+    title="Quickstart"
+    description="Minimal runtime setup with a Thread component."
+    href="/docs/runtimes/a2a/quickstart"
+  />
+  <Card
+    title="Client and hooks"
+    description="A2AClient, useA2ARuntime options, hooks reference, task states, artifacts."
+    href="/docs/runtimes/a2a/client-and-hooks"
+  />
+</Cards>

package/.docs/raw/docs/runtimes/a2a/quickstart.mdx

@@ -0,0 +1,216 @@
+---
+title: Quickstart
+description: Minimal runtime and Thread setup against an A2A server.
+---
+
+Three steps to a working chat against an A2A server. Assumes you have already installed the package and have an A2A v1.0 server reachable; if not, start at [overview](/docs/runtimes/a2a).
+
+<Steps>
+<Step>
+
+### Wire up the runtime provider
+
+<PlatformTabs>
+<Tab value="React">
+
+```tsx title="app/MyRuntimeProvider.tsx"
+"use client";
+
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import { useA2ARuntime } from "@assistant-ui/react-a2a";
+
+export function MyRuntimeProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const runtime = useA2ARuntime({
+    baseUrl: "http://localhost:9999",
+  });
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx title="runtime/MyRuntimeProvider.tsx"
+import { AssistantRuntimeProvider } from "@assistant-ui/react-native";
+import { useA2ARuntime } from "@assistant-ui/react-a2a";
+
+export function MyRuntimeProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const runtime = useA2ARuntime({
+    baseUrl: "http://localhost:9999",
+  });
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx title="runtime/MyRuntimeProvider.tsx"
+import { AssistantRuntimeProvider } from "@assistant-ui/react-ink";
+import { useA2ARuntime } from "@assistant-ui/react-a2a";
+
+export function MyRuntimeProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const runtime = useA2ARuntime({
+    baseUrl: "http://localhost:9999",
+  });
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+<Step>
+
+### Render the Thread
+
+<PlatformTabs>
+<Tab value="React">
+
+```tsx title="app/page.tsx"
+import { Thread } from "@/components/assistant-ui/thread";
+import { MyRuntimeProvider } from "./MyRuntimeProvider";
+
+export default function Page() {
+  return (
+    <MyRuntimeProvider>
+      <Thread />
+    </MyRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx title="app/index.tsx"
+import { View } from "react-native";
+import { Thread } from "@/components/assistant-ui/thread";
+import { MyRuntimeProvider } from "@/runtime/MyRuntimeProvider";
+
+export default function Page() {
+  return (
+    <MyRuntimeProvider>
+      <View style={{ flex: 1 }}>
+        <Thread />
+      </View>
+    </MyRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx title="app.tsx"
+import { Box } from "ink";
+import { Thread } from "./components/thread.js";
+import { MyRuntimeProvider } from "./runtime/MyRuntimeProvider.js";
+
+export function App() {
+  return (
+    <MyRuntimeProvider>
+      <Box flexDirection="column">
+        <Thread />
+      </Box>
+    </MyRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+<Step>
+
+### Set up UI components
+
+<PlatformTabs>
+<Tab value="React">
+
+Follow the [UI Components guide](/docs/ui/thread) to wire up the Thread, composer, and supporting primitives.
+
+</Tab>
+<Tab value="React Native">
+
+Follow the [React Native setup](/docs/react-native) to add a native Thread, composer, and supporting primitives.
+
+</Tab>
+<Tab value="React Ink">
+
+Follow the [Ink setup](/docs/ink) to add a terminal Thread, composer, and supporting primitives.
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+</Steps>
+
+Once your A2A server is reachable, the runtime negotiates streaming vs non-streaming based on the agent card's `capabilities.streaming` flag and starts forwarding messages.
+
+## Auth and headers
+
+Pass static or dynamic headers when your server expects auth:
+
+```tsx
+const runtime = useA2ARuntime({
+  baseUrl: "http://localhost:9999",
+  headers: async () => ({
+    Authorization: `Bearer ${await getAccessToken()}`,
+  }),
+});
+```
+
+## Adding adapters
+
+Attachments, speech, feedback, history, and a custom thread list are all supported via the standard adapter slots. See [adapters](/docs/runtimes/concepts/adapters) for the contracts; pass them on `useA2ARuntime`:
+
+```tsx
+const runtime = useA2ARuntime({
+  baseUrl: "http://localhost:9999",
+  adapters: { attachments, history, speech, feedback },
+});
+```
+
+For multi-thread, see [threads](/docs/runtimes/concepts/threads) and pass `adapters.threadList`.
+
+## Next
+
+<Cards>
+  <Card
+    title="Client and hooks"
+    description="A2AClient, useA2ARuntime options, hooks reference, task states, artifacts."
+    href="/docs/runtimes/a2a/client-and-hooks"
+  />
+  <Card
+    title="Pick a runtime"
+    description="Compare A2A to other runtime options."
+    href="/docs/runtimes/pick-a-runtime"
+  />
+</Cards>