「JS全栈AI学习」十一、Multi-Agent 系统设计：可观测性与生产实践

1
// ❌ 非结构化：格式不统一，无法关联请求，难以分析
2
console.log("Flight Agent started querying flights for Beijing");
3

4
// ✅ 结构化：可按字段查询，可聚合分析，可追踪到具体请求
5
logger.info({
6
  timestamp: "2026-04-06T22:45:30.123Z",
7
  level: "INFO",
8
  traceId: "req_abc123",   // 关键：把这条日志和请求绑定
9
  agentId: "flight_agent",
10
  action: "query_flights_start",
11
  context: { destination: "北京", budget: 5000 },
12
});

1
class ObservableAgent {
2
  async execute(context: Context): Promise<Result> {
3
    const startTime = Date.now();
4

5
    // 1. Agent 开始
6
    logger.info({ traceId, agentId, action: 'agent_start' });
7

8
    try {
9
      // 2. 外部 API 调用前后（记录耗时）
10
      logger.debug({ traceId, agentId, action: 'api_call_start', api: 'flight_api' });
11
      const result = await this.callExternalAPI();
12
      logger.debug({ traceId, agentId, action: 'api_call_done', count: result.length });
13

14
      // 3. 决策点（最重要！记录为什么选这个）
15
      const selected = this.selectBestOption(result);
16
      logger.info({
17
        traceId, agentId, action: 'decision_made',
18
        selected: selected.id,
19
        reason: '价格最优，在预算范围内',
20
      });
21

22
      // 4. Agent 完成
23
      logger.info({ traceId, agentId, action: 'agent_complete', duration: Date.now() - startTime });
24
      return selected;
25

26
    } catch (error) {
27
      // 5. 错误（单独捕获，带完整上下文）
28
      logger.error({ traceId, agentId, action: 'agent_error', error, duration: Date.now() - startTime });
29
      throw error;
30
    }
31
  }
32
}

1
DEBUG → 详细调试信息（只在开发环境开启）
2
INFO  → 关键节点和决策点（生产环境的基准）
3
WARN  → 使用了降级策略、潜在问题
4
ERROR → 异常和错误

1
Trace：一个完整的请求链路（从用户发起到返回结果）
2
Span：链路中的一个环节（每个 Agent 的执行是一个 Span）
3

4
Trace
5
  └─ Span（Coordinator）
6
       ├─ Span（NLU Agent）
7
       ├─ Span（Planner Agent）
8
       └─ Span（并行查询）
9
            ├─ Span（Flight Agent）
10
            ├─ Span（Hotel Agent）
11
            └─ Span（Attraction Agent）

1
class Coordinator {
2
  async execute(userInput: string): Promise<Result> {
3
    const traceId = generateTraceId(); // 在入口生成，全程传递
4
    const rootSpan = tracer.startSpan({ traceId, agentId: 'coordinator' });
5

6
    // 调用其他 Agent 时，传递 traceId 和 parentSpanId
7
    const intent = await this.nluAgent.execute({
8
      userInput,
9
      traceId,
10
      parentSpanId: rootSpan.spanId, // NLU 的 Span 挂在 Coordinator 下面
11
    });
12

13
    tracer.endSpan(rootSpan);
14
    return result;
15
  }
16
}

1
Coordinator          ████████████████████████████████ 5000ms
2
  NLU Agent          ████ 400ms
3
  Planner Agent      ████ 400ms
4
  Flight Agent       ████████████████████████ 2300ms  ← 性能瓶颈
5
  Hotel Agent        █████████████████ 1700ms
6
  Attraction Agent   █████████ 900ms

1
class ExplainableHotelAgent {
2
  async selectHotel(hotels: Hotel[], context: Context): Promise<Hotel> {
3
    // 对每个酒店打分，记录各维度的权重和影响
4
    const scored = hotels.map(hotel => ({
5
      hotel,
6
      score: this.calculateScore(hotel, context),
7
      factors: [
8
        { name: '价格',  weight: 0.4, impact: this.priceFit(hotel.price, context.budget) },
9
        { name: '位置',  weight: 0.3, impact: this.locationScore(hotel.distanceToCenter) },
10
        { name: '评分',  weight: 0.2, impact: hotel.rating / 5 },
11
        { name: '设施',  weight: 0.1, impact: this.facilityScore(hotel.facilities) },
12
      ],
13
    }));
14

15
    const best = scored.sort((a, b) => b.score - a.score)[0];
16

17
    // 记录决策（这条记录是后续解释的数据来源）
18
    decisionLog.record({
19
      agentId: 'hotel_agent',
20
      action: 'select_hotel',
21
      options: hotels.length,
22
      selected: best.hotel.id,
23
      factors: best.factors,
24
      reason: this.buildExplanation(best),
25
    });
26

27
    return best.hotel;
28
  }
29
}

1
📊 推荐理由 · 三亚某酒店
2

3
1. 价格：500元/晚（权重 40%）
4
   预算 5000元 / 4晚 = 1250元/晚上限，500元在范围内，性价比高
5

6
2. 位置：距海滩 200m（权重 30%）
7
   符合您的偏好：海边度假
8

9
3. 评分：4.8 / 5.0（权重 20%）
10
   基于 1234 条用户评价
11

12
综合得分：8.7 / 10

1
延迟（Latency）  → P50 / P95 / P99，而不是平均值
2
成功率           → 成功请求 / 总请求
3
错误率           → 失败请求 / 总请求

1
const alertRules = [
2
  {
3
    name: '错误率过高',
4
    condition: (m: Metrics) => m.errorRate > 0.1,       // 错误率 > 10%
5
    severity: 'critical',
6
  },
7
  {
8
    name: '响应过慢',
9
    condition: (m: Metrics) => m.latency.p95 > 5000,    // P95 > 5s
10
    severity: 'warning',
11
  },
12
];

1
开发环境 → DEBUG（记录所有细节，方便调试）
2
测试环境 → INFO（记录关键节点）
3
生产环境 → WARN（只记录警告和错误）

1
private sanitize(entry: LogEntry): LogEntry {
2
  const sensitiveFields = ['password', 'token', 'creditCard'];
3
  sensitiveFields.forEach(field => {
4
    if (entry.context?.[field]) entry.context[field] = '***';
5
  });
6
  return entry;
7
}

1
shouldTrace(context: Context): boolean {
2
  if (Math.random() < 0.1)      return true;  // 随机采样 10%
3
  if (context.hasError)          return true;  // 错误请求 100% 采样
4
  if (context.duration > 5000)   return true;  // 慢请求 100% 采样
5
  return false;
6
}

1
日志查询    → Elasticsearch + Kibana
2
链路追踪    → Jaeger 或 Zipkin
3
指标监控    → Prometheus + Grafana