Custom action

A custom action lets your agent call any HTTP API you control. You define the request — method, URL, headers, and body — using template variables that the model fills in from the conversation. Bookbag makes the call, captures the response, and hands it back to the agent to use in its reply.

This is the most powerful action type. Use it for anything not covered by a built-in or connector: your own order system, an internal lookup service, a CRM endpoint, or a webhook into another tool.

How it works

1. 1
   Define parameters

   Write a JSON Schema describing the arguments the model supplies (for example an order number or email).
2. 2
   Build the request template

   Set the method, URL, headers, and body. Reference parameters with {{param}} placeholders — they are interpolated at call time.
3. 3
   Choose execution mode

   Read-only lookups can run in auto; anything that writes should stay in confirm (the default).
4. 4
   Test it

   Run the action with sample parameters to confirm the request, response shape, and confirm gate behave as expected.

Template variables

Use {{paramName}} anywhere in the URL, header values, or body. Each placeholder is replaced with the matching parameter the model supplied. A missing parameter resolves to an empty string rather than erroring.

{
  "type": "object",
  "properties": {
    "order_number": { "type": "string", "description": "The customer's order number" },
    "email": { "type": "string", "description": "Email on the order" }
  },
  "required": ["order_number"]
}

Configuration example

A custom action's config holds the HTTP template. Here is a complete example that looks up an order from your own API:

{
  "method": "GET",
  "url": "https://api.yourstore.com/orders/{{order_number}}?email={{email}}",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json"
  }
}

For a POST or PUT, add a body. A string body is interpolated for {{param}} placeholders; an object body is sent as JSON. When you send a body and don't set a Content-Type, Bookbag defaults it to application/json.

{
  "method": "POST",
  "url": "https://api.yourstore.com/returns",
  "headers": { "Authorization": "Bearer YOUR_API_KEY" },
  "body": {
    "order": "{{order_number}}",
    "reason": "{{reason}}"
  }
}

The agent receives the response as { http_status, ok, data }, where data is the parsed JSON (or truncated text if the response isn't JSON). Keep responses focused — return just the fields the agent needs to answer.

Security: SSRF protection

Specifically, the following are blocked and will fail the action with a clear error:

The confirm gate

Custom actions default to confirm execution mode. When the model calls a confirm-mode action, Bookbag does not fire the request immediately — it returns a confirm_required response with a one-time token. The request runs only when that token is confirmed, and is discarded if denied.

FAQ

What's next