Skip to main content
Backstage can build a Custom Action for you in conversation: the endpoint, headers, query parameters, body, and the details your AI agent asks customers for. You describe what the AI agent should be able to do and share your API docs, and Backstage drafts the Action, tests it against your real API, and turns it on after one approval. It’s the fastest way to connect your AI agent to your own systems if you’d rather not fill in the Action form yourself.

Build an Action

1

Describe the job

Tell Backstage what your AI agent should be able to do, and include links to the API docs if there are any.
2

Answer any open question

If your request leaves a real choice open, such as which endpoint to use or whether the Action should change data, Backstage asks you one question first.
3

Approve the build

Backstage reads the docs, drafts the Action, and asks for one approval that covers the whole build: the configuration, the test call, and turning the Action on.
Along the way, Backstage shows a masked input if the endpoint needs an API key, and a test card with a Run button for the test call. Both are covered below. Then try the Action in the Playground with a question that should trigger it.

Example: a weather lookup

I want my agent to tell people the current weather in their city. Here are the docs: https://open-meteo.com/en/docs
Backstage works out how the API expects its inputs. Here it notices that the API takes coordinates rather than city names, so it builds the Action with latitude and longitude as inputs. Compare it with the Weather API example built by hand.

Example: an order status lookup

Acme customers keep asking where their order is. Our API is GET https://api.example.com/orders/{order_id} with an x-api-key header. Build an Action that looks up an order by its number, like #1042.
Because the endpoint needs a key, Backstage shows a masked input for the x-api-key value instead of asking you to paste it in the chat.

API keys stay out of the chat

When an endpoint needs an API key, Backstage shows a masked input. The value goes straight from your browser to the Action, and Backstage never sees it. When Backstage reads the Action back later, any saved key appears as [set]. The form also shows which Action the key is for and the host it will be sent to, so you can check both before pasting a live key. Once saved, the key is a normal header or parameter on the Action. In the Action editor, header and parameter values are shown in plain text to anyone who can edit the Action, so use a key scoped to only what the Action needs. See Authentication.

Testing against your real endpoint

Nothing is sent to your API until you click Run. Before that, the test card shows the exact request that will be sent, and warns you when the method can change data (POST, PUT, PATCH, or DELETE). Backstage only receives the shape of the response (field names, types, and short samples), never the full body. Those fields become the data your AI agent can see when it calls the Action. Narrow them later from the Action’s Data Access settings in the dashboard.
Testing a POST, PUT, PATCH, or DELETE request runs it for real. Point the test at a test record or a sandbox if the call creates, changes, or deletes data.

Spotting missing Actions

When Backstage reviews your conversations, it can notice that customers keep asking for something only an Action could answer, and offer to build that Action. Many gaps are better solved with a Q&A or a source fix, and in those cases Backstage suggests that instead of an Action. Scheduled audits follow the same order: a Q&A first, then a source fix, an instructions change, and an Action last.

Good to know

  • If the request uses a {{variable}} that your AI agent never collects from the customer, Backstage points it out. See Variables.
  • On Slack, the Run button works right in the thread. Entering an API key opens Backstage on the web.
  • Building or editing an Action always needs your approval, even in auto mode, because Actions aren’t one of the auto mode areas.
  • A reply that triggers an Action costs twice the model’s usual message credits. See Actions.

Frequently asked questions

No. You type the key into a masked input, and it goes straight from your browser to the Action. When Backstage reads the Action later, the key shows as [set].
No. Nothing is sent until you click Run on the test card, which first shows the exact request and warns you if the method can change data.
Backstage receives only the shape of the response: field names, types, and short samples. It never receives the full response body.
Yes. It’s a normal Custom Action under Build > Actions. You can change it there, or ask Backstage to change it, with your approval.
Yes. You can describe the Action and run the test from the Slack thread. Entering an API key opens Backstage on the web.