> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Approvers and notifications for shared agents

> Choose who in your organization approves a public agent's requests and who hears from its background work, how the first decision wins, and what stays with the person using the agent

A [public agent](/concepts/organizations-and-roles#what-an-organization-owns) can name **approvers** and **notification recipients** from its organization. Every approver receives the same approval request, the first decision wins, and every other copy updates to show who decided. The agent's own background work, such as a webhook or a job with no user, can now reach people through the inbox instead of reaching nobody. Personal work, such as someone's chat or their own scheduled task, still goes only to that person.

*Requires the Lua desktop app 0.68.0 or later.*

## Turning it on

The feature is off for every organization until an admin turns it on, and then it applies agent by agent.

<Steps>
  <Step title="Turn on the organization switch">
    An organization owner or admin turns on the switch in any of these places:

    * **Desktop app** (recent versions): **Settings** › **Workspace** › **Team settings** › **Workspace** tab › **Shared agents** card › **Choose approvers for shared agents**. Other members see the setting read-only.
    * **Admin dashboard**: **Organization settings** › **Shared-agent approvers** › **Approvers for shared agents**.
    * **API**: `PUT /admin/orgs/:orgId/shared-agent-routing` with `{ "enabled": true }` (`org:manage`). See [Shared-agent routing](/reference/rest/shared-agent-routing#organization-switch).
  </Step>

  <Step title="Share the agent">
    In the desktop app, open **Settings** › **Agent** and turn on **Share agent with workspace** (`builder` and above). The settings apply only while the agent is public and is not a [Space](/concepts/spaces). The desktop app shows the pickers only once the agent is shared and the organization switch is on. When the switch is off, owners and admins see a link to turn it on. In the admin dashboard, a private agent shows **Share this agent with the organization to use approvers.** Over the API you can save the settings while the agent is private, and they apply once it is shared.
  </Step>

  <Step title="Choose approvers and recipients">
    In the desktop app, open **Settings** › **Agent**. Under the share switch:

    * **Choose who can approve**: the approvers.
    * **Require someone other than the person who triggered it**: the person who started a run or triggered a request can't decide it.
    * **Include workflow approvals that ask the person who started the run**: on by default. Sends workflow approval steps that name the run's creator to the approvers as well; see [Workflow approvals](#workflow-approvals).
    * **Choose who gets notifications**: the notification recipients.
    * **Notify whoever triggered it too**: sends notices to the person who triggered the work, when there is one, as well as to the recipients.

    The agent's details then show **Approvers:** with the chosen names.

    In the admin dashboard, open the agent, then **Settings** › **Approvers**. The **Approvers and notifications** card has the same pickers and the three options; select **Save** to apply them. Over the API, use `PUT /admin/agents/:agentId/routing` (`agents:manage`).
  </Step>
</Steps>

An approver must hold `operator` or above on the agent, which is the right to run and approve its workflows. A notification recipient must be an active member of the organization. The platform checks this when you save, and again when a request is sent or decided. A member who is demoted below `operator` after being chosen can no longer decide.

## Who gets what

| What happens                                                                                  | Who receives it                                                                                                                                                                                                                          |
| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A workflow approval step whose approver is `'creator'`, on a public agent with approvers      | The person who started the run, plus every approver; without the person who started it when **Require someone other than the person who triggered it** is on                                                                             |
| A workflow approval step with any other approver                                              | Unchanged: whoever the step names                                                                                                                                                                                                        |
| A notice (`User.Inbox.push` without `options`) from the agent's background work               | Every notification recipient, plus the person who triggered it when **Notify whoever triggered it too** is on and there is one                                                                                                           |
| A question (`User.Inbox.push` with `options`) from the agent's background work                | Every approver; never the notification recipients. Without the person who triggered it when **Require someone other than the person who triggered it** is on, unless they are the only approver. With no approvers, it behaves as before |
| Anything from personal work: a chat, a member's own scheduled task, a trigger bound to a user | Only that person, as before                                                                                                                                                                                                              |

When the organization switch is off, the agent is private, or no one is chosen, everything behaves as it did before.

## Workflow approvals

An [approval step](/build/workflows/approvals-and-signals) whose `approver` is `'creator'` (the default) asks the person who started the run. On a public agent with approvers, and with **Include workflow approvals that ask the person who started the run** on, the step also goes to every approver.

* **Everyone gets a copy.** In the desktop inbox, a copy reads **Sent to you and N others**.
* **The first decision wins.** Every other copy updates to show who decided, such as **Approved by Priya**. Someone who acts on a copy after that sees **Already approved by Priya** (or **Already denied by** …). Over the API, the late decision answers `{ "resolved": false, "outcome": "noop", "reason": "already_resolved", "decision", "decidedBy" }`; see [Workflow approvals](/reference/rest/workflow-approvals#approvals).
* **"Require someone other than the person who triggered it"** removes the person who started the run. They get no copy, and a decision from them is refused with `403 NOT_AN_APPROVER`, reason `initiator`, on every surface.
* **What the author wrote wins.** A step that names its approver explicitly — `'org-admins'`, `{ users }`, `{ role }`, `{ group }`, or `{ governance }` — is never changed. Neither is a step with `fourEyes`, nor a per-item approval whose item names its own approver.

Pending requests follow the settings. When the list changes, added approvers receive the pending request, removed approvers' copies are withdrawn, and everyone else's copy is left as it is. When a member is removed from the organization or deactivated, their copies are withdrawn. When the agent is made private, pending requests go back to the person who started the run.

## Background work and personal work

Work the agent does for itself is **background work**:

* A [webhook](/concepts/webhooks).
* A [trigger](/concepts/triggers) that is not bound to a user.
* A [job](/concepts/jobs) with no user.
* A workflow run that runs as the system.
* An agent turn that one of these starts.

Before this feature, `User.Inbox.push` from background work had no one to deliver to and refused with `no_user_context`. On a public agent with recipients chosen:

* **A notice** goes to every notification recipient, and to the person who triggered it when **Notify whoever triggered it too** is on and there is one. Each person gets their own card: dismissing it dismisses only their copy, and pushing again with the same `key` updates everyone's card.
* **A question**, a push with two or more `options`, goes to every approver. Notification recipients who are not approvers don't receive it. With no approvers chosen, a question behaves as before: it goes to the person who triggered the work, or is refused with `no_user_context` when there is no such person. With **Require someone other than the person who triggered it** on, the person who triggered the work gets no copy of a question and can't answer it, as long as at least one other approver is set. If they are the only approver, the question goes back to them as an ordinary question, as it would without approvers. Workflow approval steps behave differently: they escalate to the organization's admins instead. Only an option answers it; a free-text answer is refused with `400 ROUTED_QUESTION_OPTION_ONLY`, and a reply typed in the chat does not answer it. The first answer wins, and a later one gets `409 QUESTION_ALREADY_ANSWERED` with `answeredBy`. The agent then continues with `Answered by <name>: <option label>`.

**Personal work never fans out:**

* A chat with the agent.
* A trigger bound to a user.
* A desktop scheduled task, including one the agent's owner set up.

These go to the person whose work it is, as before.

Without the organization switch, or with no one chosen to receive it (notification recipients for a notice, approvers for a question), a push from background work that has no triggering person still refuses with `no_user_context`. See [`User.Inbox`](/reference/sdk/inbox) and [Execution contexts](/concepts/execution-contexts).

## What stays personal

These are never sent to approvers or recipients; they stay with the person using the agent:

* Approvals in the governance console.
* Computer Control approvals.
* Draft and review cards.
* Consent to use a personal connection.
* Anything from a run started by a customer: an end user reaching the agent on a channel who is not a member of the organization. It is never sent to approvers.

## Limits

| Item                              | Value                                                |
| --------------------------------- | ---------------------------------------------------- |
| Approvers per agent               | 20                                                   |
| Notification recipients per agent | 50                                                   |
| Who can approve                   | Active members with `operator` or above on the agent |
| Who can be notified               | Active members of the agent's organization           |
| Desktop app                       | 0.68.0 or later                                      |

On a phone, a notification for an approval someone else already decided is not yet cleared; the inbox shows the decision.

## Next steps

<Columns cols={2}>
  <Card title="Shared-agent routing API" href="/reference/rest/shared-agent-routing">The organization switch and each agent's approvers and recipients over REST.</Card>
  <Card title="Approvals and signals" href="/build/workflows/approvals-and-signals">Approval steps and their `approver` options.</Card>
  <Card title="User.Inbox" href="/reference/sdk/inbox">Notices and questions from your code.</Card>
  <Card title="Organizations and roles" href="/concepts/organizations-and-roles">Public and private agents, and what each role can do.</Card>
</Columns>