---
title: "Run Agents from your Convex backend"
description: "Use @usehercules/agents in a Convex app: start Hercules Agent runs from mutations, keep threads and messages in your own database, and apply each run's events."
image: "https://hercules.app/og/home"
---

# Run Agents from your Convex backend

> Use @usehercules/agents in a Convex app: start Hercules Agent runs from mutations, keep threads and messages in your own database, and apply each run's events.

> **Note:** The 
>
> `@usehercules/agents`
>
>  package and the Agents API are in beta, so things may change.

`@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](https://hercules.app/docs/agents/agents-in-apps), Hercules writes this code for you. This page is for reading it and changing it.

### What does the package include?

```bash Install
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](https://hercules.app/docs/agents/app-tools)              |
| `@usehercules/agents/tanstack`      | `herculesConnection`, `useThreadSync`, and `agentErrorCode`, to [embed the chat](https://hercules.app/docs/agents/embed-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**

```ts 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.

**Define the Agent and export the functions your page calls**

```ts 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?](https://hercules.app/docs/agents/embed-chat#how-do-page-actions-work)

**Route the events**

```ts 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](https://hercules.app/docs/agents/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.

> **Warning:** Your app needs Hercules Auth 2.0, and `support.registerRoutes(http)`. Hercules signs every event
> delivery with your app's own Hercules Auth, so it starts no run for an app without it: the run
> fails at once with `hercules_auth_required` (see [Upgrade to Hercules Auth
> 2.0](https://hercules.app/docs/apps/users-auth/upgrade-to-hercules-auth-2)). Without the route, your backend does not hear
> when a run ends: replies reach your database only through the package's fallback check, minutes
> late, and the next message fails with `thread_busy` until then.

### 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](#what-happens-when-i-delete-a-thread) |

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

```ts 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?

| 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?](#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`:

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

| 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](https://hercules.app/docs/agents/api-reference#the-message-object) 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 `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?](https://hercules.app/docs/agents/embed-chat#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](https://hercules.app/docs/agents/embed-chat#which-errors-can-the-chat-show)).

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

```ts 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:

```ts 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,
    });
  },
});
```

```ts 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:

```ts 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](https://hercules.app/docs/agents/app-tools#who-is-calling)

### 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](https://hercules.app/docs/agents/event-delivery#what-does-the-package-do-with-a-delivery), 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](https://hercules.app/docs/agents/event-delivery#what-does-my-app-need).

#### 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](https://hercules.app/docs/agents/api#what-can-an-organization-api-key-do) with an
Organization API key, which runs an Agent for no end user and delivers no events.

Previous: [Agents API](https://hercules.app/docs/agents/api)

Next: [Embed an Agent chat in your app](https://hercules.app/docs/agents/embed-chat)

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/convex-backend#webpage",
      "url": "https://hercules.app/docs/agents/convex-backend",
      "name": "Run Agents from your Convex backend",
      "description": "Use @usehercules/agents in a Convex app: start Hercules Agent runs from mutations, keep threads and messages in your own database, and apply each run's events.",
      "dateModified": "2026-11-16T23:58:36.000Z",
      "isPartOf": {
        "@id": "https://hercules.app/docs#website"
      },
      "breadcrumb": {
        "@id": "https://hercules.app/docs/agents/convex-backend#breadcrumb"
      }
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://hercules.app/docs/agents/convex-backend#breadcrumb",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Hercules",
          "item": "https://hercules.app/docs"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Run Agents from your Convex backend",
          "item": "https://hercules.app/docs/agents/convex-backend"
        }
      ]
    },
    {
      "@type": [
        "Article",
        "TechArticle"
      ],
      "@id": "https://hercules.app/docs/agents/convex-backend#article",
      "headline": "Run Agents from your Convex backend",
      "name": "Run Agents from your Convex backend",
      "description": "Use @usehercules/agents in a Convex app: start Hercules Agent runs from mutations, keep threads and messages in your own database, and apply each run's events.",
      "url": "https://hercules.app/docs/agents/convex-backend",
      "mainEntityOfPage": {
        "@id": "https://hercules.app/docs/agents/convex-backend#webpage"
      },
      "image": "https://hercules.app/og/home",
      "dateModified": "2026-11-16T23:58:36.000Z",
      "keywords": "@usehercules/agents, HerculesAgents, convex component, convex agent, agent threads, claimPageAction, onRunFinished, registerRoutes, exposeToolDetails",
      "publisher": {
        "@id": "https://hercules.app/#organization"
      },
      "isPartOf": {
        "@id": "https://hercules.app/docs#website"
      },
      "inLanguage": "en-US"
    }
  ]
}
```
