Bubble Workflow Trigger Tool
The Bubble Workflow Trigger Tool connects your agent to your Bubble app's backend workflows. This allows the agent to take direct action—such as creating bookings or sending emails—instead of just answering questions.
This tool can change your data
Unlike the Bubble Database Read Tool, this tool is not read-only. A workflow does whatever you build it to do: create, change, or delete records, send emails, charge cards. Your agent decides on its own when to run one. Only add workflows you are comfortable with your agent running.
All of the fields below live in the Bubble Workflow Trigger card in Agent Studio.
Step 1 — Enable the Workflow API in Bubble
- In the Bubble editor, open Settings → API.
- Tick Enable Workflow API and backend workflows.
Step 2 — Expose Each Workflow
For every workflow you want your agent to be able to run:
- Open the Backend workflows editor and create (or open) an API workflow.
- Tick Expose as a public API workflow.
- Set Trigger workflow with to POST or GET. Note which one—you'll enter the same method in Agent Studio.
- Set Parameter definition to Manual definition, then add each parameter with its key, type, and whether it's optional.
- If you want your agent to get something back, end the workflow with a Return data from API action. Whatever it returns is what your agent reads, up to about 20,000 characters. Anything longer is cut off, so return only what your agent needs.
The method must match
Bubble rejects a call that uses the wrong method. If the workflow is set to GET and Agent Studio
says POST (or the other way round), every run fails with Wrong method.
Leave "Querystring" unchecked on POST workflows
On a POST workflow, your agent sends every parameter in the JSON body, so leave each parameter's Querystring box unchecked.
If you check it, Bubble looks for that value in the URL only, and never in the body:
- a required parameter makes every call fail. Bubble answers
MISSING_DATAand names that parameter, even though your agent sent it. - an optional parameter is worse. The call succeeds, your workflow runs with that value empty, and anything it writes with that value overwrites your existing data with a blank.
On a GET workflow there is no Querystring option. Bubble takes every parameter from the query string, which is what your agent sends.
Step 3 — Generate an Admin API Token
- Under Settings → API, find the API Tokens section.
- Click Generate a new API token.
- Copy the token immediately and keep it somewhere safe.
Generate a separate token for this tool, even if you already use one for Bubble Database Read. Each tool then stays independent: you can rotate or remove one without breaking the other.
This is an Admin token. Treat it like a password.
Step 4 — Find Your Workflow API URL
Your Workflow API URL is the root address your agent sends workflow calls to. It follows this shape:
Workflow API URL
Swap your-app for your app's name (or use your custom domain if you've set one). Don't include
a workflow name—your agent adds that for each call.
Step 5 — Connect It in Agent Studio
In Agent Studio, open Agent Tools, click Add Tool, and choose Bubble Workflow Trigger. In each Workflow API Source, fill in:
- Workflow API URL — the URL from Step 4.
- Workflow API Token — the token from Step 3. Once saved, it's stored securely and shown as
•••• Stored; use Replace if you ever need to rotate it.
Step 6 — Describe Your Workflows
The Workflows section tells your agent which workflows it may run, when to run them, and what to send. For each workflow:
- Workflow name — the endpoint name exactly as Bubble shows it: the part after
/wf/in the workflow's URL. - Method — the same method you set in Step 2.
- Description — when your agent should run it, and what it does. This is how your agent decides, so be specific about both.
- Parameters — for each one, its key (exactly as in Bubble), type, whether it's optional, and a short description of what value to send.
A workflow with no parameters is fine—leave the list empty.
Development vs. Production: Watch the version-test URL
Bubble runs two copies of your app—a development version and your live version—and the Workflow API URL is how you choose which one a workflow runs in.
Development (version-test)
Production (live)
Use the version-test URL for Test, and remove it for Live.
Without version-test, every workflow your agent runs acts on your live app and real customer
data. The card gives you a separate Workflow API Source for each environment for exactly this
reason.
When a Call Fails
If your agent can't reach your Bubble app at all, it tries once more. If the connection drops after the call was sent, it does not try again: it can't tell whether the workflow already ran, and running it twice could, for example, create two bookings.
When the outcome of a call is unknown, your agent also won't run that workflow again while it answers the same request. Instead, it tells the client it wasn't able to complete the action.
A workflow can still run twice for a single request. If your agent runs a workflow and then hits a server error before it answers, Pluto can retry the request once. The retry starts your agent over, and it has no record that the workflow already ran. This is uncommon, but it does not need a connection problem to happen, so plan for it. If running a workflow twice would cause real harm, build it so a repeat is detected and ignored.