> ## Documentation Index > Fetch the complete documentation index at: https://hercules.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # Use an Agent in your app > Put a Hercules Agent inside an app you build on Hercules. Your users chat with it on your pages, and you choose who can use it and how much it can spend. > [!NOTE] > > Using Agents in apps is in private beta, so things may change. If you hit a problem, tell us via > [Support & feedback](https://hercules.app/docs/company/contact.md). 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](https://hercules.app/docs/apps/quickstart.md). Describe what the Agent should do and who should use it: ```text Add a support chat wrap theme={} Add a support chat to my app. Create a Hercules Agent that answers questions about our plans and pricing, and only let signed-in users use it. ``` 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: ```text Use an existing Agent wrap theme={} Use the Sales Assistant agent in a chat on the pricing page. ``` 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**: | Option | Who can use it | | - | - | | **Signed-in users** | Only people signed in to your app. Hercules checks each user's sign-in on every run. This is the default | | **Anyone** | Visitors who are not signed in, too | 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. > [!WARNING] > > 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. | Limit | What it caps | Default | | - | - | - | | **Runs per user** | How many runs one user, or one visitor, can start per hour. Up to 1,000 | 20 | | **Daily spend limit** | How many credits the Agent can spend on runs your apps start, over a rolling 24 hours. Up to 100,000 | No limit | | **Visitor daily spend limit** | How many credits a day the Agent can spend on visitors who are not signed in. Only for **Anyone** | 100 | 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](https://hercules.app/docs/platform/billing/ai-credits.md) page. These limits are separate from the [run limits](https://hercules.app/docs/agents/costs-and-limits.md), 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: ```text Add page actions wrap theme={} Let the agent open a product's page when the user asks about it, and fill in the contact form for them. ``` 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 > [accordion] What can Hercules change about the Agent from the App Builder? > > 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** > [accordion] Can Hercules edit an Agent it didn't create? > > 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](https://hercules.app/docs/agents/instructions.md). > [accordion] Who pays for the Agent's runs? > > Your Organization. Every run from your app uses AI credits, the same credits as the rest of > Hercules. See [Costs and limits](https://hercules.app/docs/agents/costs-and-limits.md). > [accordion] Can users send files or images to the Agent? > > 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. > [accordion] How does the chat connect to the Agent? > > 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. > [accordion] I can't see App access > > Using Agents in apps is switched on one Organization at a time. If **App access** is missing under > **More**, contact [hello@hercules.app](mailto:hello@hercules.app). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.