---
title: "Embed an Agent chat in your app"
description: "Build the chat for a Hercules Agent with TanStack AI's useChat and herculesConnection, render it with your own components, and run the Agent's page actions."
image: "https://hercules.app/og/home"
---

# Embed an Agent chat in your app

> Build the chat for a Hercules Agent with TanStack AI's useChat and herculesConnection, render it with your own components, and run the Agent's page actions.

> **Note:** The 
>
> `@usehercules/agents`
>
>  package is in beta, so things may change.

Embed an Agent's chat with TanStack AI (an open-source library for building chat screens) and `herculesConnection` from `@usehercules/agents/tanstack`. Messages go through your Convex backend, the reply streams to the page as the Agent writes it, and the chat renders with your own components. This is how Hercules builds the chat in your app.

- No key or secret reaches the browser. The page calls your Convex functions, and streams the reply with a token for one run
- Opening a thread again loads its messages, and rejoins a reply that is still streaming
- Page actions run in the browser, in one tab only
- The chat is for signed-in users. Mount it once Convex knows who is asking. Without a signed-in user, every message fails with `sign_in_required`

Set up your Convex backend first, with the functions `support.api()` exports from `convex/agent.ts`. See [Convex backend](https://hercules.app/docs/agents/convex-backend).

### What do I install?

```bash Install
npm install @usehercules/agents @tanstack/ai @tanstack/ai-client @tanstack/ai-react
```

Your app installs the three TanStack AI packages itself:

- `@usehercules/agents` is tested with `@tanstack/ai` 1.2.0, `@tanstack/ai-client` 1.1.0, and `@tanstack/ai-react` 1.0.2
- The apps Hercules builds pin exactly those versions, and an exact version of `@usehercules/agents`. Do the same, and move all four together
- `@tanstack/ai` (1.2 or later) and `@tanstack/ai-client` (1.1 or later) are the package's optional peer dependencies. `@tanstack/ai-react` is your app's own, for `useChat`

### How do I build the chat?

Pass `herculesConnection` to TanStack AI's `useChat`, and render the chat with TanStack AI's headless kit, `createChatUI` from `@tanstack/ai-react/ui`, and your app's own components:

```tsx src/components/agent-chat.tsx
import { useState, type ComponentType, type FormEvent } from "react";
import { useChat, type UIMessage } from "@tanstack/ai-react";
import { createChatUI, TextPart } from "@tanstack/ai-react/ui";
import {
  agentErrorCode,
  herculesConnection,
  PAGE_ACTION_OUTPUT,
  useThreadSync,
  type HerculesMessageMetadata,
} from "@usehercules/agents/tanstack";
import { useConvex, useConvexAuth } from "convex/react";
import { api } from "@/convex/_generated/api.js";
import { Button } from "@/components/ui/button";
import { Textarea } from "@/components/ui/textarea";

type Part = UIMessage["parts"][number];

const chatOptions = { persistence: true } as const;

// The message component renders every part itself, so a tool the page does not know still shows.
const { Chat } = createChatUI(chatOptions, {
  components: { layout: ChatLayout, message: ChatMessage },
  partsComponents: {},
});

// The chat is for signed-in users. Mount it only once Convex knows who is asking:
// it reads its thread when it mounts, and a thread read signed out comes back empty.
export function AgentChat({ threadId }: { threadId: string }) {
  const { isLoading, isAuthenticated } = useConvexAuth();
  if (isLoading) return null;
  if (!isAuthenticated) return <p className="text-sm text-muted-foreground">Sign in to chat.</p>;
  return <SignedInChat threadId={threadId} />;
}

function SignedInChat({ threadId }: { threadId: string }) {
  // The client your Convex provider signs in.
  const convex = useConvex();
  // Once per chat: useChat keeps the first connection it gets.
  const [connection] = useState(() => herculesConnection(convex, api.agent));
  const [text, setText] = useState("");
  // The message on its way, to give back if it is not sent.
  const [sent, setSent] = useState("");
  const chat = useChat({
    ...chatOptions,
    connection,
    threadId,
    // A message that is refused, or whose run fails, goes back into the box.
    onError: () => setText((typed) => typed || sent),
  });
  // Shows replies the user's other tabs and devices got, keeps the reply a stop cut off,
  // and returns the thread.
  const thread = useThreadSync(chat, api.agent.thread, { threadId });
  const activeRun = thread?.activeRun ?? null;
  const latestRun = thread?.latestRun ?? null;
  // A run goes on until the thread says it ended. After Stop that is a moment later than
  // chat.isLoading, and for a run another tab started it is the only sign.
  const running = chat.isLoading || activeRun !== null;
  const stopping = activeRun?.stopping === true;
  const last = chat.messages.at(-1);
  const replying = last?.role === "assistant" && last.parts.some(isVisibleText);
  // chat.error is lost on a reload. The thread keeps how its latest run ended.
  const error = chat.error
    ? errorMessage(agentErrorCode(chat.error))
    : latestRun?.status === "failed"
      ? errorMessage(latestRun.error?.code ?? null)
      : null;
  // Notes on the latest run. They go with the next message, so none stays under a newer one.
  const notes: string[] = [];
  // "Stopped." is for a stop that cut no reply short: a reply cut short says so itself.
  // Ask the thread whether the last reply is whole. The mark on the chat's copy comes a
  // render after the run ends, so reading it here flashes the note under that reply.
  const whole =
    last?.role !== "assistant" ||
    thread?.messages.some((stored) => stored.id === last.id && stored.status === "completed");
  if (latestRun?.status === "cancelled" && whole) notes.push("Stopped.");
  // A page action that reached the app too late is not run. Say so.
  const late = thread?.pageActions.some(
    (action) => action.status === "expired" && action.runId === latestRun?.id,
  );
  if (late)
    notes.push("The assistant tried to do something on this page, but it arrived too late.");

  function send(event: FormEvent) {
    event.preventDefault();
    // Your backend refuses a message while a run goes on, so none is sent.
    if (running || !text.trim()) return;
    setSent(text);
    setText("");
    const context = {
      page: window.location.pathname,
      timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
    };
    void chat.sendMessage(text, { body: { context } }).finally(() => setSent(""));
  }

  function stop() {
    // chat.stop() ends this page's stream and cancels the run. A run with no stream here,
    // such as one another tab started, is cancelled in your backend.
    if (chat.isLoading) chat.stop();
    else void convex.mutation(api.agent.cancel, { threadId });
  }

  return (
    <div className="flex h-full min-h-0 flex-col gap-2">
      <div aria-live="polite" className="flex min-h-0 flex-1 flex-col gap-3 overflow-y-auto">
        <Chat chat={chat} />
        {running && (stopping || !replying) && (
          <p className="text-sm text-muted-foreground">
            {stopping ? "Stopping..." : (activeRun?.progress ?? "Thinking...")}
          </p>
        )}
        {notes.map((note) => (
          <p key={note} className="text-xs text-muted-foreground">
            {note}
          </p>
        ))}
      </div>
      <form onSubmit={send} className="flex flex-col gap-2">
        {error && <p role="alert">{error}</p>}
        <Textarea value={text} onChange={(event) => setText(event.target.value)} />
        <div className="flex justify-end gap-2">
          {/* Stop and Send are two buttons, and Send keeps its place. One button that turns
              from Stop into Send submits the form when the run ends during a click. */}
          {running && (
            <Button type="button" variant="outline" disabled={stopping} onClick={stop}>
              Stop
            </Button>
          )}
          <Button type="submit" disabled={running || !text.trim()}>
            Send
          </Button>
        </div>
      </form>
    </div>
  );
}

function ChatLayout({ Messages }: { Messages: ComponentType }) {
  return <Messages />;
}

function ChatMessage({ message }: { message: UIMessage }) {
  const parts = message.parts.filter((part) => isVisibleText(part) || part.type === "tool-call");
  const cutShort = isCutShort(message);
  if (parts.length === 0 && !cutShort) return null;
  return (
    <div data-role={message.role} className={message.role === "user" ? "self-end" : "self-start"}>
      {parts.map((part, index) =>
        part.type === "text" ? (
          <TextPart key={index} content={part.content} />
        ) : part.type === "tool-call" ? (
          // One line per tool call, while it runs and after it ends.
          <p key={index} className="text-xs text-muted-foreground">
            {toolLine(part)}
          </p>
        ) : null,
      )}
      {cutShort && <p className="text-xs text-muted-foreground">Stopped before it finished.</p>}
    </div>
  );
}

function isVisibleText(part: Part) {
  return part.type === "text" && part.content.trim() !== "";
}

/** A reply whose run ended before it was whole: stopped here, or stored that way. */
function isCutShort(message: UIMessage) {
  // What the connection records on a message: its run, and where the message stands.
  const hercules: Partial<HerculesMessageMetadata> = message.metadata?.hercules ?? {};
  return hercules.status === "incomplete";
}

/** One line for a tool call: its name while it runs, then the summary Hercules wrote. */
function toolLine(part: Extract<Part, { type: "tool-call" }>) {
  const name = part.name.replaceAll("_", " ");
  // Unless your backend sets exposeToolDetails, every Hercules tool is named "tool" here.
  if (part.output === undefined) return part.name === "tool" ? "Working..." : `Running ${name}...`;
  if (part.output === PAGE_ACTION_OUTPUT) return `Sent ${name} to the page`;
  return (
    part.output.summary ??
    (part.output.status === "failed" ? `Couldn't run ${name}` : `Ran ${name}`)
  );
}

function errorMessage(code: string | null) {
  switch (code) {
    case "sign_in_required":
      return "Sign in to chat.";
    case "message_too_long":
      return "That message is too long. Send a shorter one.";
    case "thread_busy":
      return "Wait for the reply to finish, then send your message again.";
    case "not_found":
    case "thread_deleted":
      return "This chat is not available. Start a new chat.";
    case "end_user_rate_limited":
    case "agent_daily_limit_reached":
    case "rate_limited":
      return "You have sent a lot of messages. Try again later.";
    case "out_of_credits":
    case "agent_not_exposed":
    case "agent_disabled":
      return "This assistant is not available right now.";
    case "agent_not_found":
    case "invalid_request":
      // The app's setup, not the user's message. A new chat will not help.
      return "This assistant is not available right now.";
    default:
      return "Something went wrong. Send your message again.";
  }
}
```

- Sending a message calls your `send` mutation, then streams the run's events into the chat, and reconnects with `Last-Event-ID` if the connection drops
- `persistence: true` loads the thread from your `thread` query when the chat opens, and rejoins a reply that is still streaming
- `useThreadSync` puts updates from the user's other tabs into the chat, but only while no reply is streaming in this tab
- `chat.stop()` stops the reply with your `cancel` mutation. `useThreadSync` keeps what the page streamed of the unfinished reply, with `metadata.hercules.status` set to `"incomplete"`, so the chat marks it "Stopped before it finished." Your backend keeps the reply only up to its last checkpoint, so a reload can show less of it, or only "Stopped." This needs `@usehercules/agents` 0.1.1 or later
- Stop and Send are two buttons, and Send stays disabled while a run goes on. One button that turns from Stop into Send submits the typed text when the run ends during a click
- `running` comes from the thread as well as from `chat.isLoading`. A stopped run takes a moment to end, and `thread.activeRun.stopping` is `true` until it has. The connection holds a message sent in that moment and sends it when the run ends, but refuses it as `thread_busy` after `settleTimeoutMs`, so the chat holds Send. It is also how a tab shows a reply that another tab started: that tab gets the reply when the run ends, and only a tab that opens or reloads during a run streams it
- `onError` puts the user's text back in the box when a message is refused or its run fails
- `thread.latestRun` says how the thread's latest run ended, so after a reload the chat still shows "Stopped." or why a message got no reply. The thread does not keep that for older runs
- Keep the chat mounted while the user is signed in. In a launcher, hide the closed panel with the `hidden` attribute instead of unmounting it: the connection holds the reply's stream and runs page actions only while the chat is mounted
- `TextPart` renders the Agent's Markdown safely
- Keep the `useConvexAuth()` gate in `AgentChat`. The chat reads its thread once when it mounts. Mounted before Convex has the user, that read finds nothing, and a reply still being written is not rejoined

> **Warning:** Build the connection inside the component, from `useConvex()`: that is the client your Convex
> provider signs in. Do not build it at module scope from a `ConvexReactClient` you import or create
> yourself. In a TanStack Start app the client is created inside `getRouter()`, so a client made
> anywhere else is signed out, and `send` fails with `sign_in_required`.

### What does herculesConnection take?

`herculesConnection(convex, api.agent, options)` takes your app's Convex client, the functions `support.api()` exported, and these options, all of them optional:

| Option            | What it does                                                                                                                                                                     |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pageActions`     | The page's handlers, by name, for handlers that need nothing from React. See [page actions](#how-do-page-actions-work)                                                           |
| `fetch`           | The `fetch` used to read the run's live stream                                                                                                                                   |
| `retry`           | How it reconnects to the live stream: `{ initialMs, maxMs, maxAttempts }`. By default 1 second, 30 seconds, and 10 tries in a row                                                |
| `settleTimeoutMs` | How long it waits for your backend to record that a run is over: after the stream ends, and before it sends a message while a stopped run is still ending. 10 seconds by default |

It returns a TanStack AI connection with `connect`, `hydrate`, `joinRun`, and `cancelRun`, which `useChat` calls for you, and `setPageActions`, which you call.

`useThreadSync(chat, api.agent.thread, { threadId, limit? })` returns the thread, as your `thread` query does. Pass `"skip"` in place of the arguments to read nothing. `limit` is 100 by default and 200 at most, and there is no way to page to older messages yet.

### How do I render tool calls?

In the `message` component, as above. The Agent also calls tools your page does not know, such as the tools that run in Hercules, and `toolsComponents` in `createChatUI` shows only the tools it names.

A tool call's `part.output` is empty while the tool runs. Once it ends, it is `{ kind, status, summary }`, or `"sent to the page"` for a page action. Show a line for each call, as `toolLine` does above: its name while it runs, and the `summary` when it is done. The thread keeps them, so the lines are still there after a reload.

By default the page does not learn which Hercules tools the Agent used. Each one is named `tool`, with the summary "Used a tool" or "Couldn't use a tool", and no tool call carries its result. Your app tools and page actions keep their names. To show the real names and summaries, set `exposeToolDetails: true` in your backend. It takes effect for your users as soon as your backend deploys, before you publish. The chat never gets a tool's result either way. See [Convex backend](https://hercules.app/docs/agents/convex-backend#what-does-the-page-see-of-tools).

Keep hooks in named components, such as `SignedInChat` above. A hook called in an inline arrow function, for example in an `input` slot written as `input: () => { ... }`, breaks React's rules of hooks.

### Which thread does the chat open?

The one you give `AgentChat`. Use a new `crypto.randomUUID()` for a new chat: the first message opens the thread under that id. Keep the id where the page can find it again, so a reload opens the same chat:

- On a chat page, keep it in the route (`/chat/$threadId`) or a search param
- In a chat launcher, keep it in state: `useState(() => crypto.randomUUID())`
- For **New chat**, use a new `crypto.randomUUID()`

A new thread's id must be a UUID in lowercase, as `crypto.randomUUID()` makes, or a ULID in uppercase. Anything else fails with `invalid_request`.

A thread answers only to the user who opened it. For anyone else, the `thread` query reads `null`, and a message to it fails with `not_found`. After your `deleteThread` mutation deletes a thread, its id is retired: a message to it fails with `thread_deleted`, so start the next chat under a new id.

Hercules does not list a user's threads. To show past chats, save each thread's id with the user in your backend. See [Convex backend](https://hercules.app/docs/agents/convex-backend#how-do-i-change-what-a-function-does).

### How do I send what is on the page?

Send named JSON values about the page with a message. The Agent reads them with the user's text, and they count toward the message size limit:

```tsx
const context = {
  page: window.location.pathname,
  timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
};
void chat.sendMessage(text, { body: { context } });
```

Send the user's time zone, and tell the Agent in its instructions to use it. Tools return dates in UTC and your page shows local time, so an Agent that does not know the zone can name a different day than the page does.

### How do page actions work?

A page action lets the Agent act on the page: open an order, fill in a form. Page actions are one-way. The Agent's call completes at once with "sent to the page", the run carries on, and the page runs the action.

**Declare it on the Agent**

Hercules does this when it creates the Agent. Page actions are the Agent's client tools: each
has a name, a description of up to 896 characters, and a JSON Schema for its arguments.

Every call's arguments are checked against that schema, within 100 milliseconds. A schema that
cannot be checked that way is refused when the page action is saved: one that does not compile,
is written for draft-04, or uses a `$ref` outside itself, one with a `pattern` over 512
characters, one where more than 500 subschemas apply to a single value, and one whose check
runs past the 100 milliseconds on a test value. `format` is never enforced.

**Register a handler on the connection**

In `SignedInChat`, after `useChat`:

```tsx
useEffect(() => {
connection.setPageActions({
  // The Agent writes the arguments: check them before acting.
  open_order: ({ orderId }) => {
    if (typeof orderId === "string") openOrder(orderId);
  },
});
return () => connection.setPageActions(undefined);
}, [connection, openOrder]);
```

Here `openOrder` is your own function, such as a call to your router. When a handler needs
nothing from React, pass it to `herculesConnection(convex, api.agent, { pageActions })` instead.

**List it in your backend**

Add its name to `pageActions` in `convex/agent.ts`, and keep `claimPageAction` among the
functions you export:

```ts convex/agent.ts
import { HerculesAgents } from "@usehercules/agents/convex";
import { components } from "./_generated/api";

export const support: HerculesAgents = new HerculesAgents(components.herculesAgents, {
agentId: "01JDX5ZQ8W3J2K6M9N4P7R1S0T",
// Only names the Agent declares.
pageActions: ["open_order"],
});

export const { send, thread, cancel, claimPageAction, deleteThread } = support.api();
```

A name that is listed here but not declared on the Agent makes every run fail with
`invalid_request`. Listing it is what lets the Agent call it, so in a published app do this
step after the handler is published. See the order below.

- A page action runs when Hercules has delivered it to your app, a moment after it shows in the chat. The chat claims it with your `claimPageAction` mutation, so only one of the user's tabs runs it, and then calls the handler with the action's arguments
- Hercules checks the Agent's arguments against the action's JSON Schema before it sends anything. A call that does not match, or whose check runs out of time, fails: the Agent reads what was wrong and can call again, and nothing reaches the page. Still check the arguments in your handler before you act on them
- A page action runs only within 2 minutes of the Agent's call. Your backend's clock decides that when a tab claims it, so the browser's clock plays no part. One that arrives while no tab has the chat open runs if the user opens the chat in that time
- One that came too late is never run. The thread lists it in `pageActions` with `status: "expired"` for 10 minutes, so the page can tell the user, as `SignedInChat` does above. The page sees the status change with the thread's next update, such as the claim that was refused as too late
- The chat shows the action as a finished tool call. The handler's return value goes nowhere, and the Agent never waits for the page
- Without `claimPageAction`, no page action runs, and the browser console says so
- Do not register a page action as a TanStack client tool. The connection answers every tool call itself

Your pages, your backend, and the Agent must agree on the names, and they change at two different moments:

- A change to the Agent, or to your backend (`pageActions` in `convex/agent.ts`), is live for your users as soon as it is saved or deployed. Your preview and your published app share one backend
- A change to your pages, such as a handler, is live for your users when you publish

The Agent can call a page action as soon as a run lists it. A page with no handler for it does nothing, and no one sees an error. So change one in an order that never leaves the published pages behind:

- **To add one**, declare it on the Agent and write its handler, publish, then list it in `pageActions`
- **To rename one**, first publish a handler that answers to both names. Then add the new name beside the old one, on the Agent and then in `pageActions`. Then change the Agent's instructions to the new name. Remove the old name last
- **To remove one**, take it out of `pageActions` and your pages, publish, then remove it from the Agent

A name that `pageActions` lists and the Agent does not declare makes every run fail with `invalid_request`.

### Which errors can the chat show?

`chat.error` is set when a message was not sent or a run failed. Read its code with `agentErrorCode(chat.error)`.

When a message was not sent:

| Code                    | What happened                                                                                             |
| ----------------------- | --------------------------------------------------------------------------------------------------------- |
| `sign_in_required`      | No one is signed in                                                                                       |
| `not_found`             | The thread is another user's, or another Agent's. Start a new chat                                        |
| `thread_deleted`        | The thread was deleted. Start a new chat under a new id                                                   |
| `thread_busy`           | A reply is still being written in this thread, or a stopped run took longer than `settleTimeoutMs` to end |
| `end_user_rate_limited` | The user reached `limits.runsPerUserPerHour`, the limit in your backend                                   |
| `message_too_long`      | The message and its page context are over the size limit                                                  |
| `invalid_request`       | The message is empty, or the thread's id is not a lowercase UUID or an uppercase ULID                     |

When a run failed:

| Code                                                                 | What happened                                                                                                                                   |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `out_of_credits`                                                     | Your Organization has no credits left. Do not retry                                                                                             |
| `run_failed`                                                         | Anything else that stopped the run                                                                                                              |
| `end_user_rate_limited`, `agent_daily_limit_reached`, `rate_limited` | A [limit](https://hercules.app/docs/agents/agents-in-apps#how-do-i-limit-what-the-agent-spends) was reached. Do not retry                                                |
| `thread_busy`                                                        | The thread's last run was still ending in Hercules                                                                                              |
| `agent_not_exposed`, `agent_disabled`                                | **Let apps run this agent** is off, or the Agent is turned off                                                                                  |
| `agent_not_found`                                                    | Your app's setup. Hercules has no Agent with the `agentId` in `convex/agent.ts` for this app, or the Agents API is not on for your Organization |
| `invalid_request`                                                    | Your app's code. `pageActions` lists a name the Agent does not declare                                                                          |

`agent_not_found` and a run's `invalid_request` are not the user's to fix. A new chat will not help, so do not offer one: fix the app.

A live view that fails is not an error. If Hercules refuses the run's stream, or keeps answering 429 because more than 10 tabs stream the same run, the connection reads the reply from your Convex backend instead. It arrives whole, without the typing effect, and `chat.error` stays unset.

`useThreadSync` returns the thread, which has more to show:

- `thread?.activeRun?.progress` is the run's latest progress label, for a line that says what the Agent is working on
- `thread?.latestRun?.error?.retryAfterSeconds` says how long a limit lasts, counted from `thread.latestRun.finished_at`
- `thread?.pageActions` lists the page actions that came too late, with `status: "expired"`
- `thread?.latestRun` is how the latest run ended: its `status`, and its `error` when it failed. `chat.error` is lost on a reload, and this is not

### Is there a lighter option?

Yes. `useAgentThread` from `@usehercules/agents/react` is a plain React hook with no TanStack AI. It takes the results of Convex's own `useQuery` and `useMutation`, and returns the thread with the live reply streamed in:

```tsx src/components/support-chat.tsx
import { useState } from "react";
import { AgentError, RunStreamError, useAgentThread } from "@usehercules/agents/react";
import { useConvexAuth, useMutation, useQuery } from "convex/react";
import { api } from "@/convex/_generated/api.js";

type Props = { openOrder: (orderId: string) => void };

// The chat is for signed-in users: mount it once Convex knows who is asking.
export function SupportChat(props: Props) {
  const { isLoading, isAuthenticated } = useConvexAuth();
  if (isLoading) return null;
  if (!isAuthenticated) return <p>Sign in to chat.</p>;
  return <SignedInSupportChat {...props} />;
}

function errorText(error: AgentError | RunStreamError | Error | null) {
  // A RunStreamError is the live view failing, not the run: the reply still arrives.
  if (error === null || error instanceof RunStreamError) return null;
  if (error instanceof AgentError && error.code === "agent_not_found") {
    // The app's setup. A new chat will not help.
    return "This assistant is not available right now.";
  }
  return "Something went wrong. Send your message again.";
}

function SignedInSupportChat({ openOrder }: Props) {
  const [threadId, setThreadId] = useState<string | null>(null);
  const chat = useAgentThread({
    threadId,
    // "skip" until there is a thread to read.
    thread: useQuery(api.agent.thread, threadId === null ? "skip" : { threadId }),
    send: useMutation(api.agent.send),
    cancel: useMutation(api.agent.cancel),
    claimPageAction: useMutation(api.agent.claimPageAction),
    pageActions: {
      // The Agent writes the arguments: check them before acting.
      open_order: ({ orderId }) => {
        if (typeof orderId === "string") openOrder(orderId);
      },
    },
  });

  async function submit(text: string) {
    const started = await chat.send(text, { context: { page: window.location.pathname } });
    // Keep the id the first send returns, so the next message continues the thread.
    if (started !== null) setThreadId(started.threadId);
  }

  const problem = errorText(chat.error);
  return (
    <div>
      {chat.messages.map((message) => (
        <p key={message.id} data-role={message.role}>
          {message.parts.map((part) => (part.type === "text" ? part.text : "")).join("")}
        </p>
      ))}
      {problem && <p role="alert">{problem}</p>}
      {chat.status === "streaming" || chat.status === "submitted" ? (
        <button type="button" onClick={() => void chat.cancel()}>
          Stop
        </button>
      ) : (
        <button type="button" onClick={() => void submit("Where is my order?")}>
          Ask about my order
        </button>
      )}
    </div>
  );
}
```

It takes `{ threadId?, thread, send, cancel?, claimPageAction?, pageActions?, fetch? }`, and returns:

| It returns | What it is                                                                                                         |
| ---------- | ------------------------------------------------------------------------------------------------------------------ |
| `messages` | The thread's messages, with the reply still being written streamed in until it is complete                         |
| `status`   | `"loading"`, `"ready"`, `"submitted"`, or `"streaming"`                                                            |
| `send`     | `send(text, { context? })` sends the user's message. Returns `{ threadId, runId }`, or `null` when it was not sent |
| `cancel`   | `cancel()` stops the reply                                                                                         |
| `error`    | An `AgentError`, a `RunStreamError`, any other `Error`, or `null`. See below                                       |

`error` is one of three things:

- An `AgentError` with a `code`: the message was not sent, or the latest run failed. For a limit it also has `retryAfterSeconds`. The codes are the ones [the chat can show](#which-errors-can-the-chat-show)
- A `RunStreamError`, only while a run is going: the live view of the reply could not be read. Hercules refused the stream, or kept answering 429 because more than 10 streams of the run are open, as with an eleventh tab. The run is not affected. The reply still arrives through `thread`, without the typing effect, and the error clears when the run is over. Do not show it as a failed message
- Any other `Error` a mutation threw, such as a lost connection

Both classes are exported from `@usehercules/agents/react`.

- Pass `threadId`. Left out, the hook takes it from `thread`, so a message sent while the query is still loading opens a new thread
- Without `cancel`, `chat.cancel()` does nothing. Without `claimPageAction`, no page action runs
- The hook takes page actions from `thread.pageActions`, and runs the `pending` ones. Read the `expired` ones from your `thread` query to tell the user

Hercules builds chats with TanStack AI. Use `useAgentThread` for a small widget, or when you would rather not add TanStack AI.

### Additional FAQ

#### Does the browser talk to Hercules?

Only to stream a run's reply, with a token that reads that one run and nothing else. Starting a
run, canceling it, and reading the thread all go through your Convex functions, which hold your
app's key.

#### Can I use TanStack AI's own tools with an Agent?

No. The Agent calls only the tools Hercules gives it: tools that run in Hercules, your [app
tools](https://hercules.app/docs/agents/app-tools), and the page actions declared on the Agent. Do not pass `tools` to
`useChat`, or write a TanStack client tool: `herculesConnection` answers every tool call itself,
so TanStack never runs one or starts a second run.

#### Why does the next message fail with thread_busy?

Your backend has not heard that the last run ended. Check that `convex/http.ts` calls
`support.registerRoutes(http)` and that your app uses Hercules Auth. Without them, your backend
learns of a run's end only from the package's fallback check, minutes late. See [Convex
backend](https://hercules.app/docs/agents/convex-backend#how-do-i-set-it-up).

#### Is AG-UI on the wire?

No. AG-UI (an open format for streaming an agent's replies to a web page) is what TanStack AI
reads, but the Agents API sends its own [run events](https://hercules.app/docs/agents/run-events). `herculesConnection`
turns them into AG-UI events in the browser.

Previous: [Run Agents from your Convex backend](https://hercules.app/docs/agents/convex-backend)

Next: [Give an Agent your app's tools](https://hercules.app/docs/agents/app-tools)

Every docs page is listed in [llms.txt](https://hercules.app/docs/llms.txt).

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://hercules.app/#organization",
      "name": "Hercules",
      "url": "https://hercules.app",
      "logo": {
        "@type": "ImageObject",
        "url": "https://hercules.app/logo-128.png"
      }
    },
    {
      "@type": "WebSite",
      "@id": "https://hercules.app/docs#website",
      "name": "Hercules",
      "url": "https://hercules.app/docs",
      "publisher": {
        "@id": "https://hercules.app/#organization"
      }
    },
    {
      "@type": "WebPage",
      "@id": "https://hercules.app/docs/agents/embed-chat#webpage",
      "url": "https://hercules.app/docs/agents/embed-chat",
      "name": "Embed an Agent chat in your app",
      "description": "Build the chat for a Hercules Agent with TanStack AI's useChat and herculesConnection, render it with your own components, and run the Agent's page actions.",
      "dateModified": "2026-11-16T23:57:07.000Z",
      "isPartOf": {
        "@id": "https://hercules.app/docs#website"
      },
      "breadcrumb": {
        "@id": "https://hercules.app/docs/agents/embed-chat#breadcrumb"
      }
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://hercules.app/docs/agents/embed-chat#breadcrumb",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Hercules",
          "item": "https://hercules.app/docs"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Embed an Agent chat in your app",
          "item": "https://hercules.app/docs/agents/embed-chat"
        }
      ]
    },
    {
      "@type": [
        "Article",
        "TechArticle"
      ],
      "@id": "https://hercules.app/docs/agents/embed-chat#article",
      "headline": "Embed an Agent chat in your app",
      "name": "Embed an Agent chat in your app",
      "description": "Build the chat for a Hercules Agent with TanStack AI's useChat and herculesConnection, render it with your own components, and run the Agent's page actions.",
      "url": "https://hercules.app/docs/agents/embed-chat",
      "mainEntityOfPage": {
        "@id": "https://hercules.app/docs/agents/embed-chat#webpage"
      },
      "image": "https://hercules.app/og/home",
      "dateModified": "2026-11-16T23:57:07.000Z",
      "keywords": "embed agent chat, herculesConnection, TanStack AI, useChat, createChatUI, useThreadSync, useAgentThread, page actions",
      "publisher": {
        "@id": "https://hercules.app/#organization"
      },
      "isPartOf": {
        "@id": "https://hercules.app/docs#website"
      },
      "inLanguage": "en-US"
    }
  ]
}
```
