Run a Hercules Agent from your app with the Agents API. Your app's backend starts each run with a key, the browser streams the reply with a token that reads only that run, and Hercules delivers the run's results into your app.
- Keys stay on your server. The browser gets a read-only token for one run
- Your app's database gets every message, tool call, and page action, even when no one has the page open
- In a Convex app,
@usehercules/agentsdoes all of this for you. See Convex backend
How does a run work?
Your backend starts the run
It calls
POST /v1/agents/{agent_id}/runswith your app's key, and names the signed-in user the run is for. The answer holds the run, and aliveURL and token for it.The browser streams the reply
It reads the run's events from
live.urlwithlive.token, so the reply appears as the Agent writes it.Hercules delivers the results to your app
It posts each durable event (messages, tool calls, page actions, and the run's end) to your app's events endpoint, signed by your app's Hercules Auth. See Event delivery.
The run ends
Every run ends with exactly one of
run.completed,run.failed,run.cancelled, orrun.capped.
Which credential do I use?
Send it as Authorization: Bearer <credential>.
| Credential | Where it comes from | Works on |
|---|---|---|
| App key | HERCULES_API_KEY, already set in every Convex deployment of your app | Every route |
| Organization API key | Settings → API keys | Every route, as your Organization |
| Run token | live.token, returned when the run starts | That run's events, as a stream, and no more |
- Never send a key to the browser. Only the events route answers calls from a page on another domain
- Keys need the
agents:runscope. App keys and Organization API keys have it - An app key reaches only the runs and threads its app started. An Organization API key reaches every run and thread of your Organization's Agents
- The Agent must have Let apps run this agent on (Manage → Agent settings → App access), or starting a run answers 403
agent_not_exposed
The Agent's id is a ULID in uppercase with no prefix, such as 01JDX5ZQ8W3J2K6M9N4P7R1S0T. It is the last part of the Agent's address in the console: https://hercules.app/org/<org-slug>/agents/<agent-id>.
What can a run token do?
A run token starts with hrt_ and is safe to hand to a browser:
- It reads one run's events as a stream (
Accept: text/event-stream), until 1 hour after the run ends. Sent for JSON, it is refused with 401invalid_run_token, and on every other route with 401credential_required - It is stable. Start the run again with the same
run_idand the same request, and you get the same run and the samelive.token - It can be used many times, but a run takes 10 streams at once. One more is a 429
rate_limited - Its stream hides tool details unless the run set
expose_tool_details. See What does a run token see of tools? - Deleting the run's thread ends its stream and revokes the token
How does versioning work?
Send the Hercules-Version header on every request, the stream included. The current version is 2025-12-09.
- A missing or unknown version is a 400 with the code
invalid_api_version. The version is checked before the credential, so this is the answer whatever key or token came with it - A run keeps the version it started with. Its events, deliveries, and live stream all use that version
- Within a version, changes only add things: fields, event types, message part types, and error codes. Ignore the ones you don't know
How do I start a run?
curl "https://api.hercules.app/v1/agents/$AGENT_ID/runs" \
-H "Authorization: Bearer $HERCULES_API_KEY" \
-H "Hercules-Version: 2025-12-09" \
-H "Content-Type: application/json" \
-d '{
"end_user": { "token_identifier": "<issuer>|<subject>" },
"input": [{ "type": "text", "text": "Where is my order?" }]
}'{
"run": {
"id": "01JDX4M2...",
"thread_id": "01JDX4M1...",
"agent_id": "01JDX5ZQ8W3J2K6M9N4P7R1S0T",
"status": "queued",
"output": null,
"error": null,
"capped_reason": null,
"usage": null,
"created_at": "2026-11-15T10:00:00.000Z",
"finished_at": null
},
"live": {
"url": "https://api.hercules.app/v1/agents/runs/01JDX4M2.../events",
"token": "hrt_..."
}
}end_user.token_identifieris the signed-in user, as Convex names them: thetokenIdentifierfromctx.auth.getUserIdentity(). Leaveend_userout for your app's own job, such as a scheduled function- Leave out
thread_idto open a new thread, or pass one to continue it - Send your own
run_id(a UUID, or a ULID in uppercase), so a retried request returns the same run instead of starting another. A UUID sent in uppercase comes back in lowercase - Set
wait_seconds(up to 60) to wait for short runs. A run that finishes in time answers200with its output
Every field is in the Agents API reference.
How do I stream the reply?
curl -N "https://api.hercules.app/v1/agents/runs/$RUN_ID/events" \
-H "Authorization: Bearer $RUN_TOKEN" \
-H "Hercules-Version: 2025-12-09" \
-H "Accept: text/event-stream"id: 3
data: {"id":"01JDX4M2...:3","seq":3,"run_id":"01JDX4M2...","thread_id":"01JDX4M1...","type":"message.delta","created_at":"2026-11-15T10:00:01.000Z","data":{"message_id":"01JDX4N0...","text":"Your order "}}- Each event's
idis itsseq - The stream closes after the run's final event, and after 10 minutes at most. If it closes or drops before a final event, reconnect with the
Last-Event-IDheader set to the lastidyou got. ALast-Event-IDthat is not a seq (a whole number from 0 to 2147483647) is a 400invalid_request - A
: keep-alivecomment line arrives every 15 seconds. Server-sent event parsers skip it - In a browser, read the stream with
fetch, notEventSource: the route needs theAuthorizationandHercules-Versionheaders, whichEventSourcecannot send - A run takes 10 streams at once. One more is a 429
rate_limitedwithRetry-After: 5, so check the status before you read the body
See Run events.
What do requests and lists look like?
- Bodies are JSON with
snake_casefields, up to 8 MiB. Timestamps are UTC, in ISO 8601 - Errors are problem details (
application/problem+json) with a stablecode. See Errors - A 503
service_unavailablemeans try again: wait for itsRetry-Afterwhen it has one, and send the same request. A 500internal_erroris also on Hercules's side. Retry it with backoff - Always retry a 503 from
POST /v1/agents/{agent_id}/runswith the samerun_id. The run may have been created without Hercules being able to confirm that it started. It then stays queued, and the answer names it and its thread indetails.run_idanddetails.thread_id. The same request with both starts the run or returns it started, and charges nothing more. Sent again without therun_id, it would start a second run - Hercules also limits how fast one credential calls the API. Each key and each run token is counted by itself, so another app's traffic never uses up yours. Past the limit the answer is a 429
rate_limitedwithRetry-After - A thread's messages answer
{ "data": [...], "has_more": true }, newest first. Page them withlimit(1 to 100, default 100),starting_after(a message id, for older messages), andending_before(a message id, for newer ones) - A run's events answer the same shape, oldest first, paged with
after(an event'sseq) - No route lists threads or runs. Store the id of each thread you want to open again
What can an Organization API key do?
An Organization API key runs an Agent as your Organization, from any server. Use it for a backend that is not a Hercules app:
- It starts runs on every Agent of your Organization that has Let apps run this agent on, and reads, streams, and cancels those runs, and reads and deletes their threads
- Deleting a thread whose run is still stopping answers 409
thread_busywithRetry-After, and deletes nothing. Send the delete again. See Delete a thread - Its runs act for no end user. Sending
end_useris a 400invalid_request, so its threads belong to your Organization, and your server decides who may see each - Nothing is delivered. Read a run with
GET /v1/agents/runs/{run_id}, its events withGET /v1/agents/runs/{run_id}/events, and a thread withGET /v1/agents/threads/{thread_id}/messages - Runs per user and Daily spend limit do not apply to it. Your Organization's rate of 60 runs a minute and its credit balance do
Additional FAQ
Can a page call the API from the browser?
Only to stream a run's events with its run token. Start runs, read threads, and cancel runs from your server, where the key stays secret. In a Convex app, the page calls your own Convex functions, and they call Hercules.
Where does Hercules deliver a run's events?
To the Convex deployment whose app key started the run, at
https://<deployment>.convex.site/hercules/agents/events. Your app needs Hercules Auth for this.
A run started with an Organization API key has no app to deliver to, so read its events and
messages from the API. See Event delivery.
What if a run gets stuck?
It is ended for you. A run whose execution is lost ends as failed, with the error code
run_failed, within a few minutes. So every run reaches a final event, and its thread is free for
the next run.
Why does every route answer 404?
The Agents API is not on for your Organization yet. Until it is, every route answers 404
not_found, the same as for an Agent, run, or thread that does not exist. That answer is final,
so do not retry it. In an app built with @usehercules/agents, each run then fails with the code
agent_not_found. Contact hello@hercules.app.
While Hercules cannot tell yet whether the API is on for your Organization, it answers 503
service_unavailable with Retry-After: 5 instead. Nothing was done: send the request again.
Who pays for a run?
Your Organization, in AI credits, the same as every other Agent run. A finished run's
usage.credits says what it cost. See Costs and limits.