Embed on Your Site

The Bounds widget runs entirely in the browser. Adding it to any site takes one script tag. No build step, no framework dependency.

The script tag

Paste this before the closing </body> tag, replacing the placeholder with your agent's public key (starts with agt_):

<script
  src="https://cdn.bounds.ai/widget.js"
  data-agent-id="agt_your_key_here"
  defer
></script>

The agt_ key is a public identifier - it is safe to include in HTML served to end users. It cannot be used to modify agent configuration or access private data.

Anonymous sessions

By default, when a user opens the widget, the SDK automatically creates an anonymous session by calling:

POST /api/public/agents/{agentId}/sessions

No login is required. The session is identified by a publicSessionId that the widget stores locally and uses as its bearer token for all subsequent message requests. Anonymous sessions expire after 30 minutes of inactivity by default.

Signed sessions

For agents that need to access user-specific data - checking order history, fetching account details - you should create a signed session from your own server. Your server uses the sk_ client API key to mint a session token that includes the user's externalUserId. Pass the resulting token to the widget on page load:

<script
  src="https://cdn.bounds.ai/widget.js"
  data-agent-id="agt_your_key_here"
  data-session-token="SESSION_TOKEN_FROM_YOUR_SERVER"
  defer
></script>

Signed sessions have a longer default expiry (8 hours) and unlock the full set of actions that are scoped to the current user.

Allowed origins

In the agent settings you can restrict which domains are allowed to load the widget. Add your production and staging origins to the allowlist. Requests from unlisted origins will be rejected. This prevents your agent key from being used on third-party sites.

Single-page applications

The widget survives client-side navigation. If your SPA uses hash or history routing, the widget remains open across route changes. If you need to reset the session on navigation - for example when a user logs out - call window.Bounds.reset() before redirecting.