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 可用性和下游授权。

生产发布策略

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