跳到主要内容

部署架构

核对日期：2026-05-09。

1. 定义与边界​

Agent 部署架构是把 API、Agent orchestrator、模型访问、工具网关、队列 worker、状态库、会话库、缓存、观测和安全控制部署到生产环境的方式。它不等于“把 demo 包成 Docker 镜像”，而是要明确运行边界、扩缩容、故障隔离和数据路径。

2. 为什么重要​

Agent 生产系统同时具备 Web 服务、异步任务、外部 API 集成、数据处理和安全代理的特征。部署架构如果没有隔离，某个慢工具、长上下文请求或批量任务可能拖垮全部在线服务。

3. 核心机制​

推荐基准架构：

关键边界：

  • API 层负责鉴权、限流、输入校验和同步响应。
  • Orchestrator 层负责 Agent loop、状态机和模型/工具编排。
  • Tool Gateway 负责权限、幂等、审计、schema 校验和副作用控制。
  • Worker 层处理长任务、重试、批量任务。
  • Observability 层收集 trace、metric、log，不参与业务决策。

4. 架构模式​

模式适用场景风险
单服务部署内部低流量工具扩展和隔离差。
API + Worker大多数生产 Agent需要任务状态和队列治理。
模型代理层多模型、多租户、成本控制代理自身成为关键依赖。
工具网关层工具多、权限复杂schema 和权限维护成本。
Workflow 平台长周期和强恢复平台复杂度更高。

5. 工程实现​

Kubernetes 部署至少拆分：

components:
  agent-api:
    replicas: 3
    probes: [readiness, liveness, startup]
    autoscale_metric: http_requests
  agent-worker:
    replicas: 2
    autoscale_metric: queue_depth
  scheduler:
    replicas: 1
  migration-job:
    run_on_deploy: true

环境配置：

  • MODEL_PROVIDER、MODEL_POLICY、PROMPT_REGISTRY_URL。
  • STATE_DB_URL、SESSION_DB_URL、QUEUE_URL、CACHE_URL。
  • TRACE_EXPORTER_ENDPOINT。
  • 密钥通过 secret manager 注入，不提交到仓库。

6. 生产实践​

  • API 与 worker 独立扩缩容，批处理 worker 不和实时 worker 混用。
  • readiness probe 检查依赖是否可服务，liveness probe 不做昂贵外部调用。
  • 使用模型代理统一限流、熔断、预算和审计。
  • 对工具网关实施最小权限和网络隔离。
  • 灰度发布按 Agent/Prompt/租户/流量比例逐步扩大。
  • 所有组件输出结构化日志和 OpenTelemetry trace。

7. 常见反模式​

  • 本地 demo 直接部署为单进程，长任务阻塞请求。
  • worker 和 API 共用同一连接池、线程池，互相拖垮。
  • 生产配置散落在镜像内，无法按环境调整。
  • 没有 staging 或影子流量验证。
  • 观测和审计作为事后补丁，trace 缺少 run 关联。

8. 评测方法​

  • 负载测试：同步请求、异步任务、工具慢调用分别压测。
  • 故障演练：模型 API、缓存、队列、状态库、工具网关单点不可用。
  • 扩缩容测试：队列 backlog 增加时 worker 能扩容并受预算控制。
  • 发布演练：灰度、回滚、配置回退和数据库迁移回退。

9. 安全与治理​

  • 工具网关和模型代理处于服务端可信边界，客户端不能直接调用高风险工具。
  • 网络策略限制 worker 只能访问必要服务。
  • Secrets 通过密钥管理系统和短期凭证注入。
  • 对 MCP server、内部工具和第三方 SaaS 分别设置权限域。
  • 安全日志与业务 trace 关联，但敏感字段脱敏。

10. 权威资料​

11. 二次精修：生产部署拓扑​

Agent 服务通常不是单一 Web 服务，而是 API、worker、状态库、向量库、队列、观测管道和审批系统的组合。

组件扩缩容指标高可用要求
APIRPS、P95 latency、429多副本、无状态
Workerqueue lag、oldest age、CPU、cost burn可抢占但要 checkpoint
State DBQPS、锁冲突、复制延迟备份、迁移、恢复演练
Queuelag、DLQ、consumer error持久化和重放能力
Tool Serviceerror rate、timeout、rate limit熔断、隔离、降级
Observabilityingest lag、drop rate故障时本地缓冲

12. 发布与回滚​

deployment:
  artifact: "agent-service:1.8.2"
  config_versions:
    prompts: "prompt-bundle@2026-05-09.3"
    tools: "tool-registry@2.4.1"
    safety: "policy-bundle@1.6.0"
  rollout:
    stage_1: "internal_shadow"
    stage_2: "5_percent_canary"
    stage_3: "25_percent"
    stage_4: "100_percent"
  rollback:
    trigger:
      - "task_success_delta < -0.03"
      - "unsafe_action_rate > 0.001"
      - "p95_latency_ms > 2 * baseline"

部署时要能单独回滚代码、prompt、工具配置和模型路由。把所有变更打成一个不可拆的大包，会让事故定位和回滚都变慢。

13. 灾难恢复清单​

  • 状态库备份恢复演练：验证 RPO、RTO，而不是只检查备份存在。
  • 队列重放演练：验证重复任务不会重复副作用。
  • 模型供应商降级：配置备用模型、限流策略和用户可解释降级文案。
  • 观测后端故障：trace/log 缓冲，避免主链路被观测系统拖垮。
  • 权限系统故障：默认拒绝高危工具，低风险问答可降级。

14. 补充权威资料​