From da75845fcfa635e7dfb5b0fabcd77b1743a2f318 Mon Sep 17 00:00:00 2001 From: arc53-machine <232052973+arc53-machine@users.noreply.github.com> Date: Tue, 29 Sep 2026 17:35:17 +0100 Subject: [PATCH] Document sharing agents and whose access what they use runs with A new "Sharing agents and what they use" section covers viewers and editors, whose access each tool, source and prompt runs with as the share dialog labels it, sponsors, stopped resources, what API, widget and public-link users can't do without the write allowlist, the wiki switch and research steps. The sharing rules now mention the editor switches and member-mode tools, the guardrails page no longer says editors can't change guardrails, the connector guide uses the new tool share labels, and related pages link to the section. --- docs/content/Agents/basics.mdx | 1 + docs/content/Agents/guardrails.mdx | 2 +- docs/content/Deploying/Access-Control.mdx | 32 ++++++++++++++++++++--- docs/content/Guides/Connectors.mdx | 6 +++-- docs/content/Sources/Wiki-sources.mdx | 2 +- 5 files changed, 35 insertions(+), 8 deletions(-) diff --git a/docs/content/Agents/basics.mdx b/docs/content/Agents/basics.mdx index c3afd758..7f9cccec 100644 --- a/docs/content/Agents/basics.mdx +++ b/docs/content/Agents/basics.mdx @@ -113,6 +113,7 @@ Once an agent is created, you can: * Modify any of its configuration settings (name, description, source, prompt, tools, type). * **Generate a Public Link:** From the edit screen, you can create a shareable public link that allows others to import and use your agent. * **Get a Webhook URL:** You can also obtain a Webhook URL for the agent. This allows external applications or services to trigger the agent and receive responses programmatically, enabling powerful integrations and automations. +* **Share it with a team:** Viewers chat with it; editors can also change it. The share dialog lists what the agent uses and whose access each item runs with. See [Sharing agents and what they use](/Deploying/Access-Control#sharing-agents-and-what-they-use). * **Use it via API:** Every agent exposes an API key that can be used with the native [Agent API](/Agents/api) or the [OpenAI-Compatible API](/Agents/openai-compatible) so you can drop DocsGPT Agents into any tool that already speaks the chat completions protocol. ## Seeding Premade Agents from YAML diff --git a/docs/content/Agents/guardrails.mdx b/docs/content/Agents/guardrails.mdx index eb645725..cf0e8c1a 100644 --- a/docs/content/Agents/guardrails.mdx +++ b/docs/content/Agents/guardrails.mdx @@ -172,7 +172,7 @@ Open the agent in the builder and expand the **Guardrails** section. Checks that cannot run without settings (`denylist`, `url`, `policy`, and `pii` with no entities selected) are marked *Not configured* and block saving until they are filled in, so a half-configured control can never be published as if it were protecting you. -Guardrails are the **agent owner's** policy. Team members with edit access can see the configuration but cannot change it — an editor who could clear a control would silently strip protection from everyone using the agent. Controls required by the instance floor (below) appear locked and cannot be removed. +Guardrails, like the agent's limits, are policy that the owner and the agent's team **editors** can change. Viewers don't see the configuration. To keep a control that nobody who edits the agent can remove, require it in the [instance floor](#the-instance-floor): floor controls appear locked for everyone. See [Sharing agents and what they use](/Deploying/Access-Control#sharing-agents-and-what-they-use) for what else viewers and editors can do. Guardrails also apply to a **draft** agent in the builder preview, which is the natural place to try a control before publishing. diff --git a/docs/content/Deploying/Access-Control.mdx b/docs/content/Deploying/Access-Control.mdx index 14f319cf..f941fd3c 100644 --- a/docs/content/Deploying/Access-Control.mdx +++ b/docs/content/Deploying/Access-Control.mdx @@ -138,13 +138,37 @@ Four resource types can be shared: **agents**, **sources**, **prompts**, and **t Sharing rules: -- Only the **owner** of a resource can share it. +- Only the **owner** of a resource can share it, unless they turn on **Editors can share** in the share dialog's **Access settings**. - A share targets either the **whole team** or a **single member**. - Each share carries an access level: **`viewer`** (read-only) or **`editor`** (read and modify). -- `editor` is not the same as owner — an editor can change a resource but cannot delete it or re-share it. -- Shared tools run server-side with the **owner's** credentials; a grantee never sees the owner's secrets. +- `editor` is not the same as owner — an editor can change a resource but cannot delete it or re-share it unless the owner turns on the matching switch. +- Shared tools run server-side with the **owner's** credentials, or with each member's own account when a connected tool is shared that way; a grantee never sees the owner's secrets. - A wiki's editors can edit its pages, but only its owner decides whether API and widget users can edit it through an agent (see [Wiki sources](/Sources/Wiki-sources#edits-from-the-api-widget-and-public-links)). +### Sharing agents and what they use + +Sharing an agent lets people use it; it doesn't share its tools, sources or prompt. Those stay yours, and people reach them only through the agent. + +- **Viewers** chat with the agent. They don't see its configuration, and they never open its share dialog. +- **Editors** open its edit page and change it: its instructions, model, tools, sources and prompt, and its [guardrails](/Agents/guardrails) and limits. They can share it or delete it only when you turn on **Editors can share** or **Editors can delete**. + +Every tool, source and prompt on the agent runs with someone's access, the same for everyone who uses the agent. The agent's share dialog lists them under **What this agent uses**, for you and its editors. For a workflow agent, the list also includes the tools and sources on its nodes. + +| The item | Runs with | The list says | +| --- | --- | --- | +| Yours, or shared with you | Your access | **Your access** (an editor sees **The owner's access**) | +| Added by an editor, and you can't use it | The editor's access; they are its [sponsor](#resources-an-editor-adds-to-someone-elses-agent) | **dana@example.com's access** | +| A connected tool shared as **Your account** | That account on the service | **Your Notion account**, or **dana@example.com's Notion account** for a teammate's tool | +| A connected tool shared as **Each person's own** | The account of whoever uses the agent; they connect it the first time | **Each person's own Notion account** | + +An editor becomes a sponsor only after confirming who will reach the resource through the agent. A resource whose sponsor or owner loses access stops running and is marked **Stopped** in the list, with the reason (see [When a resource stops working](#when-a-resource-stops-working)). + +Some runs are limited, because nobody can approve an action for you there: + +- **API key, website widget and public link.** A write action on your connected accounts or saved credentials runs only if you allow it under **Access details > Actions API, widget and public-link users can take as you**. Only the owner can change that list. The share dialog marks tools with actions that aren't allowed as **No API changes**. On a tool shared as **Each person's own**, public-link users act with their own account and approve their own writes. See [Agents used through an API key](/Guides/Connectors#agents-used-through-an-api-key). +- **Wikis.** API and widget users edit a wiki only when its owner turns on **Let API and widget users edit this wiki** in its **Wiki settings**. Public-link users edit only wikis they can edit themselves, and approve each edit (see [Wiki sources](/Sources/Wiki-sources#edits-from-the-api-widget-and-public-links)). +- **Research agents.** A research step can't stop to ask, so it skips any action that would need approval or a connection, and any write the caller may not make on your accounts. The step is told why and carries on (see [Research Agent](/Agents/basics#3-research-agent)). + ### Resources an editor adds to someone else's agent An agent (and its workflow) runs as its owner, so its tools, sources and prompts are checked against the owner's access. When a team editor adds one the owner can't use, it runs with the **editor's** access instead, for everyone who uses the agent: members of the teams it is shared with, anyone with its API key or website widget, its public link and its webhook. The editor becomes that resource's **sponsor**. @@ -189,7 +213,7 @@ Every run checks each tool, source and prompt on the agent (and each tool and so | `connection_removed` | The connection was removed but the tool was kept. | Ask the tool's owner to connect the account again, or remove it. | | `connector_disabled` | An admin turned the service off. | Ask an admin to turn it back on, or remove it. | -**Remove** takes the item off the form; save to store it. Through the API, `GET /api/get_agent` and `GET /api/workflows/` return `resource_states` to owners and editors (an empty list to everyone else): one entry per attached resource with `key`, `type`, `id`, `name`, `state` (`active` or `stopped`), `reason`, `sponsor` and `contact` (`{user_id, label}`: the recorded sponsor, and someone else who can fix it), `connection` (the service, for a connection reason), `can_confirm` and `can_reconnect`. When anything can be taken over, the response also carries `sponsor_audience`, the same shape as `audience` above. A name is shown only for a resource that runs, that someone sponsored, that you can see yourself, or that is on an agent (agent saves check every reference). +**Remove** takes the item off the form; save to store it. Through the API, `GET /api/get_agent` and `GET /api/workflows/` return `resource_states` to owners and editors (an empty list to everyone else): one entry per attached resource with `key`, `type`, `id`, `name`, `state` (`active` or `stopped`), `reason`, `sponsor` and `contact` (`{user_id, label}`: the recorded sponsor, and someone else who can fix it), `connection` (the service of a connected tool), `can_confirm` and `can_reconnect`. A running tool also has `credential_mode` (`owner` or `member` for a connected tool, else `null`), `account` (whose account an `owner`-mode connection acts as) and `owner_credential_writes` (its write actions on credentials its owner stored, which the API write allowlist covers). When anything can be taken over, the response also carries `sponsor_audience`, the same shape as `audience` above. A name is shown only for a resource that runs, that someone sponsored, that you can see yourself, or that is on an agent (agent saves check every reference). The check is the one the run uses, so the page never shows a resource as running when the run leaves it out. Each resource a run leaves out is logged as `resource_stopped` with the agent or workflow, the resource's type and id, and the reason. diff --git a/docs/content/Guides/Connectors.mdx b/docs/content/Guides/Connectors.mdx index 2db94f13..0beb33f3 100644 --- a/docs/content/Guides/Connectors.mdx +++ b/docs/content/Guides/Connectors.mdx @@ -42,8 +42,10 @@ If a provider rejects a token that DocsGPT cannot refresh, the connection is mar Sharing a tool that uses a connection asks whose account team members use: -- **Team members use my account.** Everyone acts as your account on that service. When the tool can write, you confirm this before sharing, and a member's write actions always need approval. -- **Each member connects their own account.** Members see a **Connect** prompt the first time they use the tool. +- **Your account.** Everyone acts as your account on that service. When the tool can write, you confirm this before sharing, and a member's write actions always need approval. +- **Each person's own.** Each person uses their own account, and sees a **Connect** prompt the first time they use the tool. + +An editor you let share the tool sees your choice as **The owner's account** and can't change it. An agent's share dialog shows the same words for each connected tool on the agent (see [Sharing agents and what they use](/Deploying/Access-Control#sharing-agents-and-what-they-use)). Tools from OAuth MCP servers default to each member's own account. An admin can force one mode for a connector. diff --git a/docs/content/Sources/Wiki-sources.mdx b/docs/content/Sources/Wiki-sources.mdx index 4f568ca9..43afb37a 100644 --- a/docs/content/Sources/Wiki-sources.mdx +++ b/docs/content/Sources/Wiki-sources.mdx @@ -114,5 +114,5 @@ PUT /api/sources//wiki/settings # owner only; body {"allow_outside_ ## Related - [Per-Source Configuration](/Sources/Per-source-configuration) — exposure and retrieval settings a wiki uses. -- [Access Control & Teams](/Deploying/Access-Control) — sharing a wiki with a team. +- [Access Control & Teams](/Deploying/Access-Control) — sharing a wiki with a team, and [what an agent's users reach](/Deploying/Access-Control#sharing-agents-and-what-they-use) when you share the agent. - [Connectors](/Guides/Connectors#agents-used-through-an-api-key) — what else an agent can and can't do for API, widget and public-link users.