Quickstart - Bubble.io

You can go from zero to a working AI agent inside your Bubble app in under 30 minutes. This guide walks you through it in three parts:

Set up your agent — create your account, an API key and an agent.
Connect Bubble — add a Pluto Agent collection to Bubble's API Connector.
Send your first message — call your agent from a workflow.

Part 1: Set Up Your Agent

Create your account

Sign up at pluto-agent.com. This gives you access to your developer portal, where you'll manage keys, credits, and your agents.
Generate an API key

From the portal, open API Keys and generate a new key. This key authenticates every request your app makes to the agent.

Treat your API key like a password. Store it somewhere safe and never commit it to a public repository or expose it in client-side code you don't control.
Create an agent and deploy it to Test

Open Agent Studio and click New Agent. You'll land straight in the editor for a brand-new agent.

There's nothing to configure yet—press DEPLOY AGENT beside Test to deploy the empty configuration as-is.

While you're here, copy the Agent ID shown at the top of the editor—it's the letters pa- followed by six digits. Your app will include that ID with every request it sends.

Your agent only starts answering requests in an environment once you've deployed to it, so this first deploy is what makes it reachable.

Part 2: Connect Bubble

You connect to your agent with Bubble's own API Connector. If you've used it before, every step here will be familiar.

Create a Pluto Agent collection

In your Bubble editor, click the API Connector icon in the left navigation pane. Click + NEW to add a new API collection, and name it Pluto Agent.
Add your API key to the collection

Click the dropdown icon next to COLLECTION to open the collection's settings, and fill in:

Setting Value
Authentication Private key in header
Key name Authorization
Key value Bearer <your-api-key>
Development key value Bearer <your-api-key>

The word Bearer and the space before your key are both required.

Keep the key in this field
This field keeps your API key on Bubble's server, out of the pages your users download. Don't put the key in Shared headers for all calls, or in an API's headers or body, instead.
Add an API from cURL

In the Pluto Agent collection, add an API. Import it from cURL, and paste this command as-is:
```
cURL
curl -X POST https://api.pluto-agent.com/v1/response-agent \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent_id>",
    "session_id": "<session_id>",
    "client_prompt": "<client_prompt>",
    "environment": "<environment>",
    "client_platform": "bubble",
    "reset_session": "<reset_session>"
  }'
```
Bubble fills in the API's endpoint and body, with one parameter for each value in <angle brackets>. There's no Authorization header in the command—the API gets your key from the collection's settings.

client_platform is fixed at bubble on purpose. It matches your agent's time limit to the time Bubble keeps a call open. See client_platform.
Finish the API's settings

In the new API, make three changes:
- Set Use as to Action and Data type to JSON.
- In the body, delete the two quotes around <client_prompt>, so that the line reads:
```
Code
"client_prompt": <client_prompt>,
```
  Your workflow adds those quotes back in Part 3, along with the escaping that keeps a message containing a quote or a line break from breaking the request.
- Clear the Private checkbox on every parameter, so your workflows can set their values.
Initialize the API

Give each parameter a test value:

Parameter Test value
agent_id Your Agent ID, e.g. pa-123456
session_id quickstart-test
client_prompt "Hello" — with the quotes
environment test
reset_session yes

Click Initialize call. Bubble sends a real request to your agent and shows the fields of its response.

Initializing sends a real request, so it uses a small amount of your free-trial credits. It fails if your agent isn't deployed to Test yet—see Part 1, step 3.

Added a Structured Response later?
Bubble learns a response's fields only when you initialize the API. If you add a Structured Response to your agent, initialize the Response-Agent API again so Bubble can see your fields.
Rename the API

The import names the API cURL Call. Change its API Call value to Response-Agent. This is the name your workflows show when you add the action in Part 3.

Setting	Value
Authentication	`Private key in header`
Key name	`Authorization`
Key value	`Bearer <your-api-key>`
Development key value	`Bearer <your-api-key>`

Parameter	Test value
`agent_id`	Your Agent ID, e.g. `pa-123456`
`session_id`	`quickstart-test`
`client_prompt`	`"Hello"` — with the quotes
`environment`	`test`
`reset_session`	`yes`

Part 3: Send Your First Message

Build your interface

For a conversational AI Agent, you design the interface yourself—chat bubbles, input box, send button, and how the response is displayed. The Response-Agent API handles communication with your agent; you own the look and feel.

Add the action to your workflow

In whichever workflow should talk to your agent (for example, when a user clicks Send), add the Pluto Agent - Response-Agent action and set its parameters:

Parameter	Value
`agent_id`	The Agent ID you copied in Part 1.
`session_id`	A unique identifier for each session (conversation)
`client_prompt`	Your input's value, followed by `:formatted as JSON-safe`.
`environment`	`test`
`reset_session`	`no` to continue the session, `yes` to delete message history and start fresh.

Always add :formatted as JSON-safe

The formatter wraps the message in quotes and escapes any quote or line break inside it. Without it, the first message a user types with a quote in it fails.

To show the answer, read Result of step N's agent_response, where N is the number of the Response-Agent step. See the Response-Agent API reference for every field the API sends and returns.

Send your first message

Preview your app, type a message, and send it. Your agent will plan, decide, and respond.

Congratulations—you've just set up your AI agent. 🎉🎉🎉

Your Agent Is Still Empty

The agent you deployed is fully functional, but its configuration is blank, so it behaves generically. Now it's time to configure it.

Agent Studio is where you build your AI Agent:

Agent Purpose and Instructions — what is it for, and how should it behave.
Agent Guardrails — rules it must always follow.
Agent Model — the brain that powers reasoning, planning and responding.
Agent Tools — the capabilities it is allowed to use.

Start with Basic Configuration to set up your Agent Build.

An Agent Build is the set of configurations that make up your AI Agent.
Each agent you build has an associated Agent Build.

Going Live

Everything so far has run in your Test environment.

The Test environment is for prototyping and testing.
Once testing is complete, you deploy your agent to Live environment.

When you're happy with how your agent behaves, deploy it to Live in Agent Studio and set environment to live in your workflow's Response-Agent action.

Your Test environment keeps working exactly as it is, so you can carry on making changes without touching what your users see.

Last modified on October 12, 2026

AI Agents Intro Basic Configuration