pagehive

define_command

Define an agent command a page can send with data-bp-command or bp.command.

Agent commandsChanges dataAll plans

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

NameTypeAbout
site_idrequiredstringThe id of the site. list_sites gives the ids of your sites.
namerequiredstringThe command's name. Pages send it by this name.
kindone of: fixed, freefixed (default) sends your instruction with the visitor's text in it; free sends the owner's own text.
labelstring or nullThe text on the command's button.
instructionstring or nullFor fixed: what the agent should do, up to 2000 characters. Put {input} where the visitor's text goes.
input_maxinteger or nullThe most characters a visitor may type.
accessone of: off, owner, share, memberWho may send it: off (default), owner, share (also share links) or member (also members with role edit). Never public.
deliver_toone of: owner, senderowner (default) sends calls to the owner's agent; sender sends a member's call to that member's own agent.
idempotency_keystringAny 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