Actions overview
Actions give your agent capabilities beyond answering — collect a lead, escalate to a human, search the web, or call your own API. Learn how actions become tools the model can call, and how the confirm gate keeps state-changing calls safe.
View as MarkdownOut of the box, a Bookbag agent answers questions from your data. Actions let it do things too — capture a lead, hand a conversation to a person, look up a live order, search the web, or call any API you own. Each action you enable becomes a tool the model can call mid-conversation, with the parameters you define.
Actions are configured per agent. The agent decides when to call an action based on the conversation and the action's description, then Bookbag executes it, captures the result, and lets the agent weave that result into its reply.
Open an agent and go to the Actions tab. You'll see the actions on this agent plus a catalog of built-in actions and connectors you can add.
How an action becomes a tool
Every enabled action is exposed to the model as a function-calling tool. Three fields do the work:
| Field | What it does |
|---|---|
| Name | The function name the model calls. Letters, numbers, and underscores only — Bookbag normalizes it for you (max 60 chars). |
| Description | Tells the model when to use the action. This is the single most important field for reliable calling — be specific about the trigger. |
| Parameters schema | A JSON Schema describing the arguments the model must supply. It is the single source of truth for both validation and the tool definition. |
A description like "Look up the status of a customer's order. Use whenever a customer asks where their order is or for a tracking update." calls far more reliably than "Order lookup."
Action types
Every action is one of three types. You rarely set this directly — choosing a template or connector sets it for you.
| Type | Backed by | Examples |
|---|---|---|
custom | A built-in capability or your own HTTP endpoint | Collect leads, escalate to human, web search, custom HTTP action |
integration | A connector from the catalog | Shopify, Stripe, Zendesk, Calendly, HubSpot |
webhook | A fire-and-forget HTTP call | Notify an internal system when something happens |
The confirm gate
Every action has an execution mode that controls whether it runs automatically or pauses for explicit approval first.
| Mode | Behavior | Use for |
|---|---|---|
auto | Runs immediately when the model calls it. | Read-only or low-risk actions: order lookup, web search, collecting a lead. |
confirm | Pauses and asks for explicit confirmation before running. This is the default. | Anything that changes state: cancelling a subscription, issuing a refund, creating a ticket in another system. |
When a confirm-mode action is invoked, Bookbag returns a confirm_required response with a one-time token instead of running. The action only executes when that token is confirmed; denying it cancels the run. This gives you a safety checkpoint in front of irreversible operations.
New actions are created in confirm mode on purpose. Only switch an action to auto once you're confident it is safe to run without a human in the loop.
Testing an action
Each action has a Test button. Supply sample parameters and run it:
- 1Open the action and click TestFill in sample values for each parameter defined in the schema.
- 2Auto-mode actions run immediatelyYou see the raw result the agent would receive — HTTP status, parsed body, or the connector's output.
- 3Confirm-mode actions return a tokenThe test returns
confirm_requiredplus a token, exactly as it would in a live conversation. Confirm the token to execute, or deny it to cancel.
Every run — test or live — is logged with its inputs, output, status, and latency so you can audit what the agent did.
Built-in actions and connectors
Bookbag ships a set of ready-to-use actions plus a connector catalog for popular tools. Start with the built-ins, then add connectors as you need them.
- [Collect leads](/docs/actions/collect-leads) — show a form and capture name, email, and more.
- [Escalate to a human](/docs/actions/escalate-to-human) — hand the conversation to your team and open a help-desk ticket.
- [Web search](/docs/actions/web-search) — pull in real-time information from the web.
- [Custom action](/docs/actions/custom-action) — call any API you own with full control over method, URL, headers, and body.
- [Shopify actions](/docs/actions/shopify) — look up orders and products from your store.
The connector catalog also includes Stripe, Zendesk, Freshdesk, Zoho Desk, Help Scout, HubSpot, Salesforce, Intercom, Google Calendar, Calendly, and Cal.com. Each connector authenticates with credentials you store once in Integrations.