The Agent Model
Every program that acts on Bkper books — scripts, automations, platform apps, bank connections — is an agent acting on behalf of a user. Agents are identified by logo and name in the activity stream, and are bound by the same permissions as the user who authorized them.
When you build something that interacts with Bkper — a script, an automation, a full platform app, or even a bank integration — Bkper treats it as an agent: any application that can perform actions on books on behalf of a user.
These agents can take various forms such as Apps, Bots, Assistants, or even Banks that interact with your books:
Permissions
Agents can only access books that have been explicitly shared with the user they’re acting on behalf of. Your code never has elevated access — it operates within the same permission boundaries as the human user who authorized it.
Identity
Every API request your app makes includes a bkper-agent-id header. This lets Bkper attribute actions to the correct agent, so activities and transactions appear with your app’s logo and name throughout the Bkper interface — making it easy for book owners to see which entity performed specific actions:
Bots vs AI Agents
The distinction between a “bot” and an “AI agent” is about capability, not a different type of Bkper primitive. Both are just apps:
| Bot | AI Agent | |
|---|---|---|
| Purpose | Automating predefined tasks | Autonomously perform tasks |
| Capabilities | Follows rules; limited learning; basic interactions | Complex, multi-step actions; learns and adapts; makes decisions independently |
| Interaction | Reactive; responds to triggers or commands | Proactive; goal-oriented |
In Bkper, what people call “bots” are typically apps whose primary capability is event handling — reacting to things that happen in a book. AI agents go further, combining event handling with LLM reasoning to make decisions.