Skip to Content
How-to guidesHow-to guidesRestrict who an agent can send to

Restrict who an agent can send to

A scope says what an agent may do: chat:write, Mail.Send, drive.file. A recipient constraint on the same grant says to whom. The broker reads the outgoing request, extracts the recipients, and refuses the call if any of them is outside the list. The agent gets a clean 403 with reason recipient_not_allowed; nothing is queued for approval, because the owner already decided on the grant itself.

Available on Studio and above, for the platforms the broker knows how to read recipients from: Slack, Gmail, Microsoft Outlook and Google Drive.

Add a constraint

  1. Open Agents and pick the agent.
  2. On the platform’s grant row, expand Restrict recipients.
  3. Add what applies to that platform:
    • Slack: channels. Type #general and pick from the list; the broker stores the channel id, so renaming the channel does not break the rule. You can also paste a raw C0123… id.
    • Gmail and Outlook: email domains (yourcompany.com) and individual addresses.
    • Google Drive: domains and addresses a file may be shared with, plus an allow public links switch that is off by default.
  4. Save. The grant row shows the constraint summary and the change is live on the agent’s next call.

Up to 64 channels per grant. Constraints apply to the whole grant row, so a Slack grant carrying both chat:write and channels:history keeps its reads: reads are recognised as such and pass without body inspection; only writes are checked against the list.

What the agent sees

A violation is a hard refusal:

{ "error": "Permission denied", "reason": "recipient_not_allowed",
  "constraint": { "kind": "recipients", "reason": "recipient_not_allowed", "violating": ["C0ABCDEF1"] } }

The audit row records the same, with the recipients that failed. If the request goes to an endpoint the broker cannot read recipients from, the call is refused rather than waved through (no_extractor); tell us which endpoint and we will add it.

Child agents

A child agent inherits its parent’s constraints and cannot loosen them. If the parent may only post to #deploys, every child may at most post to #deploys.

When to use this rather than a guardrail

A recipient constraint is per grant and names specific recipients. The external sends control is org-wide and about a boundary: anything leaving your organisation. Use both: the constraint for the agent that should only ever post to two channels, the control for every agent that might email a customer.

Last updated on
Manage org guardrailsRestrict which repositories an agent can reach