# Control your agent’s actions Source: https://www.hyperagent.com/docs/guides/set-up-access-policy > For AI agents: the documentation index is at https://www.hyperagent.com/llms.txt and the complete documentation in one file at https://www.hyperagent.com/llms-full.txt. Any docs page is also served as Markdown by appending `.md` to its URL. Choose how your agent updates connected apps, then add rules for specific apps and actions. Give your agent room to complete routine work, with the oversight you choose. An **access policy** defines which actions your agent can take, when it needs your approval, and what it must stop. [Autonomy](https://www.hyperagent.com/docs/concepts/agents/autonomy) explains how these rules work with instructions and connected accounts. You'll configure and test a policy for your own agent before handing off work. This lets you check its limits before relying on it to act on your behalf. ## What you'll learn [#what-youll-learn] * **Choose how your agent updates apps:** Decide whether changes can proceed or need your approval for each type of run. * **Add specific restrictions:** Limit an app or action after choosing which run types may write. * **Review and test the result:** Check the proposed actions, save the policy, then try work you want to allow and stop. * **Narrow the scope with JSON:** Choose the run type and connected app before reaching for individual action names. ## Before you start [#before-you-start] * Use a saved, active agent you own. To change a workspace agent's policy, you must be a workspace Owner. * [Connect the app](https://www.hyperagent.com/docs/integrations) your agent needs and authorize the account and scopes for its work. A policy does not connect an app or grant account access. * Use test content you control. The worked example uses native Gmail and a test mailbox. ## Set up the policy in your own words [#set-up-the-policy-in-your-own-words] First decide which types of run may write without asking and which need your approval. ### Open the agent's access policy [#open-the-agents-access-policy] * Open the saved agent and select **About**. * Select **Autonomy**, then find **Access policy**. * **Alternative:** From **Work** or **Library**, select **Configure** to open the agent's configuration. * **Migrate to a policy:** Complete the short migration below. * **Current policy:** Continue to the next step. Migration turns the agent's saved **Auto**, Ask first, and run-specific write settings into policy rules. * Save or discard pending configuration edits. * Select **Migrate to a policy** to open the preview. * Review each rule, the work it covers, and its source setting. Read any note about inherited defaults. * If a rule shows Withholds, it preserves an earlier write restriction. It does not request approval by itself on unattended runs. [Read about Withholds](https://www.hyperagent.com/docs/concepts/agents/autonomy#permission-levels). * Select **Confirm migration** when the preview is right, or **Cancel** to keep the existing settings. * After confirming, check **Current policy** and each rule's status. - You cannot return to the previous controls after migrating. You can edit the policy afterward. - Migration preserves the existing write settings. Add restrictions on recipients or content afterward. * **If migration is refused:** Correct the settings named in the preview and try again. Nothing is migrated until confirmation succeeds. ### Choose how your agent updates connected apps [#choose-how-your-agent-updates-connected-apps] Decide when your agent can make changes in connected apps without asking and when it needs your approval. Choose this for each type of run. * Allow lets writes proceed without asking, within the agent's account access and other restrictions. * Ask requires your approval before a write. * Deny blocks the write. In **Access policy**, describe which run types may write without asking and which require your approval. For example: Allow writes in regular conversations where I can respond. Ask before writes from scheduled runs. | Type of run | Decide first | | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | Conversations | May the agent save, send, and change data without asking while you work together, or does it need your approval? | | Scheduled work | May scheduled runs complete writes without asking, or do they need your approval? | | Live Mode | May background checks make changes without asking, or do they need your approval? | | MCP clients | May work started by an MCP client write without asking, or does it need your approval? | | Incoming email | May work started by an incoming email write without asking, or does it need your approval? | | Webhooks | May work started by a webhook write without asking, or does it need your approval? | | [Delegated agent work](https://www.hyperagent.com/docs/concepts/agents/invocations/other-agents) | May work delegated from another agent write without asking, or does it need your approval? | | Queued follow-ups | May queued follow-ups, reminders, and resumptions write without asking, or do they need your approval? | ### Review and save the write permissions [#review-and-save-the-write-permissions] * Select **Draft policy**. * In **Proposed**, check the write permissions for each run type, including rules preserved from migration. * Select **Save** when the proposal matches your choices. * Check **Current policy** and each rule's **In force** status. ### Add a rule for a specific app or action [#add-a-rule-for-a-specific-app-or-action] For example, your agent may help prepare email replies in Gmail. However, you want to review the drafts on your own before sending. Keep the existing run-type permissions. Allow preparing drafts in Gmail. Deny sending Gmail messages, including replies, forwards, and existing drafts. * **Type of run:** Your earlier permissions decide whether updates may proceed without approval. * **Gmail actions:** Request a Deny rule for sending while keeping draft preparation allowed. * Select **Draft policy**. * Hyperagent shows the unsaved rules in **Proposed** for you to review. ### Review the proposed permissions [#review-the-proposed-permissions] Expand the proposed rule and check: * **Actions:** Which actions does it cover? * **Connection:** Which account or app does it apply to? * **Conditions:** How is each condition checked? For this example, confirm: | Check | What to confirm | | ----------------- | ------------------------------------------------------------------------------------- | | Draft preparation | Your agent may prepare and save drafts. Sending has a separate Deny rule. | | Sending | An explicit Deny covers sending, replying, forwarding, and sending an existing draft. | | Connection | The rule covers your intended Gmail connection. Resolve any warning before saving. | * **If something is missing:** Revise your request and select **Draft policy** again. * Review the actual proposed rules; they may differ from the illustration. * Use **Show JSON** to inspect their exact actions and scope. * Strict rule: Hyperagent checks an explicit condition directly. * Judge, per write: Hyperagent uses a separate AI policy checker to evaluate each proposed write against your rule. ### Save the reviewed policy [#save-the-reviewed-policy] * Select **Save**. * Check that **Current policy** contains the rules you reviewed. * Confirm that their restrictions show **In force** before testing. * If a rule is not in force, or Autonomy cannot load the policy, stop and follow its explanation. ### Test an allowed action and a stopped action [#test-an-allowed-action-and-a-stopped-action] * Start fresh work with your agent. * Try one action the policy should allow and one it should stop or send for approval. * Check the thread's tool activity and the result in the connected app. First, ask your agent for a test draft: Save a Gmail draft addressed to \[your test email address]. Use the subject “Draft-only policy test” and the body “This is a test draft for review.” Do not send it. * Use an address for a mailbox you control, and provide a recipient, subject, and body. * Review the thread's tool activity. * Check Gmail: the message should appear in **Drafts**, not **Sent**. * **If your agent pauses:** Inspect the policy's explanation. * Do not permit sending just to make the draft test succeed. To test the sending restriction: * Confirm that **Current policy** shows the sending Deny rules as **In force**. * Ask your agent to send the test draft to the same address you control. * Confirm that the sending action is stopped. If your agent asks for approval, do not approve it; review the policy explanation. * Check the thread's tool activity and Gmail's **Sent** folder to confirm that your agent did not send it. This example applies to the Gmail connection covered by the rule. * Keep other sending routes unavailable to your agent, including browser, script, or custom MCP access that could send email. * Read [Autonomy](https://www.hyperagent.com/docs/concepts/agents/autonomy) for the broader permission model. ## Use JSON for more granular control [#use-json-for-more-granular-control] JSON lets you edit the exact actions, app connection, conditions, and run filters in a rule. Use it to require approval for particular app changes or block an individual native action. The [JSON schema reference](https://www.hyperagent.com/docs/concepts/agents/autonomy/access-policy-json) describes every field and its values. ### Open the current policy [#open-the-current-policy] * In the agent's **Autonomy** section, find **Current policy**. * Select **Show JSON**, then **Copy policy JSON** to save a backup. * Select **Edit**. ### Set permissions for each type of run [#set-permissions-for-each-type-of-run] * **Operations:** Include append, write, and delete together in `ops`. * **Permission:** Choose Allow, Ask, or Deny. * Choose a type of run in the dropdown to see an example. #### Conversations Updates in conversations where you can respond. ```json { "effect": "allow", "ops": [ "append", "write", "delete" ], "trigger": { "electionCarrying": false, "attended": true } } ``` #### Scheduled work Updates during work started by a saved schedule. ```json { "effect": "ask", "ops": [ "append", "write", "delete" ], "trigger": { "kind": "scheduled" } } ``` #### Live Mode Updates during Live Mode checks. ```json { "effect": "ask", "ops": [ "append", "write", "delete" ], "trigger": { "kind": "alive" } } ``` #### MCP clients Updates during work started by an MCP client. ```json { "effect": "ask", "ops": [ "append", "write", "delete" ], "trigger": { "kind": "mcp" } } ``` #### Incoming email Updates during work started by incoming email. ```json { "effect": "ask", "ops": [ "append", "write", "delete" ], "trigger": { "kind": "email" } } ``` #### Webhooks Updates during work started by a webhook. ```json { "effect": "ask", "ops": [ "append", "write", "delete" ], "trigger": { "kind": "webhook" } } ``` #### Delegated work Updates during work delegated to another agent. ```json { "effect": "ask", "ops": [ "append", "write", "delete" ], "trigger": { "kind": "thread_ops" } } ``` #### Queued follow-ups Updates during queued follow-ups and reminders. ```json { "effect": "ask", "ops": [ "append", "write", "delete" ], "trigger": { "kind": "chat_queue_wake" } } ``` * Each example is one rule for the policy's `rules` array. * See [Thread filters](https://www.hyperagent.com/docs/concepts/agents/autonomy/access-policy-json#thread-filters) for advanced setup and the entire rules schema. ### Add an app-specific rule [#add-an-app-specific-rule] After choosing write permissions by run type, add conditions for a particular app: * Set `integration.slug` to the connection's actual app identifier. * Put write in the `ops` array. * Put the condition in `where.semantic`. With conversation writes set to Allow, this rule adds Ask before Notion changes: ```json { "effect": "ask", "ops": [ "write" ], "integration": { "slug": "notion" }, "where": { "semantic": "The request would create, update, delete, or share Notion content, or change its permissions." } } ``` For an app-based rule, write brings every app call into the policy check, including reads. Hyperagent's AI policy checker judges whether each call meets the condition. * Put the new rule objects inside the existing `rules` array. * Preserve unrelated rules and the outer policy settings. * Keep the `version` Hyperagent provides. If a change needs a different format, use **Draft policy** to describe the rules and let Hyperagent choose the compatible version. * Select **Preview**. * Check the write permissions for each run type, then the app-specific rule. * For the Notion example, confirm that the proposal adds an approval requirement and preserves the scheduled Ask rule and explicit denials. ### Save and test both rules [#save-and-test-both-rules] * Select **Save**. * Check **Current policy** and each rule's status. * Test through the run types you configured. A successful conversation does not demonstrate that a schedule or MCP run works. With these examples, test: * A conversation write that should proceed under Allow. * A scheduled write that should pause under Ask. * A Notion change that should require Ask, even in the allowed conversation. * Start with an app-based rule for connections such as standard Notion or Airtable. * For a native integration, put exact names from the [action catalog](https://www.hyperagent.com/docs/concepts/agents/autonomy/access-policy-json#integration-action-names) in `ops`, without `integration.slug`. * For example, `ops: ["GmailSendDraft"]` selects the action that sends an existing Gmail draft. It does not cover every way to send email. ## FAQ [#faq] * Check the permission for that type of run first. An applicable Ask rule still requires approval even when a more specific app rule says Allow. * To let updates proceed automatically, ask Hyperagent to change the existing Ask rule. Adding another Allow rule does not override it. * Check other applicable rules and the connected account's restrictions. * If an in-force rule still produces an unexpected failure, keep the thread link, exact error, and policy details for support. App access and permission for this run are separate checks. An account that can edit data does not authorize every agent action. Check the policy and run restrictions as well. * If an approved action still fails, preserve the error and failed-run details for support. * Set `trigger.kind` to scheduled. * Add the schedule's trigger-record ID in `trigger.ids`. Without IDs, the rule covers all scheduled work. * If an existing Ask rule covers that schedule, change that rule's scope while preserving the permissions for other schedules. A new Allow rule does not override it. * Add conditions for the permitted work afterward. Drafting and JSON Preview prepare an unsaved proposal. * Review **Proposed**. * Select **Save** to apply it. * If drafting fails, inspect **Current policy** to check what is saved. A fresh approval may be needed if the policy changed, the earlier approval expired, or an approved attempt failed. * If the same unchanged action keeps asking again unexpectedly, keep the request, thread link, and exact error for support. * Adding another Allow rule may not resolve it. * Some unattended work can request approval through **Inbox**. * `trigger.attended` means someone can answer an approval in the run's own conversation. A browser tab being open does not determine this. * Without an available approval path, the action cannot proceed. * Open **Current policy → Show JSON → Edit**. * Restore the complete backup you saved before editing. * Select **Preview** and review the proposed permissions. * Select **Save**. Restoring a backup also restores its other rules and settings. ## What's next [#whats-next] [Access policy JSON reference](https://www.hyperagent.com/docs/concepts/agents/autonomy/access-policy-json) Look up rule fields, nested conditions, run filters, and exact native action names. [Understand autonomy](https://www.hyperagent.com/docs/concepts/agents/autonomy) See how instructions, connected accounts, and policy checks work together.