---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - llm-gateway
  - policy
topic: LangSmith Smith API LLM Gateway 策略与 Agent Builder 集成开关
sources:
  - https://docs.langchain.com/langsmith/smith-api/gateway-policies/create-a-gateway-policy
  - https://docs.langchain.com/langsmith/smith-api/gateway-policies/delete-a-gateway-policy
  - https://docs.langchain.com/langsmith/smith-api/gateway-policies/get-a-gateway-policy
  - https://docs.langchain.com/langsmith/smith-api/gateway-policies/list-gateway-policies
  - https://docs.langchain.com/langsmith/smith-api/gateway-policies/search-gateway-policies-by-subject-value-set
  - https://docs.langchain.com/langsmith/smith-api/gateway-policies/update-a-gateway-policy
  - https://docs.langchain.com/langsmith/smith-api/integrations/get-agent-builder-integrations-settings
  - https://docs.langchain.com/langsmith/smith-api/integrations/update-agent-builder-integrations-settings
last_verified: 2026-08-11
---

# Smith API：LLM Gateway 策略与 Agent Builder 集成

Gateway Policy 是 Organization 级运行时控制：它在模型请求进入上游之前执行费用上限、速率限制、敏感信息 guard 或故障路由。Agent Builder Integration Settings 则是 Workspace 级“哪些集成默认可用”的配置。前者控制调用路径，后者控制产品功能可见/启用状态，两者都不能替代底层凭据与权限校验。

## 六类 Policy

| `policy_type` | config 核心字段 | 触发结果 |
|---|---|---|
| `spend_cap` | window=hourly/daily/weekly/monthly、limit_usd | 达上限返回 402 |
| `default_spend_cap` | 同上 | 按新出现的 subject 自动物化子 policy |
| `rate_limit` | version=1、非空 limits[] | 超限返回 429，并给 Retry-After 提示 |
| `default_rate_limit` | 同上 | 按 subject 自动物化子 policy |
| `guard` | detect.pii、detect.secrets、timeout | 命中内容在转发前原位脱敏 |
| `route_config` | priority_fallback、triggers、fallbacks | 上游失败时按优先级尝试 model configs |

Rate limit 的 metric 是 requests 或 tokens，window 是 minute 或 hour；同一 metric/window 组合不能重复，value 范围为 1 到 `10^15`。Guard 的 `timeout_seconds` 范围 0.1–30 秒、默认 2 秒，`timeout_action` 为 allow 或 block，默认 allow。默认值意味着 guard 超时时是 fail-open；高敏感业务若要 fail-closed，必须显式选择 block，并评估 guard 服务故障对可用性的影响。

Route config 要求：

- `strategy=priority_fallback`；
- `triggers.status_codes` 必须非空，且文档建议包括 502、504 以覆盖上游传输故障；
- fallbacks 中的 model configs 按顺序尝试，每组 1–5 个；
- `subject_matchers` 只能有一个 `workspace_id`；
- route config 不按 matcher upsert，名称在 Organization 内必须唯一，冲突返回 409。

## Subject、优先级与物化子策略

`subject_matchers` 是 `{key,value}` 数组，key 可为 organization_id、workspace_id、user_id、api_key_id、run_rule_id；多个 matcher 是 AND。Spend/rate/guard 类创建时，如果同 Organization 已有相同 matchers 的同族 policy，会原位更新并保留 ID，而不是创建重复记录。

默认 policy 使用 `{key, value: ""}` 作为模板。运行时遇到请求 metadata 中不同 subject 时，物化带 `parent_policy_id` 的子 policy。List 会同时返回管理员创建项和系统物化子项，因此资产盘点不能只按 name 计数。

显式 create/update 一个与子项相同 matcher 的 policy 会清除其 parent link，由该行自行管理。删除 default policy 会级联删除仍关联的子 policy；更新 default policy 会级联更新子项的 config、action、enabled 与 priority。模板是事实来源，不应直接逐个修改其仍挂接的子项。

`action` 当前固定为 block。`enabled=false` 只是不执行阻断，返回记录仍可能包含 `current_spend_usd` 或每条 rate limit 的 `current_usage`，便于在正式启用前做 shadow observation。priority 应显式规划，避免多条匹配 policy 的优先级靠偶然创建顺序决定。

## CRUD 与查询边界

`POST /api/v1/platform/gateway-policies` 对普通 policy 具有“按 matcher upsert”语义，创建与原位更新都返回 201；不能把 201 简化理解成“一定新增了资源”。PATCH 只应用出现的字段，`policy_type` 不可修改；config 必须与既有类型匹配，否则 400。修改 matcher 若与另一 policy 冲突返回 409。

Get 跨 Organization 时返回 404，而不是暴露资源存在。List 可按 policy_type 或 matcher key/value 筛选。大量 subject 值应使用 `POST .../search`，把 `subject_matcher_values[]` 放入 body，避免 URL 长度上限；空数组或省略时等价于只按 policy_type 的 list。

读取 policy 时：

- spend policy 的 `current_spend_usd` 表示当前 window 的累计值，disabled 时也可返回；
- rate policy 的 `current_usage[]` 与 config 中 limits 一一对应；
- 非对应类型或查询失败时这些运行时字段可为空；
- `is_system_generated` 与 `parent_policy_id` 用来区分物化项，不能仅凭命名判断。

删除成功为 204，之后 get 为 404。创建、更新、删除要求 OrganizationManage；读取要求 OrganizationRead，组织未启用 LLM Gateway 也会 403。

## Agent Builder Integration Settings

`GET /v1/agent-builder/integrations` 返回：

- `integrations_enabled_by_default`：默认策略；
- `integration_overrides[]`：按 `integration_key` 的启停覆盖；
- `integration_catalog[]`：已知集成的 id/key/display_name 与 `can_invoke`。

`PUT` 是整体替换 default policy 与 overrides，不是 PATCH。多管理员并发的安全写法是读取当前 payload、只改目标 key、带业务侧版本/互斥控制提交，再回读比对。缺省覆盖项通常回落到 default policy；调用方不应把“未出现在 overrides”硬编码为 disabled。

`can_invoke` 是服务端计算的能力结果，`is_enabled` 是配置意图。界面可据此禁用按钮，但真正执行仍必须在服务端校验 workspace 权限、OAuth/secret 可用性和下游授权。

## 生产发布策略

1. 先以 `enabled=false` 创建 spend/rate policy，观察 current usage，再启用阻断。
2. Spend cap 与 rate limit 同时存在时，客户端分别处理 402 和 429；429 尊重 Retry-After，402 不做自动重试。
3. Guard 先用脱敏测试集验证 PII/secrets 的误报漏报，再决定 timeout_action；日志中不可保留脱敏前内容。
4. Route fallback 只应覆盖明确的可恢复状态码；不要把认证、配额或业务 4xx 路由到另一模型以掩盖根因。
5. 变更 default policy 前枚举当前子项与预期影响量，保留旧 config；删除模板前确认级联范围。
6. Agent Builder 的 PUT 更新与 Gateway policy 更新分别属于 Workspace 和 Organization 控制面，审计中要记录两种作用域，不能混成一个开关。