Core Concepts
Bounds is built around a small set of composable primitives. Understanding them makes everything else - configuration, security, and troubleshooting - much easier.
Organisation
The root of the account hierarchy. Every agent, document, database, and session belongs to exactly one organisation. Users are scoped to organisations through roles. Data never crosses organisation boundaries.
Agent
The conversational entity your users interact with. An agent has a name, a system prompt, one or more attached databases, optional actions, and configurable session rules (rate limits, expiry, max messages). Each agent has three API keys:
| Prefix | Name | Where it is used | Keep secret? |
|---|---|---|---|
agt_ | Public key | Widget data-agent-id, client-side SDK | No - safe in browser |
sk_ | Client API key | Signed session initialisation from your server | Yes - server only |
ck_ | Management key | Admin API - CRUD operations, document uploads | Yes - server only |
Database
A named collection of documents. An agent can have multiple databases attached; at query time Bounds searches across all of them simultaneously and surfaces the most relevant content. Organise databases by topic or audience - for example, one for product documentation and a separate one for support policies.
Document
A PDF file you upload. Bounds analyses and indexes the content automatically so the agent can search it and cite specific pages in its answers. Processing is asynchronous; the document status moves through pending → processing → completed (or failed on error).
Session
A conversation thread between one end-user and an agent. Sessions come in two forms:
| Type | How it starts | What it enables |
|---|---|---|
| Anonymous | Widget opens automatically - no login required | Knowledge base answers, general questions |
| Signed | Your server mints a token with an externalUserId | Actions that fetch or write user-specific data |
Sessions expire after inactivity (anonymous: 30 min default; signed: 8 h default) or when a hard limit is hit (max messages, max duration).
Actions
Parameterised HTTP calls the agent can make during a conversation. You define a URL template, describe the inputs, choose when to call it (automatically or after asking the user), and optionally attach a credential binding so the call is authenticated. Actions let the agent check order status, look up account details, submit a form - any task that requires live data from your own systems.
Escalation
When the agent cannot resolve a request, or when a user asks to speak to a person, Bounds creates an escalation ticket. The ticket captures the full conversation context, the user's external ID (if signed session), a confidence score, and any routing tags you have configured. Your support team picks up the ticket from there.