生产级智能体平台设计：任务编排、工具管理与运行监控

摘要

当 Agent 只服务一个接口、只调用少量工具时，使用一个应用加几段提示词通常就可以开始。但随着业务发展，系统可能同时拥有多个 Agent、多个模型、几十个工具、异步任务、知识库、审批流程和不同业务团队。此时，继续把逻辑堆在单个服务中，会带来配置分散、权限混乱、任务不可恢复、运行状态不可见和成本无法控制等问题。

生产级智能体平台的目标，不是简单地把模型调用封装成一个统一接口，而是为 Agent 提供一套可管理的基础设施：能够注册和版本化工具，编排长任务和多 Agent 流程，控制权限和审批，记录完整运行轨迹，统计质量、延迟和成本，并支持失败恢复、灰度发布和问题回放。

本文从平台边界开始，介绍生产级智能体平台的核心模块、任务模型、工作流编排、工具中心、模型路由、权限控制、记忆与知识库、运行时监控、评估体系和部署架构。随后以一个"企业智能客服平台"为例，设计任务创建、工具调用、人工转接、结果交付和监控告警的完整流程。

本文重点讨论工程设计原则和模块边界，不绑定某一个具体框架。实际项目可以使用 LangGraph、Temporal、Airflow、自研工作流引擎或消息队列组合实现，但平台必须先明确任务、状态、权限、工具和观测这些核心概念。

读完本文后，你应该能够：

• 判断什么时候需要从 Agent 应用演进为智能体平台；
• 设计平台的任务、工作流和运行实例模型；
• 管理模型、Prompt、工具和 Agent 的版本；
• 为长任务提供暂停、恢复、重试和人工介入能力；
• 设计工具注册、权限校验和审批流程；
• 建立统一运行监控、成本统计和质量评估体系；
• 设计适合多租户和多业务团队使用的平台架构；
• 规划从单体 Agent 服务到生产级平台的演进路线。

一、背景与问题

1. 一个 Agent 应用是如何变成平台问题的

最初的 Agent 应用可能只有一个接口：

用户问题
  -> 调用模型
  -> 调用一个工具
  -> 返回答案

随着需求增加，系统会逐渐拥有：

多个模型
  + 多个 Agent
  + 多个业务场景
  + 知识库
  + 工具中心
  + 长任务
  + 人工审批
  + 多租户
  + 运行监控
  + 成本统计
  + 质量评估

此时，团队会开始重复解决相同问题：

• 每个业务自己保存 API Key；
• 每个 Agent 自己实现重试；
• 每个工具自己定义权限；
• 每个服务自己记录调用日志；
• 每个项目自己统计 Token 成本；
• 每个团队自己维护 Prompt；
• 每个任务失败后只能重新开始。

这就是平台化需求的起点。

2. 生产环境中的长任务

许多 Agent 任务不是几秒内完成的短请求。例如：

• 分析一个月的业务数据；
• 读取数百份企业文档；
• 生成并审核一份技术报告；
• 运行多轮代码测试和修复；
• 批量处理客户工单；
• 先检索知识库，再提交人工审批；
• 调用多个外部系统完成订单操作。

任务可能持续数分钟甚至数小时。它需要具备：

• 持久化状态；
• 中间结果保存；
• 失败重试；
• 暂停和恢复；
• 人工介入；
• 超时和取消；
• 任务进度；
• 最终结果和审计记录。

如果平台只把 Agent 当作同步 HTTP 接口，就很难可靠支持这类任务。

3. 没有平台治理会出现什么问题

配置分散

不同服务中可能出现：

模型名称不同
Prompt 版本不同
超时时间不同
重试规则不同
安全策略不同

同一个业务场景在不同环境中表现不一致，出现问题时也难以定位。

工具权限失控

某个 Agent 为了方便，可能拿到数据库写权限、文件系统权限和外部通知权限。随着工具增加，很难知道哪个 Agent 具备哪些能力。

运行状态不可见

任务失败时，平台只能看到"请求失败"，不知道：

• 哪个 Agent 失败；
• 哪个工具超时；
• 哪次模型调用最贵；
• 是否发生重复执行；
• 是否已经产生外部副作用。

无法回放

模型、知识库和工具结果都可能变化。如果没有保存执行轨迹，问题发生后无法复现当时的决策链。

4. 平台不等于把所有东西都集中

平台化不是把所有业务代码搬进一个超级服务。平台应该提供通用能力，业务团队仍然负责自己的：

• 业务规则；
• 数据权限；
• 领域流程；
• Agent 目标；
• 业务验收标准。

可以把边界理解为：

平台负责：
  模型、任务、工具、权限、编排、运行、评估、审计

业务负责：
  业务知识、业务规则、业务数据、业务结果

如果平台开始直接理解所有业务细节，就会变成另一个巨型单体。

5. 是否真的需要建设平台

不是所有 Agent 项目都需要独立平台。

适合平台化的信号：

信号	说明
多个团队重复接入模型	需要统一模型客户端和成本治理
工具数量快速增加	需要统一工具注册和权限
任务需要长时间运行	需要状态持久化和恢复
多个 Agent 共享能力	需要统一编排和运行管理
业务对审计有要求	需要完整执行链路
成本难以控制	需要预算、计量和限流
质量需要持续评估	需要统一测试和评估平台

如果只有一个小型聊天接口，直接建设完整平台通常会增加不必要的复杂度。

二、核心概念

1. Agent 平台的核心对象

一个生产级平台至少需要定义以下对象：

对象	含义
Tenant	租户或业务空间
Agent	面向某类任务的智能体定义
Model	可调用的模型及其配置
Prompt	可版本化的提示词模板
Tool	Agent 可以调用的能力
Workflow	多步骤任务流程定义
Task	用户发起的一次业务任务
Run	Task 的一次具体执行
Approval	人工审批记录
Trace	执行轨迹
Evaluation	质量评估结果

它们之间的关系可以表示为：

Tenant
  -> Agent
      -> Workflow
          -> Task
              -> Run
                  -> Step
                      -> Model / Tool / Human

2. Agent 定义与 Agent 实例

Agent 定义描述"这个 Agent 是什么"：

{
  "agent_id": "customer-support",
  "name": "企业客服助手",
  "version": "v3",
  "model": "support-model",
  "prompt_version": "support-prompt-v12",
  "allowed_tools": [
    "search_faq",
    "read_order_summary",
    "create_ticket"
  ],
  "risk_level": "medium"
}

Agent 实例描述"这次运行中的 Agent"：

{
  "run_id": "run_1001",
  "agent_id": "customer-support",
  "task_id": "task_2001",
  "status": "running",
  "started_at": "2026-09-18T10:00:00+08:00"
}

定义可以版本化、灰度和回滚，实例则记录真实运行状态。

3. Workflow 与 Task

Workflow 是一套可复用的流程定义：

接收问题
  -> 判断意图
  -> 查询知识库
  -> 判断是否需要订单信息
      -> 需要：查询订单
      -> 不需要：跳过
  -> 生成回答
  -> 安全审核
  -> 返回或转人工

Task 是用户实际发起的一次任务：

{
  "task_id": "task_2001",
  "workflow_id": "support-workflow",
  "input": "我的订单为什么还没有发货？",
  "created_by": "user_123",
  "status": "running"
}

一个 Workflow 可以执行很多 Task。任务状态必须持久化，不能只存在内存中。

4. Run 与 Step

同一个 Task 可能因为失败而重试多次，每次执行可以记录为一个 Run：

Task task_2001
  -> Run run_1 失败
  -> Run run_2 重试
  -> Run run_3 人工介入后完成

Run 内部包含多个 Step：

Step 1: classify_intent
Step 2: search_faq
Step 3: read_order_summary
Step 4: generate_answer
Step 5: safety_review

Step 是重试、审计和进度展示的基本单位。

5. 工具注册中心

工具注册中心保存工具的元信息：

{
  "tool_id": "read_order_summary",
  "version": "v2",
  "description": "读取当前用户订单摘要",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "integer"
      }
    },
    "required": ["order_id"]
  },
  "required_permissions": [
    "order:read"
  ],
  "risk_level": "L2",
  "timeout_seconds": 3,
  "idempotent": true,
  "enabled": true
}

注册中心的价值是让工具具备统一的：

• 发现；
• 版本；
• 权限；
• 风险；
• 输入校验；
• 超时；
• 审计；
• 灰度；
• 禁用和回滚。

6. 模型中心

模型中心管理：

• 模型名称；
• 供应商；
• API 地址；
• 认证引用；
• 上下文窗口；
• 输入输出价格；
• 能力标签；
• 速率限制；
• 健康状态；
• 可用租户和场景。

例如：

{
  "model_id": "support-model",
  "provider": "provider-a",
  "model_name": "general-model",
  "capabilities": [
    "chat",
    "json_output",
    "streaming"
  ],
  "context_window": 128000,
  "max_output_tokens": 4096,
  "status": "active"
}

业务 Agent 不应该自己保存供应商 API Key，而应该引用模型中心中的受控配置。

7. 运行状态

任务状态可以使用有限状态机表示：

created
  -> queued
  -> running
  -> waiting_approval
  -> paused
  -> retrying
  -> completed
  -> failed
  -> cancelled

状态迁移必须由代码控制，不能让模型直接写入 completed 或 approved。

8. 平台控制平面与运行平面

生产级平台可以分为两个部分。

控制平面负责：

• Agent 配置；
• Workflow 配置；
• 工具注册；
• 模型管理；
• 权限策略；
• 版本发布；
• 评估配置；
• 租户管理。

运行平面负责：

• 接收任务；
• 执行工作流；
• 调用模型和工具；
• 保存状态；
• 处理重试；
• 发送事件；
• 记录 Trace。

两者关系：

控制平面
  -> 发布 Agent、工具和工作流版本

运行平面
  -> 根据已发布版本执行任务

这样配置变更不会直接影响正在运行的任务。

三、工作原理

1. 平台整体架构

一个典型的生产级智能体平台可以设计为：

                    控制平面
  +------------------------------------------------+
  | Agent 管理 | Workflow 管理 | 工具中心 | 模型中心 |
  | Prompt 管理 | 权限策略 | 评估集 | 发布与灰度     |
  +------------------------------------------------+
                         |
                         v
                    运行平面
  +------------------------------------------------+
  | API Gateway | Task Service | Orchestrator       |
  | Worker Pool | Tool Gateway | Approval Service   |
  | Memory | Knowledge | Trace Collector           |
  +------------------------------------------------+
                         |
                         v
  +------------------------------------------------+
  | Model Providers | Business APIs | DB | MQ       |
  | Search | Vector DB | External Systems            |
  +------------------------------------------------+

平台不一定需要一开始拆成这么多微服务。逻辑边界可以先在模块化单体中建立，随着流量和团队规模增长再拆分部署单元。

2. 任务创建流程

用户发起任务后：

1. API Gateway 验证用户身份
2. Task Service 创建任务
3. 绑定 Agent 和 Workflow 版本
4. 检查用户和租户配额
5. 创建 Run
6. 把任务放入队列
7. 返回 task_id

返回结果通常不是最终答案：

{
  "task_id": "task_2001",
  "run_id": "run_3001",
  "status": "queued"
}

客户端可以通过轮询、SSE、WebSocket 或回调获取进度。

3. 任务编排

编排器负责决定：

• 当前执行到哪个步骤；
• 下一步是什么；
• 是否可以并行；
• 是否需要重试；
• 是否需要人工审批；
• 是否可以结束；
• 失败后从哪里恢复。

一个有状态的编排流程：

读取任务状态
  -> 选择当前 Step
  -> 加载 Agent 版本
  -> 调用模型或工具
  -> 保存 Step 结果
  -> 更新任务状态
  -> 计算下一步
  -> 提交下一条执行消息

每一步执行完成后都应持久化状态。不能只依赖 Worker 的内存。

4. 队列与 Worker

长任务应该通过队列与 Worker 解耦：

Task API
  -> Message Queue
      -> Worker 1
      -> Worker 2
      -> Worker 3

队列可以提供：

• 削峰；
• 重试；
• 并发控制；
• 优先级；
• 延迟任务；
• 死信队列；
• 消费者扩展。

Worker 执行任务时，需要防止同一个 Run 被多个 Worker 同时处理。可以使用：

• 分布式锁；
• 任务租约；
• 数据库行锁；
• 幂等状态；
• 消息去重。

5. 状态持久化

任务状态可以保存到关系数据库：

CREATE TABLE agent_tasks (
    task_id VARCHAR(64) PRIMARY KEY,
    tenant_id VARCHAR(64) NOT NULL,
    workflow_id VARCHAR(128) NOT NULL,
    workflow_version VARCHAR(32) NOT NULL,
    status VARCHAR(32) NOT NULL,
    input_json JSON NOT NULL,
    output_json JSON,
    current_step VARCHAR(128),
    retry_count INT NOT NULL DEFAULT 0,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL
);

步骤表：

CREATE TABLE agent_task_steps (
    step_id VARCHAR(64) PRIMARY KEY,
    task_id VARCHAR(64) NOT NULL,
    step_name VARCHAR(128) NOT NULL,
    step_type VARCHAR(32) NOT NULL,
    status VARCHAR(32) NOT NULL,
    input_json JSON,
    output_json JSON,
    error_code VARCHAR(128),
    started_at TIMESTAMP,
    ended_at TIMESTAMP,
    attempt INT NOT NULL DEFAULT 1
);

完整模型输出和大文件可以放对象存储，数据库保存引用和摘要。

6. 工具调用网关

所有工具调用统一经过 Tool Gateway：

Agent Worker
  -> Tool Gateway
      -> 身份校验
      -> 租户校验
      -> Agent 权限
      -> 工具白名单
      -> 参数 Schema
      -> 资源范围
      -> 风险和审批
      -> 超时和预算
      -> 业务工具
      -> 输出脱敏
      -> 审计记录

网关不能只依赖模型发来的参数。当前用户、租户、Agent 身份和审批状态必须来自可信上下文。

7. 人工审批

高风险步骤进入等待状态：

Agent 生成操作计划
  -> 创建 Approval
  -> Task 状态变为 waiting_approval
  -> 通知审批人
  -> 用户批准或拒绝
  -> 继续或终止任务

审批对象应绑定：

• task_id；
• run_id；
• step_id；
• action；
• resource_id；
• 参数摘要；
• 发起人；
• 审批人；
• 有效期；
• 使用状态。

不能把一个通用的 approved=true 作为所有任务的审批凭证。

8. 记忆与知识库

平台可以提供统一的记忆和知识库能力，但要区分：

会话记忆：
  近期对话和上下文

用户记忆：
  用户偏好和长期事实

任务状态：
  当前任务和中间结果

知识库：
  企业文档和检索资料

这些数据的生命周期、权限和一致性要求不同，不能全部放入同一个向量库或 Redis。

知识库服务通常包括：

• 文件上传；
• 解析；
• 切片；
• 向量化；
• 索引；
• 召回；
• 重排序；
• 引用来源；
• 权限过滤。

9. 运行监控

平台监控需要同时观察系统、任务和模型三个层面。

系统层：

• CPU；
• 内存；
• 队列长度；
• Worker 数量；
• 数据库连接；
• Redis 状态。

任务层：

• 成功率；
• 失败率；
• 平均任务时长；
• 当前运行任务数；
• 重试次数；
• 人工介入率；
• 取消率。

模型层：

• Token；
• 费用；
• 首 Token 延迟；
• 总延迟；
• 429 比例；
• 5xx 比例；
• 输出解析失败率；
• 模型拒答率。

10. Trace 和事件

平台应该把任务运行记录为事件：

{
  "event_id": "evt_1001",
  "task_id": "task_2001",
  "run_id": "run_3001",
  "step_id": "step_4001",
  "event_type": "tool.completed",
  "agent_id": "customer-support",
  "tool_id": "read_order_summary",
  "status": "success",
  "latency_ms": 240,
  "created_at": "2026-09-18T10:00:05+08:00"
}

事件可以用于：

• 运行状态；
• 进度展示；
• 审计；
• 指标计算；
• 失败回放；
• 事件驱动的后续任务。

11. 版本发布和灰度

Agent 平台中至少要版本化：

Agent 版本
Workflow 版本
Prompt 版本
Model 配置版本
Tool 版本
Knowledge Base 版本
Evaluation Set 版本

一次 Run 应该固定使用一组版本：

{
  "agent_version": "support-agent:v3",
  "workflow_version": "support-flow:v5",
  "prompt_version": "support-prompt:v12",
  "tool_bundle_version": "support-tools:v4",
  "knowledge_version": "support-kb:2026-09-18"
}

否则同一个任务运行过程中配置变化，会导致结果无法解释。

12. 取消和恢复

用户取消任务时，平台需要：

• 更新任务状态；
• 发送取消信号；
• 停止可取消的模型请求；
• 阻止后续步骤；
• 记录取消原因；
• 对已经完成的外部操作做补偿或提示。

服务重启后，平台应该能够从最后一个可恢复步骤继续：

读取 Run 状态
  -> 找到最后一个成功 Step
  -> 检查下一步是否幂等
  -> 继续执行或进入人工确认

不能简单地从头执行，否则可能重复扣款、重复发送通知或重复创建资源。

四、实战示例

下面设计一个企业智能客服平台的核心流程。用户可以查询常见问题、查看订单，并在必要时创建人工工单。

1. 业务目标

目标流程：

用户输入问题
  -> 意图识别
  -> 查询企业知识库
  -> 判断是否需要订单信息
  -> 查询当前用户订单摘要
  -> 生成回答
  -> 检查敏感和越权内容
  -> 返回回答或创建工单

角色分工：

组件	职责
Support Agent	理解问题并生成回答
Knowledge Tool	检索企业 FAQ
Order Tool	查询当前用户订单
Ticket Tool	创建人工服务工单
Safety Reviewer	检查隐私和敏感内容
Supervisor	控制任务流程

2. 定义 Agent 配置

agent:
  id: customer-support
  version: v3
  model: support-model
  prompt: support-prompt-v12
  workflow: support-workflow-v5
  tools:
    - search_faq:v2
    - read_order_summary:v2
    - create_support_ticket:v1
  limits:
    max_steps: 12
    max_tool_calls: 8
    max_cost_cents: 10
    timeout_seconds: 120

配置发布后生成不可变版本。运行中的任务不应该被实时修改。

3. 定义任务请求

public record CreateTaskRequest(
        @NotBlank String agentId,
        @NotBlank String input,
        String conversationId
) {
}

public record CreateTaskResponse(
        String taskId,
        String runId,
        String status
) {
}

任务服务：

@Service
public class TaskService {

    private final AgentRegistry agentRegistry;
    private final TaskRepository taskRepository;
    private final RunRepository runRepository;
    private final TaskQueue taskQueue;

    public CreateTaskResponse create(
            String tenantId,
            String userId,
            CreateTaskRequest request
    ) {
        AgentDefinition agent = agentRegistry.resolve(
                tenantId,
                request.agentId()
        );

        Task task = Task.create(
                tenantId,
                userId,
                agent.workflowId(),
                agent.workflowVersion(),
                request.input()
        );
        taskRepository.save(task);

        Run run = Run.create(task.id(), agent.version());
        runRepository.save(run);
        taskQueue.enqueue(run.id());

        return new CreateTaskResponse(
                task.id(),
                run.id(),
                "queued"
        );
    }
}

创建任务时固定 Agent、Workflow 和 Prompt 版本，保证后续运行可追溯。

4. 设计编排器接口

public interface Orchestrator {

    void execute(String runId);

    void resume(String runId);

    void cancel(String runId);
}

执行器：

@Component
public class SupportOrchestrator implements Orchestrator {

    private final RunRepository runRepository;
    private final StepExecutor stepExecutor;
    private final WorkflowRegistry workflowRegistry;

    @Override
    public void execute(String runId) {
        Run run = runRepository.getRequired(runId);
        WorkflowDefinition workflow =
                workflowRegistry.get(run.workflowVersion());

        while (run.canContinue()) {
            WorkflowStep step = workflow.nextStep(run.state());
            if (step == null) {
                run.complete();
                runRepository.save(run);
                return;
            }

            StepResult result = stepExecutor.execute(run, step);
            run.apply(result);
            runRepository.save(run);

            if (result.requiresHumanApproval()) {
                return;
            }
        }
    }
}

实际系统中不建议在一个 Worker 内无限循环。长流程应在每个 Step 完成后重新投递任务，避免占用 Worker 太久。

5. 定义工作流步骤

workflow:
  id: support-workflow
  version: v5
  steps:
    - id: classify_intent
      type: model
      agent: support-agent
      next: search_faq

    - id: search_faq
      type: tool
      tool: search_faq
      next: decide_order_lookup

    - id: decide_order_lookup
      type: condition
      branches:
        order_related: read_order
        other: generate_answer

    - id: read_order
      type: tool
      tool: read_order_summary
      next: generate_answer

    - id: generate_answer
      type: model
      agent: support-agent
      next: safety_review

    - id: safety_review
      type: review
      next:
        passed: deliver
        failed: create_ticket

    - id: deliver
      type: output

    - id: create_ticket
      type: tool
      tool: create_support_ticket
      next: deliver

固定工作流可以让关键路径稳定，同时保留条件分支。

6. 工具注册与调用

工具注册：

public record ToolDefinition(
        String id,
        String version,
        String description,
        Set<String> permissions,
        RiskLevel riskLevel,
        Duration timeout,
        boolean idempotent
) {
}

统一调用：

public ToolResult execute(
        ExecutionContext context,
        String toolId,
        Map<String, Object> arguments
) {
    ToolDefinition definition = registry.get(toolId);

    permissionService.check(
            context.userId(),
            context.agentId(),
            definition
    );
    schemaValidator.validate(
            definition,
            arguments
    );
    budgetService.check(context, definition);
    approvalService.checkIfRequired(
            context,
            definition,
            arguments
    );

    ToolResult result = handlerRegistry
            .handler(toolId)
            .execute(context, arguments);

    auditService.record(
            context,
            definition,
            result
    );
    return resultSanitizer.sanitize(definition, result);
}

7. 人工转接流程

当 Agent 无法确认答案或用户明确要求人工服务时：

public ApprovalResult transferToHuman(
        ExecutionContext context,
        String reason,
        Map<String, Object> summary
) {
    Ticket ticket = ticketService.createPending(
            context.userId(),
            reason,
            summary
    );

    taskRepository.markWaitingHuman(
            context.taskId(),
            ticket.id()
    );

    notificationService.notifySupportTeam(ticket);

    return new ApprovalResult(
            "waiting_human",
            ticket.id()
    );
}

任务状态不应该停留在"模型失败"。应明确区分：

自动回答
等待人工
人工处理中
人工完成
已关闭

8. 进度查询接口

@RestController
@RequestMapping("/api/tasks")
public class TaskController {

    @GetMapping("/{taskId}")
    public TaskStatusResponse getStatus(
            @PathVariable String taskId,
            CurrentUser currentUser
    ) {
        Task task = taskQueryService.getForUser(
                taskId,
                currentUser.id()
        );

        return TaskStatusResponse.from(task);
    }
}

返回信息：

{
  "task_id": "task_2001",
  "status": "running",
  "current_step": "search_faq",
  "progress": 40,
  "message": "正在查询企业知识库",
  "updated_at": "2026-09-18T10:00:04+08:00"
}

不要把模型内部思考链原样返回给用户。进度信息应来自结构化 Step 状态。

9. Trace 记录

public record TraceEvent(
        String traceId,
        String taskId,
        String runId,
        String stepId,
        String eventType,
        String component,
        String status,
        long latencyMs,
        Map<String, Object> attributes
) {
}

事件类型可以包括：

task.created
run.started
step.started
model.requested
model.completed
tool.requested
tool.completed
approval.created
approval.completed
step.failed
run.completed
run.cancelled

10. 运行指标

针对客服 Agent，可以定义：

task_success_rate
auto_resolution_rate
human_handoff_rate
average_task_latency
p95_task_latency
average_model_cost
tool_error_rate
knowledge_retrieval_hit_rate
safety_block_rate
user_negative_feedback_rate

其中 auto_resolution_rate 比单纯的模型回答成功率更接近业务价值：

自动解决任务数 / 总任务数

但这个指标仍需要结合用户是否重复提问、是否重新转人工等行为判断。

11. 故障恢复

假设查询订单工具调用超时：

Step read_order
  -> 第一次超时
  -> 重试一次
  -> 仍超时
  -> 查询服务状态
  -> 返回可解释错误
  -> 转人工或稍后重试

如果工具可能已经产生外部副作用，必须先查询操作状态，不能盲目重试。

任务恢复代码：

public void resume(String runId) {
    Run run = runRepository.getRequired(runId);

    if (run.status() == RunStatus.COMPLETED
            || run.status() == RunStatus.CANCELLED) {
        return;
    }

    if (run.hasPendingApproval()) {
        return;
    }

    queue.enqueue(runId);
}

12. 评估与发布门禁

Agent 版本发布前运行评估集：

{
  "agent_version": "customer-support:v3",
  "evaluation_set": "support-eval:v8",
  "task_success_rate": 0.93,
  "safety_pass_rate": 1.0,
  "average_cost": 0.018,
  "p95_latency_ms": 7800,
  "tool_selection_accuracy": 0.96
}

发布门禁：

安全通过率必须为 100%
任务成功率不能低于上一版本 2 个百分点
工具选择准确率 >= 95%
平均成本增长不超过 20%
P95 延迟不超过预算

如果不满足门禁，版本进入人工审核或不允许发布。

五、常见问题与实践建议

1. 一开始就拆成很多微服务

平台建设初期，建议优先采用模块化单体或少量服务：

平台 API
  + 任务编排模块
  + 工具网关模块
  + 模型客户端模块
  + 运行记录模块
  + 评估模块

等到出现独立扩展、故障隔离或团队边界需求后，再拆成服务。

过早拆分会增加：

• 网络调用；
• 服务部署；
• 分布式事务；
• 本地调试；
• 版本兼容；
• 故障定位。

2. 把 Workflow 做成完全自由的模型决策

生产流程不建议完全依赖模型决定所有下一步。

更稳妥的方式是：

关键路径由代码定义
  + 可选步骤由模型判断
  + 高风险动作由规则拦截
  + 不确定情况进入人工

模型可以帮助选择路径，但不能绕过任务状态、权限和审批状态。

3. 允许 Agent 动态注册高权限工具

动态工具注册有灵活性，但高风险工具不能由模型或普通 Agent 自己注册。

工具注册应该经过：

• 代码审查；
• 权限审批；
• Schema 校验；
• 安全扫描；
• 版本发布；
• 回滚机制。

动态发现可以存在，但动态授权必须受控。

4. 使用共享管理员账号调用所有工具

不应该让所有 Worker 使用同一个管理员身份访问业务系统。

应根据：

• 租户；
• 用户；
• Agent；
• 任务；
• 工具；
• 资源；

生成最小权限上下文，并记录完整调用链。

5. 只记录最终结果

没有 Step、Tool 和 Model 记录，平台无法定位：

• 哪个工具慢；
• 哪个模型贵；
• 哪个 Prompt 版本导致回归；
• 哪次审批被绕过；
• 哪个 Agent 重复执行。

至少应该保留结构化运行轨迹。

6. 所有数据都放在一个数据库

不同数据适合不同存储：

数据	推荐存储
任务和状态	关系数据库
事件和审计	关系数据库或事件存储
大模型原始输出	对象存储
短期任务缓存	Redis
向量检索数据	向量数据库
指标和日志	时序或日志系统

统一入口不等于统一存储。

7. 把所有模型输出都保存永久

模型输出可能包含用户隐私、企业机密和敏感业务数据。需要设计：

• 保留期限；
• 脱敏策略；
• 访问权限；
• 加密；
• 删除机制；
• 审计。

调试需要数据，但不能无限保存全部原文。

8. 忽略租户隔离

多租户平台中，以下数据必须进行租户隔离：

• Agent；
• Workflow；
• Prompt；
• 工具授权；
• 知识库；
• 任务；
• Trace；
• 成本；
• 评估集。

租户 ID 不应只由客户端传入，服务端需要从认证上下文获得并在每层校验。

9. 缺少配额和预算

没有预算控制时，异常循环可能造成：

• 模型调用数量暴增；
• 工具请求洪泛；
• 费用超支；
• 队列积压；
• 供应商限流。

至少应设置：

每租户并发任务数
每 Agent 每小时调用量
每任务最大步骤数
每任务最大模型成本
每工具最大调用次数
每分钟请求数

10. 只看技术指标，不看业务结果

平台不能只关注：

• QPS；
• CPU；
• 模型延迟；
• Token。

还要关注：

• 自动解决率；
• 人工转接率；
• 任务完成率；
• 用户重复提问率；
• 业务转化率；
• 错误操作率；
• 客诉率。

技术指标说明系统运行情况，业务指标说明系统是否创造价值。

11. 发布配置直接覆盖线上任务

新版本 Agent、Prompt 或工具配置发布后，正在执行的任务最好继续使用旧版本，避免中途变更导致状态不一致。

建议：

新任务 -> 新版本
运行中任务 -> 继续使用绑定版本
失败重试 -> 默认使用原版本，除非明确迁移

12. 没有明确的降级路径

模型不可用时，平台需要提前定义：

• 是否切备用模型；
• 是否使用缓存；
• 是否转人工；
• 是否暂停任务；
• 是否返回部分结果；
• 是否允许稍后继续。

降级不是出现故障后临时写一段 if，而应该是工作流的一部分。

六、进阶思考

1. 平台的多租户设计

多租户平台通常需要在三个层面隔离：

数据隔离

所有核心表包含 tenant_id，查询默认带租户条件：

SELECT *
FROM agent_tasks
WHERE tenant_id = :tenant_id
  AND task_id = :task_id;

资源隔离

不同租户拥有不同的：

• 模型配额；
• 并发限制；
• 工具范围；
• 知识库；
• 存储空间；
• 费用预算。

运行隔离

高价值租户可以使用独立 Worker 池、独立队列或独立模型凭证，降低相互影响。

2. 配额和成本中心

平台应该把成本计量到可操作的维度：

租户
  -> 用户
      -> Agent
          -> Task
              -> Run
                  -> Model Call

成本记录：

{
  "tenant_id": "tenant_a",
  "agent_id": "support",
  "task_id": "task_2001",
  "model": "support-model",
  "input_tokens": 3200,
  "output_tokens": 680,
  "estimated_cost": 0.018,
  "created_at": "2026-09-18T10:00:00+08:00"
}

有了成本中心，平台才能实施：

• 配额；
• 超预算告警；
• 成本归属；
• 高成本任务优化；
• 供应商价格比较；
• 模型路由。

3. 调度优先级

不同任务可能有不同优先级：

P0：线上故障处理
P1：实时客服请求
P2：普通业务任务
P3：离线批处理

队列调度可以考虑：

• 优先级；
• 租户配额；
• 任务截止时间；
• 资源类型；
• 模型容量；
• 重试次数。

高优先级不能无限抢占低优先级，否则低优先级任务会长期饥饿。可以使用配额和公平调度。

4. 任务编排引擎选择

不同场景可以选择不同技术：

方案	适合场景
自研状态机	流程有限、团队希望完全控制
LangGraph	Agent 状态图和条件流程
Temporal	长任务、可靠恢复、定时和补偿
消息队列	异步解耦、任务分发
工作流平台	可视化流程和跨团队编排

选择时应关注：

• 状态持久化；
• 任务恢复；
• 定时和延迟；
• 重试；
• 幂等；
• 人工暂停；
• 可观测性；
• 运维复杂度。

不要只因为某个框架适合 Demo，就直接用于所有生产流程。

5. Agent 沙箱

如果平台允许 Agent 执行代码、访问文件或操作命令，需要独立沙箱：

临时运行环境
  -> 非 root
  -> 只读基础文件系统
  -> 限定工作目录
  -> 默认无网络
  -> CPU 和内存限制
  -> 执行时限
  -> 进程限制
  -> 自动销毁

普通容器不应被简单视为绝对安全边界。高风险代码执行需要更严格的隔离技术、网络策略和主机安全配置。

6. Prompt 管理平台

Prompt 应该像代码一样管理：

• 版本；
• 作者；
• 变更说明；
• 测试集；
• 发布状态；
• 灰度比例；
• 回滚版本。

Prompt 发布流程：

编辑草稿
  -> 离线评估
  -> 安全检查
  -> 小流量灰度
  -> 线上指标观察
  -> 全量发布或回滚

不要让生产 Prompt 只能通过修改代码和重新部署才能更新，也不要允许未经评估的用户输入直接成为系统 Prompt。

7. 工具生命周期

工具也应该有生命周期：

draft
  -> testing
  -> active
  -> deprecated
  -> disabled

工具升级要考虑：

• 输入 Schema 兼容；
• 输出字段变化；
• 权限变化；
• 资源影响；
• 幂等行为；
• 旧任务是否继续使用旧版本。

高风险工具下线时，应先禁止新任务使用，再等待旧任务完成或迁移。

8. 评估平台

平台评估不应只测试最终文本，还要测试：

• 工具选择；
• 参数正确性；
• 任务完成率；
• 安全拒绝；
• 多 Agent 路由；
• 任务恢复；
• 成本；
• 延迟；
• 人工接管。

评估集可以来自：

• 人工编写；
• 线上脱敏失败样本；
• 用户反馈；
• 安全红队样本；
• 业务规则；
• 历史任务回放。

9. 运行时策略

平台可以根据运行状态动态调整：

模型连续超时
  -> 切换备用模型

工具错误率升高
  -> 暂停工具

任务预算即将耗尽
  -> 降低上下文
  -> 终止非关键步骤

高风险请求激增
  -> 提高人工审批级别

运行时策略应该有明确边界和审计，不要让系统在不透明的情况下自动改变关键行为。

10. 安全运营

Agent 平台需要持续监控：

• 提示词注入；
• 越权工具调用；
• 敏感数据输出；
• 异常访问模式；
• 任务成本突增；
• 大量失败重试；
• 跨租户访问尝试；
• 审批绕过；
• 工具参数异常。

发现风险后可以：

阻断调用
  -> 暂停 Agent
  -> 撤销令牌
  -> 通知安全团队
  -> 保留审计证据
  -> 人工复核

11. 高可用设计

平台的关键组件需要考虑高可用：

组件	关注点
API Gateway	多副本、限流、健康检查
Task Service	无状态、幂等、数据库高可用
Queue	持久化、重试、死信
Worker	弹性扩缩容、租约、优雅关闭
Orchestrator	状态恢复、重复执行保护
Tool Gateway	超时、熔断、权限服务可用性
Trace	异步写入、降级、采样
Model Provider	多供应商或备用模型

任何情况下都不应该因为监控系统短暂不可用，就阻塞核心业务任务；但审计要求高的操作需要在审计无法写入时保守处理。

12. 平台演进路线

推荐按阶段演进：

阶段一：统一模型客户端
  -> 阶段二：工具网关和权限
  -> 阶段三：任务状态和异步队列
  -> 阶段四：Workflow 编排
  -> 阶段五：版本、评估和灰度
  -> 阶段六：多租户、成本中心和安全运营

每个阶段都应该有明确收益和验收指标。

结论

生产级智能体平台的核心，不是让模型变得更聪明，而是让 Agent 具备可管理、可恢复、可审计、可评估和可运营的工程基础。

一个完整的平台通常需要覆盖：

Agent 管理
模型管理
Prompt 管理
工具注册
工作流编排
任务和运行状态
队列与 Worker
权限和审批
知识库与记忆
Trace 和日志
成本和配额
评估和回归
灰度和发布
安全运营

落地时不建议一开始就建设庞大的微服务平台。更合理的路线是先统一模型调用，再建立工具网关和任务状态，随后增加工作流、评估、成本、版本和多租户能力。平台逻辑可以先以模块化单体实现，等流量、团队和可靠性要求明确后再拆分部署。

最重要的设计原则包括：

• 任务状态必须持久化；
• 每次运行必须绑定明确版本；
• 工具调用必须经过统一网关；
• 高风险操作必须审批；
• Agent 权限遵循最小权限；
• 模型输出必须经过业务校验；
• 失败任务必须支持恢复或明确终止；
• 运行轨迹必须能够查询和回放；
• 成本、质量、延迟和安全需要同时监控。

至此，智能体 Agent 开发实战系列完成了从基本概念、工具调用、任务拆解、记忆、工作流、多 Agent、权限、评估到生产平台设计的完整路径。后续可以基于一个具体业务继续实践，例如企业智能客服、代码助手、智能数据分析平台或企业知识库 Agent。