STACK
MENU
DOCS / CONTROLS / POLICIES

Policies

How you write a policy for one agent or for all of them, what a policy can limit, how tightening differs from loosening, and how you try a call against a policy before it is live. What policies are and what they cost is on Controls.

Before you start

  • Controls must be on: see Switching controls on.
  • A policy only narrows. It can never give an agent more than its access already allows.
  • There is one default policy for the account, and an agent can have its own. An agent's own policy is the one in force for it.
  • Only the owner or an admin reads or changes a policy. An agent cannot see its own.

Read the policy in force

prompt
Show me the policy for the assistant agent.

The client calls stack_get_control_policy. From code or the terminal:

typescript
const { policy, in_force } = await stack.controlPolicies.get('agt_123');
const all = await stack.controlPolicies.list();
bash
npx @getstackrun/cli policies get agt_123
npx @getstackrun/cli policies get default

When controls were switched on, each agent got a policy named "Current access" that equals what it could already do. That is the place to start narrowing. For an agent that has none, policies start <agent> makes one.

Change a policy

A policy is one JSON document. Only the name is required:

json
{
  "name": "Assistant",
  "actions": { "kinds": { "card.checkout": "review", "browser.navigate": "deny" } },
  "recipients": { "email": ["@example.com"] },
  "spend": {
    "max_per_action_cents": 500,
    "limits": [{ "kind": "month", "unit": "cents", "limit": 5000 }]
  },
  "review": { "over_cents": 200 }
}
bash
npx @getstackrun/cli policies set agt_123 --file ./policy.json --expected-revision 3
typescript
await stack.controlPolicies.set('agt_123', definition, { expectedRevision: 3 });
  • To change a policy, send the revision number you read. If someone changed it in between, the call is refused and you read it again.
  • To make the first policy, leave the revision out.
  • Use default in place of the agent id for the account's default policy.
  • The tool is stack_set_control_policy.

What a policy can limit

  • actions.kinds - for each kind of action: allow, review (hold it for a person) or deny. A kind you do not name is allowed.
  • recipients - who email, texts and calls may go to. Email takes addresses or @domain. Texts and calls take numbers.
  • connections - which connected services may be used, and for what. In listed mode only the services named are allowed.
  • spend.max_per_action_cents - the most one action may cost.
  • spend.limits - a ceiling a day, a month or a Mission, in cents or in a count of actions.
  • spend.max_concurrent - how many actions may run at once.
  • spend.rules - ceilings for one merchant, one payee or one category of them.
  • review.over_cents - hold any action that costs more than this for a person.
  • surfaces - the models that may be called and the most one call may cost, the sites the browser may open, the merchants the card may pay, the payees the wallet may pay, how long a workspace command may run, and the paid tools that may run.

A list is a list of what is allowed. With no list there is no restriction. Day and month windows are in UTC.

Let an agent write only to people who wrote first

json
{ "name": "Replies only", "recipients": { "email": "per_mission" } }

With "per_mission" in place of a list, an email, text or call must name the received message it answers (reply_to_message), and goes only to whoever wrote that message. A reply does this by itself.

Tightening and loosening

  • A change that only narrows applies at once: a shorter list, a lower ceiling, allow to review, review to deny.
  • A change that widens anything needs your approval in a browser: a longer list, a higher ceiling, removing a limit, deny to review.
  • A change that narrows one thing and widens another counts as loosening.
  • Deleting a policy needs approval too, because the agent then falls back to the default policy or to none.
  • The answer to a change says which it was: tighten, loosen or unchanged.

Try a call before the policy is live

bash
npx @getstackrun/cli policies simulate --agent agt_123 --action card.checkout --amount-cents 900 \
  --definition ./draft.json
typescript
const result = await stack.controlPolicies.simulate({
  agent_id: 'agt_123',
  definition: draft,
  call: { action: 'card.checkout', amount_cents: 900 },
});

Simulate says whether the call would be allowed, held or refused, and by which rule. With no definition it tries the policy in force. Nothing runs and nothing is charged. The tool is stack_simulate_control_policy.

What an agent sees when a policy refuses

The call answers 403 CONTROL_DENIED and names the rule: the policy, its revision, the section and a code. It never repeats anything from the call. The refused action is not counted as an action. The codes you will meet most:

  • action_denied - the kind of action is set to deny.
  • recipient_not_allowed - an address or number is not on the list.
  • recipients_not_pinned - recipients are per_mission and the send names no message.
  • connection_not_listed - the service was granted after the policy was written. Add it to the policy.
  • amount_over_limit, merchant_not_allowed, payee_not_allowed, model_not_allowed, host_not_allowed, tool_not_allowed - a ceiling or a list in surfaces or spend.
  • limit_reached, concurrency_reached - a count of actions, or the number running at once.
  • review_required - the action is held for a person. See Approvals.

A limit in money is refused with 403 CONTROL_LIMIT_EXCEEDED, which says which limit and how much is left. Nothing is charged.

See earlier revisions

stack_list_control_policy_revisions, or policies revisions <policy-id>, lists every revision of a policy.

When a change is refused

  • 409 CONTROLS_NOT_ENABLED - controls are off.
  • 409 CONFLICT - the policy changed since you read it, or it exists and you sent no revision.
  • 403 GOVERNANCE_APPROVAL_REQUIRED - the change loosens. Approve it in the browser, then send it again.
  • 400 UNBOUNDED_SEND_RULE - a rule allows sending through a connected service without saying to whom. Name the recipients in the rule, or set the rule's recipients to per_mission.
  • 400 VALIDATION_ERROR - the document has an unknown key or a wrong value. The answer names it.
  • 404 NOT_FOUND - the agent has no account. Policies are for agents with an account.

Reference

Every field of a policy is on Controls. What happens to a held action is in Approvals.

Policies | Docs