ReAct（react_agent）从入门到严谨：并以 AIOps 离线 PoC 为例给出可落地方案

ReAct（react_agent）从入门到严谨：并以 AIOps 离线 PoC 为例给出可落地方案

关键词：ReAct Agent / react_agent、Reason-Act-Observe 循环、Tool Calling、可审计证据链、AIOps（ServiceNow / AppDynamics / Splunk / CMDB）、离线可跑 PoC、评测与回归

---

目录

• [1. react_agent 到底是什么](#1. react_agent 到底是什么)
• [2. 四种难度梯度：从直觉到严谨](#2. 四种难度梯度：从直觉到严谨)
  • [2.1 最简单：会用工具的 ChatGPT](#2.1 最简单：会用工具的 ChatGPT)
  • [2.2 进阶：Reason-Act-Observe 循环与结构化输出](#2.2 进阶：Reason-Act-Observe 循环与结构化输出)
  • [2.3 工程落地：一个可用 react_agent 需要哪些组件](#2.3 工程落地：一个可用 react_agent 需要哪些组件)
  • [2.4 最严谨：POMDP 视角与可验证约束](#2.4 最严谨：POMDP 视角与可验证约束)
• [3. AIOps 场景：离线可跑的最小 ReAct PoC 规格](#3. AIOps 场景：离线可跑的最小 ReAct PoC 规格)
  • [3.1 PoC 目标与验收指标](#3.1 PoC 目标与验收指标)
  • [3.2 仓库结构与离线数据](#3.2 仓库结构与离线数据)
  • [3.3 工具（Tools）与契约（Contracts）](#3.3 工具（Tools）与契约（Contracts）)
  • [3.4 最终输出 Schema（可审计、可解析）](#3.4 最终输出 Schema（可审计、可解析）)
  • [3.5 ReAct Orchestrator：循环、停止条件与错误策略](#3.5 ReAct Orchestrator：循环、停止条件与错误策略)
  • [3.6 Prompt 与防注入（Policy）](#3.6 Prompt 与防注入（Policy）)
  • [3.7 评测数据集与打分（Eval Harness）](#3.7 评测数据集与打分（Eval Harness）)
  • [3.8 从离线 PoC 到真实系统对接的替换点](#3.8 从离线 PoC 到真实系统对接的替换点)
• [4. 结语：如何把"会查资料"升级为"可回归的工程系统"](#4. 结语：如何把“会查资料”升级为“可回归的工程系统”)

---

1. react_agent 到底是什么

这里的 react_agent 通常指 ReAct Agent（Reason + Act：推理 + 行动交错的智能体范式），不是 React.js 前端框架。

核心思想 ：让 LLM 在生成答案的过程中，不是一次性"想完再答"，而是交替进行推理与工具调用：

• Reason：决定下一步需要什么信息、该调用什么工具
• Act：调用工具（检索、计算、API、数据库等）
• Observe：读取工具返回并更新决策
• 循环直到输出最终答案（Final）

---

2. 四种难度梯度：从直觉到严谨

2.1 最简单：会用工具的 ChatGPT

把它当成一句话：

ReAct（react_agent）= 会一边想、一边动手调用工具的 LLM。

• 传统聊天：模型只在"脑内"推理，最后给答案
• ReAct：模型会在中途做"动作"，例如查日志、查指标、查 CMDB、查变更，再基于结果回答

适用于需要外部事实 或多源证据的问题，比如 AIOps 告警归因、数据排障、合规问答等。

---

2.2 进阶：Reason-Act-Observe 循环与结构化输出

ReAct 典型循环（Reason → Act → Observe）如下：
enough evidence
User question or Alert
Reason decide next step
Act call tool with args
Observe read tool result
Final structured answer

建议工程上使用"结构化"决策与输出

不要依赖把 "Thought" 原样打印（难审计、难测试、可能泄露）；推荐用可解析协议：

• Tool call（工具调用）示例：

{"type":"tool_call","tool":"search_logs","args":{"service":"payments-api","query":"NullPointerException","time_from":"...","time_to":"...","limit":50}}

• Observation（工具返回）示例：

{"type":"observation","tool":"search_logs","result":{"total_hits":42,"events":[{"ts":"...","host":"...","message":"...","raw_id":"log_raw_7781"}]}}

• Final（最终输出）示例：

{"type":"final","category":"Deployment","confidence":0.78,"summary":"...","evidence":[...]}

---

2.3 工程落地：一个可用 react_agent 需要哪些组件

一个"能上生产语境"的 react_agent 通常需要补齐 5 类工程件：

1. 工具层（Tools）

   • 输入/输出 schema（强类型）
   • 超时、重试、幂等
   • 权限与审计

2. 编排层（Agent Loop / Orchestrator）

   • 停止条件（最大步数、证据阈值）
   • 错误策略（工具失败怎么办）
   • 成本与预算控制（token、调用次数、延迟）

3. 记忆层（Memory）

   • 短期：本轮观测（observations）
   • 长期：RAG/向量库/知识库
   • 任务：避免重复、记录尝试过的动作

4. 评测与回归（Eval Harness）

   • 成功率、调用准确率、证据质量、延迟、成本

5. 安全与合规（Safety / Compliance）

   • 防提示注入
   • 工具白名单
   • 证据到结论的一致性校验

常见失败模式（必须提前设计防护）

• 幻觉工具返回（编造 observation）
• 循环调用（重复查询同一关键词）
• 过度调用（能答却一直查）
• 证据与结论不一致
• 提示注入（检索到的内容诱导越权）

---

2.4 最严谨：POMDP 视角与可验证约束

从严格建模角度，ReAct Agent 可视为一个 部分可观测的序贯决策过程（POMDP）：

• 真实世界状态： s s s（外部系统真实信息：日志、指标、CMDB、工单等）
• 观测： o o o（工具返回的结果，通常不完整且有噪声）
• 动作： a a a（调用工具及参数，或输出最终答案）
• 历史： h = ( q , a 1 , o 1 , ... , a t , o t ) h = (q, a_1, o_1, \dots, a_t, o_t) h=(q,a1,o1,...,at,ot)
• 策略： π ( a ∣ h ) \pi(a \mid h) π(a∣h)（基于历史选择动作）

ReAct 的关键在于：每次获得观测 o t o_t ot 后，策略基于更新后的历史 h h h 再决策下一步，而非一次性规划后执行。

可验证约束（把 agent "系统化"）

为提升可靠性与可审计性，建议引入以下硬约束：

1. 工具调用约束（Safety Contracts）：仅允许白名单工具与合法参数
2. 证据一致性约束（Evidence-to-Claim）：结论必须被 evidence 支持
3. 终止与预算约束（Termination Guarantees） ：最大步数 T T T、最大调用数 N N N、超时降级
4. 结构化输出约束（Schema Compliance）：强制 JSON schema，失败即重试/降级

---

3. AIOps 场景：离线可跑的最小 ReAct PoC 规格

本节给出一个 本地离线可跑 的 PoC：先用本地文件模拟 Splunk/AppDynamics/ServiceNow/CMDB 的返回，确保端到端闭环跑通；后续仅替换工具实现即可对接真实系统。

3.1 PoC 目标与验收指标

PoC 目标

给定一个告警（服务、时间窗、症状），react_agent 能：

1. 选择并调用合适工具（查日志/查指标/查 CMDB/查变更/查历史工单）
2. 汇总证据（引用到具体日志片段、指标异常、变更记录）
3. 输出 RCA 初步结论 + 置信度 + 下一步建议
4. 输出严格结构化 JSON（可入库、可审计、可看板）

验收指标（可量化）

• 归因类别命中率（Category Accuracy）

  设数据集有 M M M 个 case，预测类别为 y ^ i \hat{y}i y^i，真实类别为 y i y_i yi：
  CategoryAcc = 1 M ∑ i = 1 M 1 ( y ^ i = y i ) \text{CategoryAcc} = \frac{1}{M}\sum{i=1}^{M} \mathbf{1}(\hat{y}_i = y_i) CategoryAcc=M1i=1∑M1(y^i=yi)

• 证据精确率（Evidence Precision）

  设第 i i i 个 case 预测的证据集合为 E ^ i \hat{E}_i E^i，其中真正支持结论（可在工具返回中追溯且与结论一致）的证据集合为 E ^ i + \hat{E}_i^{+} E^i+：
  EvidencePrecision = ∑ i ∣ E ^ i + ∣ ∑ i ∣ E ^ i ∣ + ϵ \text{EvidencePrecision} = \frac{\sum_i |\hat{E}_i^{+}|}{\sum_i |\hat{E}_i| + \epsilon} EvidencePrecision=∑i∣E^i∣+ϵ∑i∣E^i+∣

  其中 ϵ \epsilon ϵ 是避免分母为 0 的极小值。

• 证据覆盖率（Evidence Coverage）

  若期望证据类型集合为 T i T_i Ti（如 { log , metric , change } \{\text{log},\text{metric},\text{change}\} {log,metric,change}），预测证据类型集合为 T ^ i \hat{T}_i T^i：
  Coverage i = ∣ T i ∩ T ^ i ∣ ∣ T i ∣ , EvidenceCoverage = 1 M ∑ i = 1 M Coverage i \text{Coverage}_i = \frac{|T_i \cap \hat{T}i|}{|T_i|}, \quad \text{EvidenceCoverage} = \frac{1}{M}\sum{i=1}^M \text{Coverage}_i Coveragei=∣Ti∣∣Ti∩T^i∣,EvidenceCoverage=M1i=1∑MCoveragei

• 结构合规率（Schema Compliance）
  SchemaCompliance = # ( schema_valid ) M \text{SchemaCompliance}=\frac{\#(\text{schema\_valid})}{M} SchemaCompliance=M#(schema_valid)

• Latency（端到端延迟）：并统计工具调用次数分布，防止"过度调用"。

---

3.2 仓库结构与离线数据

建议仓库结构：

aiops-react-agent/
  README.md
  pyproject.toml
  src/
    agent/
      orchestrator.py
      policy.py
      schemas.py
      prompts.py
    tools/
      splunk_stub.py
      appd_stub.py
      snow_stub.py
      cmdb_stub.py
      incidents_stub.py
    eval/
      dataset.jsonl
      scorer.py
  data/
    logs.jsonl
    metrics.csv
    changes.jsonl
    cmdb.json
    incidents.jsonl
  tests/
    test_schemas.py
    test_orchestrator_smoke.py

离线 PoC 核心原则：先用 data/ 文件 stub 掉所有外部系统，保证 macOS 不联网也能稳定复现、稳定评测。

---

3.3 工具（Tools）与契约（Contracts）

至少实现 5 个工具以覆盖 AIOps 的主要证据面：

Tool A：search_logs（模拟 Splunk）

• 输入（args）：

  • service: str
  • time_from: str（ISO8601）
  • time_to: str（ISO8601）
  • query: str
  • limit: int

• 输出（result）：

  • events: list[{"ts","host","level","message","trace_id?","raw_id"}]
  • total_hits: int

Tool B：query_metrics（模拟 AppDynamics）

• 输入：

  • service: str
  • metric_names: list[str]（如 latency_p95, error_rate, throughput）
  • time_from, time_to: str
  • granularity_sec: int

• 输出：

  • series: dict[metric_name -> list[{ts,value}]]
  • anomalies: list[{metric_name, ts, severity, description}]

Tool C：get_cmdb_context（模拟 CMDB / 服务注册）

• 输入：

  • service: str

• 输出：

  • service
  • cis（相关 CI 列表）
  • owner（team/oncall）
  • dependencies（db、mq、3rd api）

Tool D：get_changes（模拟 ServiceNow 变更）

• 输入：

  • service: str
  • time_from, time_to: str

• 输出：

  • changes: list[{change_id,type,start,end,risk,summary,implementer}]

Tool E：search_similar_incidents（模拟历史工单 / 相似事件）

• 输入：

  • service: str
  • symptoms: str
  • limit: int

• 输出：

  • incidents: list[{incident_id,category,resolution_summary,key_evidence_ids}]
  • top_patterns（可选）

---

3.4 最终输出 Schema（可审计、可解析）

建议最终输出固定 JSON（可直接入库/看板）：

{
  "case_id": "string",
  "service": "string",
  "time_window": {"from": "ISO", "to": "ISO"},
  "category": "Deployment|Config|Dependency|Infra|Capacity|CodeDefect|Unknown",
  "summary": "string",
  "confidence": 0.0,
  "primary_hypothesis": "string",
  "evidence": [
    {
      "type": "log|metric|change|cmdb|incident",
      "source_id": "string",
      "excerpt": "string",
      "why_it_matters": "string"
    }
  ],
  "impact_assessment": {
    "user_impact": "string",
    "blast_radius": "string"
  },
  "recommended_actions": [
    {"action": "string", "owner": "string", "priority": "P0|P1|P2"}
  ],
  "tool_trace": [
    {"tool": "string", "args": {}, "result_digest": "string"}
  ],
  "unknowns": ["string"]
}

关键工程要求：

• evidence.source_id 必须可追溯到工具返回中的 raw_id / change_id / incident_id
• tool_trace 记录每次调用摘要（用于审计、回放、成本分析）

---

3.5 ReAct Orchestrator：循环、停止条件与错误策略

Orchestrator 的状态（State）

• input_alert：service、time window、symptoms
• observations：工具返回累积（结构化存储）
• budget：最大步数、最大调用数、最大时延
• policy：白名单、参数限制、输出 schema 校验

停止条件（Termination）

满足任一条件即可输出 Final：

1. 收集到至少两类互相支持的证据（例如 change + metric；或 log + dependency）
2. 达到最大步数 T T T（如 8）或最大调用数 N N N（如 6）
3. 工具连续失败超过阈值（如 2），降级输出 Unknown 并列出缺失信息

错误策略（实用）

• 工具超时：重试 1 次 → 收窄查询（更小时间窗/更少关键词/更小 limit）→ 失败则记录 unknowns
• 返回过多：自动收紧（limit、关键词、trace_id）
• 证据冲突：输出多个假设并降低 confidence

ReAct 编排流程（AIOps 版本）

anomaly
no anomaly
Alert service time_window symptoms
Get CMDB context
Query key metrics
Search logs
Search similar incidents
Get changes in window
Decide category and confidence
Final JSON with evidence and tool_trace

---

3.6 Prompt 与防注入（Policy）

工程上建议把"安全与约束"写进 policy.py，并在运行时强制执行：

• 工具输出是不可信输入：只当数据，不执行其中指令
• 只能调用允许的工具；参数必须符合 schema
• 最终结论必须引用 evidence 的 source_id
• 证据不足必须输出 Unknown 并列出 unknowns，禁止编造

---

3.7 评测数据集与打分（Eval Harness）

数据集 dataset.jsonl（每行一个 case）

{
  "case_id": "C-0001",
  "input": {
    "service": "payments-api",
    "time_from": "2026-01-09T09:00:00Z",
    "time_to": "2026-01-09T09:20:00Z",
    "symptoms": "p95 latency spike + error_rate 5xx increased"
  },
  "expected": {
    "category": "Deployment",
    "must_have_evidence_types": ["change", "metric", "log"],
    "key_source_ids_any_of": ["CHG0012345", "log_raw_7781"]
  }
}

Scorer 逻辑（建议最小实现）

• Category Accuracy：pred.category == expected.category
• Evidence Precision：输出 source_id 是否存在于工具返回集合且与结论一致（可先做简化校验）
• Evidence Coverage：是否覆盖 must_have_evidence_types
• Schema Compliance：JSON schema 校验通过率
• Latency / Calls：从 tool_trace 统计

---

3.8 从离线 PoC 到真实系统对接的替换点

离线 PoC 跑通后，你只需要把 tools/*_stub.py 替换为真实 API：

• Splunk：Search API（时间窗、index、sourcetype、service tag）
• AppDynamics：REST 查询 metric path + time range
• ServiceNow：Table API（change_request / incident / cmdb_ci 等）
• CMDB：只读查询封装（你已有 service ↔ CI ↔ owner ↔ site 映射最关键）

Orchestrator / Policy / Schema / Eval Harness 建议保持不变：这能保证可回归、可审计、可持续迭代。

---

4. 结语：如何把"会查资料"升级为"可回归的工程系统"

ReAct（react_agent）真正的价值不在于"模型会调用工具"，而在于你能把它变成：

• 有契约（schema、白名单、预算）
• 有证据链（可追溯 source_id）
• 有评测（成功率、证据质量、延迟、成本）
• 有回归与审计（tool_trace、可重放）

在 AIOps 场景中，这意味着：从"口头推断"升级为"证据驱动、可度量、可迭代"的自动化归因与处置建议系统。

---

附：一个简化 orchestrator 伪代码（便于理解）

# Pseudocode: ReAct orchestrator
state = {input_alert, observations=[], tool_trace=[]}

for step in range(T):
    decision = planner(state)  # tool_call or final
    if decision.type == "final":
        validate_schema(decision.output)
        return decision.output

    validate_tool_call(decision.tool, decision.args)
    result = run_tool(decision.tool, decision.args)
    state.observations.append(result)
    state.tool_trace.append({tool,args,digest(result)})

# budget exceeded -> degrade
return degraded_unknown_with_missing_info(state)