Skip to content
OpenBot

Rules and Grants

Decisions about requests do not have to be made again and again. OpenBot keeps them in two forms:

Form Looks like Who checks it
Grant apps.call on conn-7/search_orders, allow, for this Session OpenBot, by exact match
Rule “The Programmer may read any repository of the openbot organization, but asks before a push.” A judge model

A Grant is fast and exact. A Rule covers a whole kind of request.

Grants

A Grant is a kept decision about one capability of one Agent. The Agent never sees its Grants. It only sees that some calls run and some are denied.

Field Meaning
capability action, target (* for every target) and optional exact arguments.
effect allow or deny. A deny wins.
scope once (used up by one call), session or lifetime.
grantedBy The person, Agent or Rule that decided.
parent The Grant of the decider that this Grant came from.
status active, used or revoked.

OpenBot makes Grants when a decider answers a request. You can also make one yourself:

Terminal window
curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"capability":{"action":"agents.spawn","target":"*"},"effect":"allow","scope":"lifetime"}' \
  https://api.example.com/v1/agents/$AGENT/grants

GET /v1/agents/:agentId/grants lists Grants. Add ?status=active to see only active ones.

DELETE /v1/agents/:agentId/grants/:grantId revokes a Grant. OpenBot also revokes every Grant that came from it, so Agents below lose what they got through it.

Rules

A Rule is a sentence in plain language for one Agent. When no Grant decides a request, a judge model reads the active Rules of the Agent.

  • The judge allows only when a Rule clearly allows this request, and denies only when a Rule clearly forbids it. In every other case, the request goes to the decider.
  • Each allow or deny must quote the text of a Rule. OpenBot checks the quote. Without a real quote, there is no decision.
  • A deny wins over an allow.
  • When the judge fails or is slow, there is no decision.

A Rule that an Agent wrote counts only when that Agent may use the capability itself.

Terminal window
curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"The Programmer may read any repository of the openbot organization, but must ask before it pushes to main."}' \
  https://api.example.com/v1/agents/$AGENT/rules
Field Meaning
author The person or Agent that wrote the Rule.
status active, proposed or retired. Only active Rules count.
version Goes up with each change.

A Rule from a person is active at once. An Agent can propose a Rule in a review. A proposed Rule counts only after a person makes it active:

Terminal window
curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected":0,"status":"active"}' \
  https://api.example.com/v1/agents/$AGENT/rules/$RULE

You can also keep a Rule when you answer a request: send rule with the answer. See Answer a request.

The judge model

The judge uses the helper model, a model that OpenBot uses for its own work. It is helperModel in the organization settings. By default it is the default model of the organization. OpenBot keeps each judge answer for the same Rules and the same capability, so the judge does not run again for the same question.