---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - fleet
  - governance
  - security
topic: LangSmith Fleet 身份、权限、审批与 Workspace 治理
sources:
  - https://docs.langchain.com/langsmith/fleet/access-and-oversight
  - https://docs.langchain.com/langsmith/fleet/agent-identity
  - https://docs.langchain.com/langsmith/fleet/auth-format
  - https://docs.langchain.com/langsmith/fleet/manage-agent-settings
  - https://docs.langchain.com/langsmith/fleet/workspace-admin
last_verified: 2026-08-11
---

# Fleet：身份、权限、审批与 Workspace 治理

Fleet 的治理不是一个开关，而是 Agent 分享权限、Agent 身份/凭据、工具 RBAC/ABAC、内置集成 workspace gate、工具审批、trace 审计、secret 与预算的组合。任何单层都不能替代其余层。

## Agent identity 是不可逆设计决定

创建后设置的 Agent identity 当前不能修改，需要变更时只能新建 Agent。两种模式：

| 身份模型 | 官方别名 | 凭据来源 | 适合 | 主要风险 |
|---|---|---|---|---|
| Fixed credentials | Claws | 始终使用 Agent owner 连接的一套 API key/OAuth token | 团队 Slack bot、共享资源、channels、schedules | 所有人以同一主体操作，权限放大，审计需额外关联调用人 |
| User credentials | Assistants | 每个调用者首次连接自己的账户，以其 token 操作 | 私人邮件、按用户权限访问数据 | 每位用户要授权；跨用户行为与后台触发受限 |

Channels 和 schedules 要求 fixed credentials，因为无人触发时没有可用的最终用户 OAuth 上下文。固定身份应使用专用 service account、最小权限、可轮换凭据，避免绑定个人离职账户。

## Agent 分享不是线程共享

Agent 可以 private、workspace-wide 或分享给特定人。权限维度包含：

- **Clone**：复制并形成自己的可编辑副本；
- **Run**：使用但不能改配置；
- **Edit**：修改 instructions、tools 与 settings。

可把 Edit 给核心团队、Run 给组织、Clone 给需要二次定制的人。工作区 Agent 的 system prompt、工具选择、sub-agents 与 channel 类型对工作区用户可见；具体 OAuth connection 和 channel 实例不共享。线程始终 user-scoped，即使 Agent 是 workspace scope，聊天历史也只属于创建该 thread 的用户。

这意味着：共享 Agent 配置不会自动授予原 owner 的私人 OAuth 连接；但 workspace secrets 是 workspace-scoped，private 与 workspace Agent 都可能使用它们，因此 secret 的权限面要单独治理。

## 工具访问的三层策略

企业版工具控制覆盖 custom MCP server 与内置 integrations。

### RBAC

`mcp-servers:*` 权限：

| 权限 | 能力 |
|---|---|
| `read` | 发现和列出 MCP servers/integrations |
| `invoke` | 调用工具，含 OAuth connect/disconnect |
| `create` | 新建 MCP server 配置 |
| `update` | 修改 server 配置 |
| `delete` | 删除 server 配置 |

`read + invoke` 会让角色看见并使用 workspace 中全部 MCP servers 和 integrations，不能误以为它天然是细粒度授权。

### ABAC

ABAC 可按 tag 对 `mcp_server` 与 `fleet_integration` 资源做 allow/deny。它既能给无通用 RBAC 权限的角色只开放某些标签资源，也能从有广泛 RBAC 权限的角色中排除高风险资源。

### Workspace integration policy

内置 integrations 还有 workspace 管理员控制的全局启停 gate。禁用后任何 RBAC/ABAC 都不能重新开放；该页面需要 `workspaces:manage`。

### 精确求值顺序

```mermaid
flowchart LR
    A["内置集成 Workspace gate"] --> B["ABAC deny"]
    B --> C["RBAC"]
    C --> D["ABAC allow 补充授权"]
```

Custom MCP 不经过第一步，顺序是 `ABAC deny → RBAC → ABAC allow`。Deny 永远优先；内置集成若 workspace gate 关闭，后续完全不评估。生产排障应按这个顺序查，不能只看角色权限。

## 人工审批与 auth interrupt 是不同机制

工具在 Connections 中可设：

- **Auto**：直接执行；
- **Ask**：执行前暂停，用户 Accept 或 Reject 并可给修正意见。

Fleet 有跨 Agent 的中央 approvals inbox，Slack trigger 也可在原 thread 中 Approve/Deny。审批能降低副作用风险，但不是权限系统：一个本来无权调用工具的人不能靠批准绕过 RBAC/ABAC；一个拥有权限的 Agent 也不能因为有审批就忽略输入校验、幂等和审计。

自定义工具需要 OAuth 时，可以只返回以下 JSON 字符串：

```json
{
  "auth_required": true,
  "auth_url": "https://auth.example.com/start",
  "auth_id": "opaque-tracking-id"
}
```

Fleet middleware 识别后暂停、显示授权 UI，成功后自动重试同一个 tool call。输出必须只有这段 JSON，不要附加说明文字；`auth_id` 可用于关联授权会话。自动重试要求工具设计幂等，尤其当“是否已完成副作用”与“授权失败”边界不清时。

## Secret 治理

Fleet 默认使用 LangChain 托管模型，不需要 provider key。自定义模型或特定工具才从 workspace secrets 读取：

- `FLEET_` 前缀优先于通用 secret，例如 `FLEET_OPENAI_API_KEY` 会覆盖 `OPENAI_API_KEY`；
- Exa 需要 `EXA_API_KEY`；Tavily 需要 `TAVILY_API_KEY`；
- X 读取需要 `TWITTER_API_KEY` 与 `TWITTER_API_KEY_SECRET`，文档说明 posting/media upload 未开放；
- Remote MCP 的 headers 也在 workspace 配置中，并会用于 discovery 与 invoke。

Secret 名称必须与 provider 期望的环境变量一致。不要把 key 写进 instructions、memory、tool output 或 trace；使用最小权限 secret、分环境 workspace、轮换计划和访问审计。

## 预算与执行边界

Usage 页面需要 `fleet:read-admin-config`；设限需要 `fleet:write-admin-config`。可查看 7/14 天 spend、threads、runs，并按 Agent 或用户分解；默认每 Agent/用户周限额可被个别 override，星期一重置。

预算限制有三个容易误判的边界：

1. 变更需要数分钟传播；
2. 只在 run 开始时检查，已开始的 run 即使最终超限仍会完成；
3. 成本以 traces 计算，删除 trace 会影响报表与 enforcement。

因此预算不是实时熔断器。高成本工具和递归 Agent 仍需限制 recursion、单 run token/时间、并发、外部 API 配额，并对接近限额告警。

## 管理操作与不可逆风险

- model、connections、sharing、memory approval 和 channels 可在侧栏调整；
- Download ZIP 导出完整 Agent 配置；View code snippets 给出程序化调用入口；
- Pause Agent 实际是 pause all channels，UI chat/API 能力需另行确认，不能当全面停机开关；
- Delete Agent 不可恢复，会永久删除 Agent、关联 threads，并解除 attached channels；删除前先导出、停触发、盘点外部调用与保留要求。

默认 memory write 需要批准。Schedule/其他自动触发若会写 memory，应在确认风险后把 “Update memory and instructions” 改为 Auto，否则会一直等待；同时要限制 Agent 可写目录、对 memory diff 建立审计与恢复点。

## 审计与生产基线

Fleet actions 会进入结构化 LangSmith trace，含工具调用、决策与输出。结合 identity 和权限，目标是能回答：哪个 Agent、代表谁、使用哪类凭据、在什么输入下、调用什么工具、产生什么结果。

生产基线：

- 身份模型在设计评审时确定；固定身份使用专用账户，用户身份验证跨用户隔离。
- 默认 private + 只读 tools + Ask；通过评估后逐项开放共享、写权限和 Auto。
- 以 workspace gate 做禁用基线，ABAC deny 隔离高风险资源，RBAC 给常规角色，ABAC allow 做窄例外。
- 共享前检查 prompt、tools、sub-agents、channel 类型是否包含内部信息。
- Secret 按环境与用途拆分；Fleet-specific key 用于成本归因，不与其他 LangSmith 工作负载混用。
- 对授权失败、审批拒绝、重复事件、token 过期、预算传播延迟与删除操作做演练。
- Trace 保留与删除策略要和费用统计、调查取证、隐私要求一起设计。