Skip to main content

Approvals

The Approvals page is the central inbox where users review and respond to requests raised by AI agents that require human sign-off before continuing. When one or more requests are pending, the sidebar badge shows a live count so approvers can act without polling. The page subtitle reads either "Review and respond to agent approval requests." or, when there are outstanding items, the exact pending count followed by "pending — review and respond to keep agents moving."

Approvals flow from three possible delivery channels — in-app Chat, Email, and Microsoft Teams — and a decision made on any channel is immediately reflected across all others.

Who Receives a Request​

Approvers are decided by an approval policy on the tenant, not by the individual skill. A request can reach you as a named person or through a role you hold, and a single request may have several eligible approvers.

  • Named directly — The policy, or a skill's override, names you.
  • Through a role — The policy names a role, and the request reaches everyone currently holding it. Any eligible approver can decide, and the person who requested the action is excluded from their own request.
  • As the tenant fallback — Nobody more specific matched, so the request goes to the fallback approver configured for the tenant.

If no approver can be reached at all, the action is refused rather than held — an approval nobody can act on is not an approval. The agent is told why, so the run fails visibly instead of stalling.

Policies and per-skill overrides are described in Custom Skills.

Note: Every request records which policy matched it and why, shown on the request itself. Check it before deciding — it tells you what rule considers this action risky.

Note: For agents that run on a schedule or from a webhook, an approval-gated action stops the run and marks it failed, leaving the request pending here. A policy can target unattended runs specifically, requiring approval on a schedule while allowing the same action in chat.

Stats Tile​

A row of metric cells appears above the filter tabs, refreshing every thirty seconds. The cells surface a rolling window of tenant-level health signals so approvers can tell at a glance whether requests are moving or stacking up.

  • Pending — Current count of unanswered approval requests across the whole tenant; highlighted in the primary accent colour.
  • Decided (Xh) — Total approved plus rejected in the rolling window shown in parentheses (default 24 h).
  • p50 latency — Median decision time for the window, formatted as milliseconds, seconds, minutes, or hours depending on scale.
  • p95 latency — 95th-percentile decision time for the same window.
  • Expire rate — Percentage of decided requests that expired before a human responded; a rising value signals approvers are not reaching items in time.
  • Channel delivery — One cell per configured delivery channel (for example email delivery) showing the percentage of notifications that landed successfully.

Filter Tabs​

Three tabs sit above the request list and filter which approvals are shown. The Pending tab carries a live badge with the count whenever there are outstanding items.

  • Pending — Shows only requests awaiting a decision.
  • Resolved — Shows requests that have been approved, rejected, expired, or cancelled.
  • All — Shows the full history regardless of status.

My Channels Preference​

The My channels button to the right of the filter tabs opens a compact popover where each user controls which extra channels deliver approval pings to them personally. The in-app Chat surface is always active and is not shown here because it drives the sidebar badge regardless of preference. Optional channels are:

  • Email — Sends a transactional email containing a single-use link the recipient can click to approve or reject without opening the app.
  • Microsoft Teams — Delivers an Adaptive Card from the Beak Teams bot with inline Approve and Reject buttons. Requires the originating agent to have Microsoft Teams deployed.

Saving updates the preference immediately; clicking Cancel discards any changes.

Request List​

The left panel of the split-pane layout lists all approval requests matching the active tab filter. The header shows the total count as "N request" or "N requests". Each row contains:

  • Requester avatar — Initials of the user or system that triggered the request, drawn from the requester name or user ID.
  • Requester name and agent — The display name of the requester alongside the name of the agent that raised the request.
  • Prompt excerpt — Up to two lines of the approval question posed by the agent.
  • Channel icons — Small icons for each delivery channel on which the notification was successfully sent or delivered (Chat, Email, Teams, Slack).
  • Timestamp — Relative time since the request was created (for example 14m ago).
  • Expiry badge — For pending items, a clock badge shows how much time remains before the request expires (for example 2h left).
  • Status badge — For resolved items, the terminal status (approved, rejected, expired, cancelled) is displayed instead of the expiry.

Clicking any row selects it and opens the full detail pane on the right; the selected row is highlighted with a primary-colour left border.

Request Detail Pane​

The right panel shows the full detail of the selected approval request. The pane is divided into three zones.

Displays the agent name and current status as an eyebrow label, the full approval prompt as the primary heading, and the requester identity plus creation timestamp as secondary text.

Body​

  • Tool payload — What the agent wants to do, rendered as labelled fields rather than raw JSON so the action can be judged without reading code. Nothing is hidden: long values expand in place rather than truncating, and a Show raw JSON toggle reveals the exact payload for anyone who wants to check the rendering.
  • Comment field — For pending requests, a free-text area is shown beneath the payload labelled "Comment (optional)". The placeholder reads "Add a note explaining your decision…". Any text entered here is stored with the decision and visible to the agent.
  • Decision summary — For resolved requests, a read-only block shows the outcome (Approved or Rejected), which channel the decision was submitted through, the timestamp, and any comment that was recorded.

Action Bar​

For pending requests, two action buttons appear pinned to the bottom of the pane.

  • Reject — Rejects the request and halts the pending agent action. The button is styled with the error colour.
  • Approve — Approves the request and allows the agent to proceed. The button shows Submitting… while the API call is in flight.

Both buttons are disabled during submission. For resolved requests the action bar is hidden; the decision summary in the body section serves as the permanent record.

Approving from a Chat Conversation​

When an agent needs approval part-way through a conversation, the run pauses and an approval card appears inline in the chat. The card takes one of two shapes depending on whether the policy allows you to answer it.

When you can approve it yourself​

If the matched policy names you as an approver, the card shows Approve and Reject buttons alongside everything needed to decide: the action, its inputs, the rule that fired, who else was asked, and when the request expires. Answering resumes the conversation immediately and the agent continues in place.

When somebody else must approve it​

Most requests reach a different person than the one chatting. Separation of duty is on by default, which removes the requester from the approver list unless a policy names them explicitly — so the person who triggered the action usually cannot sign it off.

In that case the card shows the same information without buttons, plus a plain statement of who is holding it, for example "Sent to Alice Smith — 2 approvals required. You cannot approve this yourself."

The conversation is held closed while the request is outstanding: the message box is replaced by a waiting notice. This is deliberate — the agent is paused mid-turn, and a new message would start a second turn over a run that is still waiting to be answered.

You do not have to stay on the page. Once an approver answers, from the Approvals inbox or from any other channel:

  • the conversation resumes on its own and the agent's continuation appears in the thread;
  • the requester receives an Approval resolved notification naming the decision and who made it;
  • the card briefly shows the outcome — "Approved by Alice Smith — the agent is continuing" — before the reply arrives.

Reloading the page does not lose the card. A conversation that is paused for approval shows its card again on reopen, so a blocked chat is never mistaken for an idle one.

Quorum in chat​

When a policy requires more than one approval, a single decision made in chat is recorded but does not release the action. The card confirms "Your decision was recorded. This action needs more approvals before it can run." and the conversation stays paused until the required number of approvers have agreed. A single rejection is final regardless of how many approvals were required.

Rejections​

A rejected action is not silently dropped. The agent is told the request was refused, along with any comment the approver left, so it can explain the outcome or take a different route rather than stopping without a word.

Best Practices​

  • Monitor the p50 and p95 latency cells — If either grows beyond your service-level expectations, consider enabling the Email or Teams channel so approvers receive out-of-app prompts.
  • Set the Email channel when approvers are frequently away from the app — The single-use link in the email allows a decision to be submitted from any device without logging in.
  • Use the comment field on rejections — Agent developers can inspect the stored comment to understand why a request was declined and adjust the agent's prompting accordingly.
  • Check the expire rate tile regularly — A non-zero expire rate means agents are being blocked and eventually timing out; routing notifications to additional channels reduces this.
  • Expect to approve from the inbox, not from the chat — Because separation of duty excludes requesters from their own requests, the chat card is usually informational for the person chatting and actionable for someone else. Configure Email or Teams so that approver is reached promptly; the conversation stays paused until they answer.
  • Use the Resolved tab for audit trails — Every decision, the channel it came through, and any comment is retained in the resolved view for compliance review.