@usehercules/agents connects a Hercules Agent to your app's Convex backend. It starts runs with your app's key, keeps threads, runs, and messages in your Convex database, and applies the events Hercules delivers. When you ask for an Agent in the App Builder, Hercules writes this code for you. This page is for reading it and changing it.
What does the package include?
npm install @usehercules/agents| Import | What it has |
|---|---|
@usehercules/agents/convex.config | The Convex component that stores threads, runs, messages, and tool calls |
@usehercules/agents/convex | HerculesAgents and runFinishedValidator, and defineTools, tool, and ToolError for app tools |
@usehercules/agents/tanstack | herculesConnection, useThreadSync, and agentErrorCode, to embed the chat with TanStack AI |
@usehercules/agents/react | useAgentThread, a lighter React hook |
@usehercules/agents | The Run, Message, Event, and ToolCaller types, followRun, and createTokenVerifier and createMcpHandler for other backends |
How do I set it up?
Add the component
convex/convex.config.tsimport { defineApp } from "convex/server"; import herculesAgents from "@usehercules/agents/convex.config"; const app = defineApp(); app.use(herculesAgents); export default app;If your app already has a
convex/convex.config.ts, keep it as it is and add theimportandapp.use(herculesAgents)lines.Define the Agent and export the functions your page calls
convex/agent.tsimport { HerculesAgents } from "@usehercules/agents/convex"; import { components } from "./_generated/api"; // Keep the type annotation: see "How do I act when a run ends?" export const support: HerculesAgents = new HerculesAgents(components.herculesAgents, { // The Agent's id: a ULID in uppercase, with no prefix. agentId: "01JDX5ZQ8W3J2K6M9N4P7R1S0T", }); // send, thread, cancel, claimPageAction and deleteThread, for the page. export const { send, thread, cancel, claimPageAction, deleteThread } = support.api();Name the file
convex/agent.ts, so the page passesapi.agentto the chat.herculesConnectioncalls the functions by these names. AddpageActionsonly once the Agent declares them: see How do page actions work?Route the events
convex/http.tsimport { httpRouter } from "convex/server"; import { support } from "./agent"; const http = httpRouter(); support.registerRoutes(http); // POST /hercules/agents/events export default http;If your app already has a
convex/http.ts, add only theimportand thesupport.registerRoutes(http)line. If the Agent has app tools, route them here too, withtools.registerRoutes(http).
There is nothing to configure: HERCULES_API_KEY, HERCULES_OIDC_AUTHORITY, and CONVEX_SITE_URL are already set in every Convex deployment of your app. Leave the apiKey, apiUrl, and issuer options unset, so the package uses them. The apps Hercules builds pin an exact version of the package.
Which functions does the page call?
support.api() builds them, for you to export from convex/agent.ts. Each one acts for the signed-in user:
| Function | Type | Arguments | What it does |
|---|---|---|---|
send | mutation | { threadId?, text, context? } | Sends the user's message and starts a run. Returns { threadId, runId } |
thread | query | { threadId, limit? } | The thread's newest messages, its running run with a live token, and the page actions no tab has run. null if it is not the caller's |
cancel | mutation | { threadId } | Stops the thread's running run. Returns whether there was one |
claimPageAction | mutation | { threadId, runId, toolCallId } | Takes a page action for one tab to run. Returns true to the first tab that asks. Returns false to every other, and for an action that came late |
deleteThread | mutation | { threadId } | Deletes the thread from your app at once, and asks Hercules to delete its copy. It cannot be undone. See deleting |
- Without a signed-in user,
sendthrowssign_in_required,threadreturnsnull, and the others returnfalse - Without
claimPageAction, no page action runs - A thread belongs to the Agent it was started with. In an app with several
HerculesAgents, each one's functions answer for its own threads only
How do I change what a function does?
Export your own function in place of the one from support.api(), with the same name and arguments, and call the matching method. Hercules has no route that lists threads, so to show a user their past chats, save each new thread with the user:
import { HerculesAgents } from "@usehercules/agents/convex";
import { v } from "convex/values";
import { components } from "./_generated/api";
import { mutation } from "./_generated/server";
export const support: HerculesAgents = new HerculesAgents(components.herculesAgents, {
agentId: "01JDX5ZQ8W3J2K6M9N4P7R1S0T",
});
export const { thread, cancel, claimPageAction, deleteThread } = support.api();
export const send = mutation({
args: {
threadId: v.optional(v.string()),
text: v.string(),
context: v.optional(v.record(v.string(), v.any())),
},
handler: async (ctx, args) => {
// Throws sign_in_required when no one is signed in.
const started = await support.send(ctx, args);
const identity = await ctx.auth.getUserIdentity();
const saved = await ctx.db
.query("chats")
.withIndex("by_thread", (q) => q.eq("threadId", started.threadId))
.unique();
if (saved === null && identity !== null) {
await ctx.db.insert("chats", {
threadId: started.threadId,
tokenIdentifier: identity.tokenIdentifier,
title: args.text.slice(0, 80),
});
}
// The page needs the run's id, so return what support.send returned.
return started;
},
});Here chats is a table of your own, with an index on threadId. List a user's chats with a query on it. Keep the three arguments of send as they are: the page always sends context.
Which options does HerculesAgents take?
| Option | What it does |
|---|---|
agentId | The Agent to run. Its id is the last part of its address in the console |
pageActions | The names of the page actions every run may call. None by default. Each must already be declared on the Agent, or every run fails with invalid_request |
onRunFinished | An internal function the component calls after it writes a run's final event |
limits.runsPerUserPerHour | How many runs one user can start per hour, checked by send before it calls Hercules. No limit when left out. Hercules still enforces the Agent's Runs per user |
exposeToolDetails | Default false. Shows the page the names and summaries of Hercules tools, and puts your app tools' results on the live stream. See What does the page see of tools? |
apiKey, apiUrl, issuer | Leave unset. They default to your app's HERCULES_API_KEY, the Agents API, and HERCULES_OIDC_AUTHORITY |
Which methods does it have?
| Method | What it does |
|---|---|
api() | Builds the five functions the page calls |
send(ctx, { threadId?, text, context?, pageActions? }) | In a mutation: starts a run for the signed-in user. Leave out threadId to open a new thread. Returns { threadId, runId } |
run(ctx, { threadId?, text, context?, pageActions? }) | In a mutation or action: starts a run as your app's own job, with no end user. Returns { threadId, runId } |
readThread(ctx, { threadId, limit? }) | In a query: what the thread function returns. Callers read their own threads only |
readThreadDetails(ctx, { threadId, limit? }) | In a query, for your backend only: the thread as stored, with every tool call and its result. It does not check who asks |
cancel(ctx, { threadId }) | In a mutation: stops the thread's running run |
deleteThread(ctx, { threadId }) | In a mutation: deletes a thread from your app at once, and asks Hercules to delete its copy |
claimPageAction(ctx, { threadId, runId, toolCallId }) | In a mutation: takes a page action for the calling tab |
registerRoutes(http) | Routes POST /hercules/agents/events on your HTTP router. One route serves every Agent in your app |
pageActions on send and run replaces the option's list for that one run.
What happens when a user sends a message?
In one Convex mutation, send:
- Reads the signed-in user from
ctx.auth - Checks the user's hourly limit, and that no run is going on the thread
- Writes the user's message and a run to the component's tables
- Schedules an action that calls
POST /v1/agents/{agent_id}/runs, with the run's own id asrun_id
Because the run's id is its idempotency key, a retried action never starts a second run. The page then reads the thread with your thread query, which updates as Hercules delivers the run's events, and streams the live reply with the token it returns.
A thread's id can come from the page. send opens a new thread when threadId is left out, or when it is a UUID in lowercase, as crypto.randomUUID() makes, or a ULID in uppercase, that no thread has yet. Any other new id is refused with invalid_request. A thread answers only to the user who opened it.
What does the thread query return?
null for a thread that does not exist or is another user's. Otherwise an AgentThread:
| Field | What it is |
|---|---|
id | The thread's id |
agentId | The Agent the thread belongs to |
messages | The newest messages, oldest first: limit of them, 100 by default and 200 at most. Each is a Message with a status |
hasMore | true when older messages were left out |
activeRun | The run that is going, or null: { id, status, progress, live, lastSeq, created_at, stopping }. live is { url, token } for the browser to stream, or null until Hercules took the run |
latestRun | The thread's latest run, going or not, or null: { id, status, error, cappedReason, finished_at }. error is { code, message, retryAfterSeconds? } for a failed run |
pageActions | The page actions no tab has run: { toolCallId, runId, name, argumentsJson, created_at, status }, with status "pending" or "expired" |
- A message's
statusisstreamingwhile the reply is being written,completed, orincompletewhen its run ended first activeRun.progressis the run's latest progress label, ornullactiveRun.stoppingistrueoncecancelasked for a stop, until the run has ended. That takes a moment, andsendthrowsthread_busyuntil then. It is in@usehercules/agents0.1.1 and laterlatestRunsays why a reply is missing: afailedrun has itserror, and acappedrun itscappedReason- A read is also cut at about 4 MiB of messages, with
hasMore: true. There is no cursor for the older messages yet: a largerlimit, up to 200, is the only way to read further back - A
pendingpage action waits for a tab to claim it. Anexpiredone reached your app more than 2 minutes after the Agent called it, so it was not run and will not be. The list holds the last 10 minutes, oldest first, and at most the 20 that have waited longest. The page sees a status change with the thread's next update. See How do page actions work?
Which errors do the functions throw?
A ConvexError whose data is { code, message, retryAfterSeconds? }. In the page, read the code with agentErrorCode (see Embed the chat).
| Code | When |
|---|---|
sign_in_required | No one is signed in |
not_found | The thread is another user's, or another Agent's |
thread_deleted | The thread was deleted. Start the next chat under a new id |
thread_busy | A run is still going on the thread |
end_user_rate_limited | The user reached limits.runsPerUserPerHour. retryAfterSeconds says when they can send again |
message_too_long | The message and its context are over 262,144 characters |
invalid_request | The message is empty, or a new threadId is not a UUID in lowercase or a ULID in uppercase |
A run that starts and then fails throws nothing. The thread's latestRun.error has its code: out_of_credits or run_failed, or the code Hercules refused the start with, such as end_user_rate_limited, agent_daily_limit_reached, rate_limited, thread_busy, agent_not_exposed, agent_disabled, hercules_auth_required for an app that does not use Hercules Auth 2.0, or invalid_request for a page action the Agent does not declare. For a limit, retryAfterSeconds counts from latestRun.finished_at.
One code is your app's setup, not the conversation. agent_not_found means Hercules answered 404 when the run started: it has no Agent with the agentId in convex/agent.ts for this app, or the Agents API is not on for your Organization. A new chat will not help. Fix the id, or ask for the beta. A 503 is not this: Hercules answers it while it cannot tell yet, and the component sends the run again with the same id.
What does the page see of tools?
A thread goes to the user's browser, so by default it leaves out what the Agent's tools did in detail:
- A Hercules tool call (a built-in tool or an integration) is named
tool, with the summary "Used a tool", or "Couldn't use a tool" when it failed - No tool call carries its result
- Your app tools and page actions keep their names and summaries
Hercules does the same to the run's live stream, so what streams and what is stored read alike. Set exposeToolDetails: true to show the page the tool calls as they are: the names and summaries of Hercules tools in the thread, and those plus the results of your app tools in the live stream.
The thread query and the chat hooks never carry a tool's result, with the option on or off. With it on, the results of your app tools travel to the browser on the live stream, where anyone can read them in the browser's network tools. Turn it on only when every result is safe for the user to see.
The component stores everything as delivered either way. Read it in your backend with readThreadDetails, which returns the thread with toolCalls:
import { v } from "convex/values";
import { internalQuery } from "./_generated/server";
import { support } from "./agent";
export const toolCallsOf = internalQuery({
args: { threadId: v.string() },
handler: async (ctx, { threadId }) => {
const details = await support.readThreadDetails(ctx, { threadId });
// Each has toolCallId, runId, name, kind, status, summary, resultJson, and argumentsJson.
return details?.toolCalls ?? [];
},
});resultJsonis an app tool's result as JSON text.argumentsJsonis a page action's argumentstoolCallsTruncatedistruewhen the results were more than one read holds, and the older runs' calls were left outreadThreadDetailsdoes not readctx.auth, and answers for any user's thread of this Agent. Call it from an internal function, or check who is asking first, and never return it to a page
How do I act when a run ends?
Pass onRunFinished, an internal mutation that takes runFinishedValidator.fields as its arguments. The component calls it after it writes the run's final event, so it can read the finished messages from the thread:
import { runFinishedValidator } from "@usehercules/agents/convex";
import { internalMutation } from "./_generated/server";
export const onAgentRunFinished = internalMutation({
args: runFinishedValidator.fields,
handler: async (ctx, run) => {
// run.status is "completed", "failed", "cancelled", or "capped".
if (run.status !== "completed" || run.output === null) return;
await ctx.db.insert("agentReplies", {
threadId: run.threadId,
runId: run.runId,
reply: run.output,
credits: run.usage?.credits ?? 0,
});
},
});import { HerculesAgents } from "@usehercules/agents/convex";
import { components, internal } from "./_generated/api";
// Keep the type annotation: see below.
export const support: HerculesAgents = new HerculesAgents(components.herculesAgents, {
agentId: "01JDX5ZQ8W3J2K6M9N4P7R1S0T",
onRunFinished: internal.orders.onAgentRunFinished,
});
export const { send, thread, cancel, claimPageAction, deleteThread } = support.api();- The run has
runId,threadId,agentId,status,output,error,cappedReason,usage, andendUser. HereagentRepliesis a table of your own - Always write
support: HerculesAgents. Convex typesinternalandapifrom your modules, this file included, so once the options name a function from either, TypeScript cannot work out the type ofsupportwithout the annotation, and type-checking fails with TS7022
How do I run the Agent with no user?
Call run in a mutation or action, for example from a cron job:
import { internalMutation } from "./_generated/server";
import { support } from "./agent";
export const summarizeOrders = internalMutation({
args: {},
handler: async (ctx) => {
const { threadId, runId } = await support.run(ctx, { text: "Summarize today's new orders." });
return { threadId, runId };
},
});The run acts for no end user, and its thread belongs to your app: no user can read it with thread. Read the reply in onRunFinished, or with readThreadDetails.
Who does the run act for?
- In
send, the run acts for the userctx.authnames, by theirtokenIdentifier(<issuer>|<subject>) - Your app tools see that user only when your app's own Hercules Auth signed them in. Otherwise the run acts for no end user
runacts for no end user. Only app tools that accept theagentcaller can be used. See App tools
What happens when I delete a thread?
deleteThread removes the thread from your app at once. The thread query reads null from then on, the live token of a run still going is dropped, and the thread's id is retired: send under it throws thread_deleted, so start the next chat under a new id.
The rest happens in the background:
- The thread's messages, runs, and tool calls are purged in batches
- The component asks Hercules to delete its copy. Hercules first stops a run that is still going, and answers 409
thread_busywhile that run is still stopping, so the component asks again whenRetry-Aftersays, for up to 24 hours. A 404 counts as deleted only after an hour of them, since Hercules also answers 404 while the Agents API is off for your Organization - A mutation that reschedules itself drives both, so neither stops halfway. If Hercules has not confirmed after 24 hours, the component logs it and stops asking
Deleting cannot be undone.
What does the component store?
The component keeps its own tables in your Convex database: threads, runs, messages, message chunks, and tool calls. It writes them as events are delivered, so reading a thread is a Convex query like any other.
The component also checks on every run that is still going, with a mutation that reschedules itself, so a check is never lost:
- A run with no delivery for 3 minutes is read from the API, with its events. While Hercules says the run is still going, the check comes back less often: after 3, 6, 12, and 24 minutes, then every 30. Any delivered event starts that over
- A start that Hercules could not answer is not a failure. After a
5xx, a timeout, or a network error, the component sends the run again under the same id, whenRetry-Aftersays and then up to 2 minutes apart - A cancel that did not get through is asked again
- A run Hercules has had no record of for 1 hour is recorded as failed
- A run Hercules never took, or one the component cannot settle, is recorded as failed after 24 hours, not after a number of tries
Each of those failures has the code run_failed, and frees the thread for the next run.
Additional FAQ
Does my app need Hercules Auth?
Yes, Hercules Auth 2.0. Hercules signs event deliveries and app tool calls with your app's own Hercules Auth, and starts no run for an app without it. See Event delivery.
Does it work with a custom domain on my Convex deployment?
Yes, when one of the two URLs is still Convex's own. Hercules calls your deployment at
https://<deployment>.convex.site, and signs its tokens for that address. The package accepts
that address from CONVEX_SITE_URL, and from CONVEX_CLOUD_URL when CONVEX_SITE_URL is a
custom domain. A deployment that overrides both with custom domains answers 401 to every
delivery, and Hercules then holds all of its deliveries. Leave CONVEX_CLOUD_URL as Convex sets
it.
Does it work with other backends?
Not yet. This release covers Convex. The root @usehercules/agents export holds the parts that do
not depend on Convex: the types, followRun, createTokenVerifier, and createMcpHandler.
Another backend can call the Agents API with an
Organization API key, which runs an Agent for no end user and delivers no events.