Skip to main content
Using Agents in apps is in private beta, so things may change. If you hit a problem, tell us via Support & feedback.
Put a Hercules Agent inside an app you build on Hercules, so your users can talk to it on your pages. Use it for a support chat, a shopping assistant, or a button that runs the Agent on what the user typed.
  • Your app’s pages talk to the Agent directly. Hercules builds the chat for you, with no backend or API key to set up
  • You choose who can use it: only people signed in to your app, or anyone who visits
  • Limits cap how often each user can run it and how many credits it spends a day

​
How do I add an Agent to my app?

Ask Hercules in the App Builder. Describe what the Agent should do and who should use it:
Add a support chat
Hercules then:
1

Proposes a plan

It lists the Agent’s name, job, who can use it, tools, page actions, and limits, and asks for your yes before it creates anything.
2

Creates the Agent

It creates the Agent in your Organization and writes its instructions.
3

Tests it

It sends the Agent two or three real user messages, and one message it must refuse, then fixes the instructions until the answers are right.
4

Adds the chat to your app

It builds the chat on your page, opens the page, sends a message, and checks that a reply streams in.
5

Gives you the link

It gives you the Agent’s page in the Agents console, where you can review and change it.

​
Can I use an Agent I already built?

Yes. Any Agent in your Organization can run in your apps once you let it:
1

Open App access

Go to Agents → open the Agent → Build → More → App access.
2

Turn it on

Switch on Let apps run this agent.
3

Add it to an app

Click Add to an app, pick the app, and choose how to Use it as:
  • Chat: a chat in the app where users talk to the Agent and watch it reply live
  • Action: a button or form that runs the Agent on the user’s input and shows the result
  • Background: runs on a schedule, with no one watching, and saves what it finds in the app
4

Open in builder

Add any Requirements, then click Open in builder. Hercules opens the app with the request already sent.
Once Let apps run this agent is on, you can also ask Hercules in any app in your Organization to use the Agent by name. Only you can turn the switch on, so Hercules can’t use an Agent until you do:
Use an existing Agent
Agents that Hercules creates from the App Builder are already allowed to run in your apps.

​
Who can use the Agent?

Choose under App access → Who can use it: With Signed-in users, each user sees only their own chats. They get their latest chat back when they return, and can open their past chats. With Anyone, each visit starts a new chat, and the chat ends when the visitor closes the page. Nothing is saved for the visitor to come back to.
With Anyone, strangers spend your Organization’s credits, and the Agent can use all of its tools and connected accounts for whoever calls it. Set a Daily spend limit before you share the app.

​
How do I limit what the Agent spends?

Set these under App access. They save as soon as you change them. Visitors who are not signed in stop at the Visitor daily spend limit first, even when your Daily spend limit is higher. When a user reaches a limit, the chat shows a short message instead of a reply. When your Organization runs out of credits, it shows that the assistant is not available right now. Top up on the AI Credits page. These limits are separate from the run limits, which cap a single run wherever it starts.

​
Can the Agent do things on the page?

Yes. Page actions let the Agent act on your app’s page, for example to open a page or fill in a form. Your page runs the action in the user’s browser, and the Agent decides when to call it. Tell Hercules which actions you want when you ask for the Agent:
Add page actions
Hercules adds them when it creates the Agent, and you can ask it to change them later. Page actions only run on your page, so Hercules checks them by opening the page in a browser and trying them there.

​
How do I choose which sites can use the Agent?

Add them under App access → Allowed domains. Only pages on these domains can call the Agent from a browser.
  • Leave the list empty to allow any site. Every Agent starts this way
  • Use *.example.com to allow every subdomain
  • Your app’s own Hercules domains always work. Add your custom domain if your app has one
  • You can add up to 50 domains
If a page on a domain that isn’t in the list calls the Agent, the call is blocked. Add the domain to fix it.

​
Additional FAQ

For Agents created from that app, Hercules can set the instructions, prebuilt tools, page actions, who can use it, Runs per user, and Daily spend limit. Changes to the instructions take effect right away.Set these yourself on the Agent’s page, under Build:
  • Connections to other services and their sign-in: Integrations
  • The model: Instructions
  • What starts it: Triggers
  • Where it talks to people: Channels
  • Files and skills: Files, Skills
  • Allowed domains and Visitor daily spend limit: More → App access
No. Hercules can change only Agents created from that app. It can still use your other Agents once you let them run in apps, but you change them yourself in the Agents console. See Instructions.
Your Organization. Every run from your app uses AI credits, the same credits as the rest of Hercules. See Costs and limits.
No. Agents in apps read text only, up to a size limit. If a message is too long, the chat asks the user to send a shorter one.
For developers: your page streams the Agent’s replies from the Hercules Agents API at https://api.hercules.app/v1/agents, using AG-UI (an open format for streaming an agent’s replies to a web page) through the TanStack AI client library. For Signed-in users, each call carries the user’s Hercules Auth sign-in token. For Anyone, a visitor’s call carries no token. Your app needs no server code or API key for this.
Using Agents in apps is switched on one Organization at a time. If App access is missing under More, contact hello@hercules.app.