What it does
Define an agent command a page can send with data-bp-command or bp.command. kind fixed (default) needs instruction, up to 2000 characters; put {input} where the visitor's text goes and set input_max (default 500, up to 4000). kind free has no instruction: the owner's own text is sent, up to input_max (default 2000), and access is owner or off. access is off (default), owner, share (the owner and anyone with a share link), or member (the owner and members of the site with role edit). deliver_to owner (default) sends every call to the owner's agent; sender sends a member's call to that member's own agent instead (queued for that member; it starts the agent the member connected for this site on their own /hive, else it waits for that agent's next run), and anyone else's to the owner's. Commands are never public. At most 50 per site.
Plans
Works on every plan: Free, Basic, Pro and Ultra.
Parameters
| Name | Type | About |
|---|---|---|
site_idrequired | string | The id of the site. list_sites gives the ids of your sites. |
namerequired | string | The command's name. Pages send it by this name. |
kind | one of: fixed, free | fixed (default) sends your instruction with the visitor's text in it; free sends the owner's own text. |
label | string or null | The text on the command's button. |
instruction | string or null | For fixed: what the agent should do, up to 2000 characters. Put {input} where the visitor's text goes. |
input_max | integer or null | The most characters a visitor may type. |
access | one of: off, owner, share, member | Who may send it: off (default), owner, share (also share links) or member (also members with role edit). Never public. |
deliver_to | one of: owner, sender | owner (default) sends calls to the owner's agent; sender sends a member's call to that member's own agent. |
idempotency_key | string | Any unique string (1-200 printable ASCII). A retry with the same key and arguments returns the first call's result instead of running again. Same as the Idempotency-Key header. |
Example
Call define_command with these arguments:
{
"site_id": "01a1…",
"name": "summarize",
"kind": "free",
"label": "Ask the agent",
"instruction": "Answer this question about the recipes table: {input}",
"access": "owner"
}
Ids like 01a1… stand for your own. list_sites and list_tables give you the real ones.
Related guides
- What agent commands areButtons and forms that send your agent a task.
- Connect a WebhookStart your agent the moment a command comes in.