Hercules

DevelopersConvex backend

Developers

Run Agents from your Convex backend

@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?

Install
npm install @usehercules/agents
ImportWhat it has
@usehercules/agents/convex.configThe Convex component that stores threads, runs, messages, and tool calls
@usehercules/agents/convexHerculesAgents and runFinishedValidator, and defineTools, tool, and ToolError for app tools
@usehercules/agents/tanstackherculesConnection, useThreadSync, and agentErrorCode, to embed the chat with TanStack AI
@usehercules/agents/reactuseAgentThread, a lighter React hook
@usehercules/agentsThe Run, Message, Event, and ToolCaller types, followRun, and createTokenVerifier and createMcpHandler for other backends

How do I set it up?

  1. Add the component

    convex/convex.config.ts
    import { 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 the import and app.use(herculesAgents) lines.

  2. Define the Agent and export the functions your page calls

    convex/agent.ts
    import { 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 passes api.agent to the chat. herculesConnection calls the functions by these names. Add pageActions only once the Agent declares them: see How do page actions work?

  3. Route the events

    convex/http.ts
    import { 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 the import and the support.registerRoutes(http) line. If the Agent has app tools, route them here too, with tools.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:

FunctionTypeArgumentsWhat it does
sendmutation{ threadId?, text, context? }Sends the user's message and starts a run. Returns { threadId, runId }
threadquery{ 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
cancelmutation{ threadId }Stops the thread's running run. Returns whether there was one
claimPageActionmutation{ 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
deleteThreadmutation{ 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, send throws sign_in_required, thread returns null, and the others return false
  • 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:

convex/agent.ts
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?

OptionWhat it does
agentIdThe Agent to run. Its id is the last part of its address in the console
pageActionsThe 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
onRunFinishedAn internal function the component calls after it writes a run's final event
limits.runsPerUserPerHourHow 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
exposeToolDetailsDefault 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, issuerLeave unset. They default to your app's HERCULES_API_KEY, the Agents API, and HERCULES_OIDC_AUTHORITY

Which methods does it have?

MethodWhat 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:

  1. Reads the signed-in user from ctx.auth
  2. Checks the user's hourly limit, and that no run is going on the thread
  3. Writes the user's message and a run to the component's tables
  4. Schedules an action that calls POST /v1/agents/{agent_id}/runs, with the run's own id as run_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:

FieldWhat it is
idThe thread's id
agentIdThe Agent the thread belongs to
messagesThe newest messages, oldest first: limit of them, 100 by default and 200 at most. Each is a Message with a status
hasMoretrue when older messages were left out
activeRunThe 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
latestRunThe thread's latest run, going or not, or null: { id, status, error, cappedReason, finished_at }. error is { code, message, retryAfterSeconds? } for a failed run
pageActionsThe page actions no tab has run: { toolCallId, runId, name, argumentsJson, created_at, status }, with status "pending" or "expired"
  • A message's status is streaming while the reply is being written, completed, or incomplete when its run ended first
  • activeRun.progress is the run's latest progress label, or null
  • activeRun.stopping is true once cancel asked for a stop, until the run has ended. That takes a moment, and send throws thread_busy until then. It is in @usehercules/agents 0.1.1 and later
  • latestRun says why a reply is missing: a failed run has its error, and a capped run its cappedReason
  • A read is also cut at about 4 MiB of messages, with hasMore: true. There is no cursor for the older messages yet: a larger limit, up to 200, is the only way to read further back
  • A pending page action waits for a tab to claim it. An expired one 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).

CodeWhen
sign_in_requiredNo one is signed in
not_foundThe thread is another user's, or another Agent's
thread_deletedThe thread was deleted. Start the next chat under a new id
thread_busyA run is still going on the thread
end_user_rate_limitedThe user reached limits.runsPerUserPerHour. retryAfterSeconds says when they can send again
message_too_longThe message and its context are over 262,144 characters
invalid_requestThe 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:

convex/audit.ts
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 ?? [];
  },
});
  • resultJson is an app tool's result as JSON text. argumentsJson is a page action's arguments
  • toolCallsTruncated is true when the results were more than one read holds, and the older runs' calls were left out
  • readThreadDetails does not read ctx.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:

convex/orders.ts
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,
    });
  },
});
convex/agent.ts
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, and endUser. Here agentReplies is a table of your own
  • Always write support: HerculesAgents. Convex types internal and api from your modules, this file included, so once the options name a function from either, TypeScript cannot work out the type of support without 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:

convex/reports.ts
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 user ctx.auth names, by their tokenIdentifier (<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
  • run acts for no end user. Only app tools that accept the agent caller 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_busy while that run is still stopping, so the component asks again when Retry-After says, 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, when Retry-After says 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.