Hercules

DevelopersEmbed the chat

Developers

Embed an Agent chat in your app

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.

What do I install?

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:

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

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:

OptionWhat it does
pageActionsThe page's handlers, by name, for handlers that need nothing from React. See page actions
fetchThe fetch used to read the run's live stream
retryHow it reconnects to the live stream: { initialMs, maxMs, maxAttempts }. By default 1 second, 30 seconds, and 10 tries in a row
settleTimeoutMsHow 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.

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.

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:

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.

  1. 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.

  2. Register a handler on the connection

    In SignedInChat, after useChat:

    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.

  3. List it in your backend

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

    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:

CodeWhat happened
sign_in_requiredNo one is signed in
not_foundThe thread is another user's, or another Agent's. Start a new chat
thread_deletedThe thread was deleted. Start a new chat under a new id
thread_busyA reply is still being written in this thread, or a stopped run took longer than settleTimeoutMs to end
end_user_rate_limitedThe user reached limits.runsPerUserPerHour, the limit in your backend
message_too_longThe message and its page context are over the size limit
invalid_requestThe message is empty, or the thread's id is not a lowercase UUID or an uppercase ULID

When a run failed:

CodeWhat happened
out_of_creditsYour Organization has no credits left. Do not retry
run_failedAnything else that stopped the run
end_user_rate_limited, agent_daily_limit_reached, rate_limitedA limit was reached. Do not retry
thread_busyThe thread's last run was still ending in Hercules
agent_not_exposed, agent_disabledLet apps run this agent is off, or the Agent is turned off
agent_not_foundYour 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_requestYour 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:

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 returnsWhat it is
messagesThe thread's messages, with the reply still being written streamed in until it is complete
status"loading", "ready", "submitted", or "streaming"
sendsend(text, { context? }) sends the user's message. Returns { threadId, runId }, or null when it was not sent
cancelcancel() stops the reply
errorAn 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
  • 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, 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.

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. herculesConnection turns them into AG-UI events in the browser.