发帖
雷达卡
如今，大多数智能体架构的核心都集中在多个智能体如何协同工作，并从预定义的工具库中选择工具。这种设计虽然有效，但隐含了一个假设：完成任务所需的工具是提前已知的。
在本文中，我们将挑战这一假设。
现代大型语言模型（LLMs）已经能够将复杂目标分解为多步骤计划、推理执行顺序，并生成正确、可执行的代码。换句话说，它们不仅仅是使用工具——它们还能创建工具。
本文将探索如何利用“计划-编码-执行”（Plan–Code–Execute）智能体架构，构建一个端到端的可解释性智能体（Explainability Agent），通过真实场景展示工具如何按需生成。
本文提出的架构也可轻松适配其他场景。
场景背景
我们将对一个用于需求预测的图神经网络（GNN）模型结果进行解释，该模型我已在之前的文章中探讨过。我们有以下需要解释的数据信号：
节点（库存单位，SKUs）的空间特征
添加到图节点的时间特征（销售订单、生产数据等）
用于预测库存单位需求的图神经网络模型结果
用于检测生产异常的图神经网络模型结果
所有这些数据都生成了一系列分析结果、结论和图表，需要从规划者的角度进行全面解释，且解释需基于事实和领域知识。
可解释性智能体架构
我们将创建一个“计划-编码-执行”的智能体工作流。为了在工具生成过程中获得更精细的控制、可解释性和灵活性，我们将构建完全自定义的智能体，而非依赖知名编排框架的抽象封装。具体将创建以下智能体：
1. 分析师智能体（Analyst Agent）
我们需要一个分析师智能体作为应用的“眼睛”。它的职责是探索应用程序其他部分将使用的环境（原始数据、模型结果、先前输出）。它能防止幻觉问题，例如规划者智能体假设销售文件名为“sales.csv”，而数据集中实际的文件名是“Sales Order.csv”。
除了扫描现有资源外，它还会打开文件并创建动态 schema（模式）。例如，Sales Order.csv 包含列 [日期（Date）、金额（Amount）]，而 demand_vs_production.csv 包含列 [预测值（Predicted）、实际值（Actual）]。这些信息将构成规划者智能体的上下文。
2. 规划者智能体（Planner）
规划者智能体接收用户的高层目标和分析师智能体生成的 schema，充当应用的“大脑”。它的职责是将用户请求分解为带有依赖关系的步骤图。为实现这一点，它首先从用户请求中推断意图：如果用户询问“准确性”，它就会定位到“预测结果（Forecast Results）”文件夹；如果用户询问“销售历史”，它就会定位到“原始数据（Raw Data）”。其输出是一个 JSON 格式的计划，其中每个步骤都清晰描述了具体任务，并包含一个标记为“CODE（需要编码）”或“TEXT（仅需文本）”的标识。只有标记为 CODE 的步骤，才会由编码智能体生成工具。
示例输出：一个 JSON 计划
步骤1：加载图数据并找到节点 SOS001L12P 的邻居。（CODE）
步骤2：聚合时间维度的销售与生产数据。（CODE）
步骤3：计算加权绝对百分比误差（WAPE）。（CODE）
步骤4：准备总结报告。（TEXT）
3. 编码智能体（Coder）
编码智能体是应用的“双手”，承担大部分实际工作。它接收计划中的每个步骤和 schema，对于每个标记为 CODE 的计划步骤，它会编写一个独立、可执行的 Python 脚本。
它负责处理库导入（如 pandas、networkx）、绝对路径和错误捕获。它生成的是自给自足的软件，而非仅仅是代码片段。
4. 执行智能体（Executor）
执行智能体在受控环境中运行生成的脚本。为此，它会捕获标准输出（stdout）和标准错误（stderr）。如果脚本运行失败（例如出现“文件未找到（FileNotFound）”错误），日志将提供反馈循环以支持潜在的自我修正（不过由于分析师智能体提供的上下文支撑，这种情况实际上很少发生）。
5. 报告智能体（Reporter）
最后，报告智能体读取脚本生成的日志和产物（CSV 文件、PNG 图片），并按照用户要求的语气、深度和角色，回答用户最初的问题。它充当应用的“声音”。
这些智能体通过一个简单的编排脚本（main.py）按顺序调用。config.py 文件包含数据集文件夹（含节点和边信息）以及需求预测和生产异常检测模型结果文件夹的路径。每个智能体和编排脚本的代码都不足 100 行，所使用的大型语言模型为 gemini-2.5-flash。
测试过程中遇到的主要错误是编码智能体引用了不存在的数据源（幻觉问题），为此我们强化了编码智能体的提示词，要求其严格遵循计划步骤的上下文。此外，最初并未设计分析师智能体，后来为了防止幻觉，在规划者智能体之前添加了这一用于上下文支撑的步骤。
以下是规划者智能体的参考代码
import json
from ..llm.client import GeminiClient
class Planner:
def __init__(self):
self.llm = GeminiClient()
def create_plan(self, user_prompt, dataset_context=""):
"""Decomposes user prompt into execution steps."""
system_prompt = f"""
You are a Senior Project Manager for a Data Science team.
Your goal is to break down a high-level user request into a list of specific, executable steps.
--- DATASET AVAILABLE (Use EXACT Filenames) ---
{dataset_context}
-----------------------------------------------
--- DATASET GUIDELINES ---
- The dataset contains both 'Raw Data' (Historical) and 'Model Results' (Predictions/Anomalies).
- CAREFULLY infer which source is needed based on the user's goal.
- Example: "Sales Analysis" -> Raw Data. "Forecast Accuracy" -> Model Results.
Output format: JSON list of ob jects with fields:
- step_id: int
- name: str (short title)
- desc ription: str (detailed instruction for the coder)
- type: "CODE" (if it requires writing a sc ript) or "TEXT" (if just a summary)
--- SCOPE RESTRICTION ---
- DO NOT USE Machine Learning (LinearRegression, Training, Random Forest).
- USE ONLY Statistical Analysis (Mean, Median, Std Dev, Z-Score, Rolling Averages).
- FOCUS on Data Visualization (Line plots, Histograms).
- If the user asks for "forecast" or "accuracy", PREFER WAPE (Weighted MAPE) over standard MAPE.
Example:
User: "Analyze SKU001"
Output:
[
{{"step_id": 1, "name": "Load Data", "desc ription": "Load Nodes.csv and filter for SKU001 to get basic info.", "type": "CODE"}},
{{"step_id": 2, "name": "Temporal Analysis", "desc ription": "Load Production.csv and Sales.csv. Calculate monthly volume and trend for SKU001.", "type": "CODE"}}
]
"""
full_prompt = f"{system_prompt}\n\nUser Request: {user_prompt}\nJSON Plan:"
response = self.llm.generate_content(full_prompt)
# basic cleanup for JSON markdown blocks
clean_response = response.replace("```json", "").replace("```", "").strip()
print(f"\n[DEBUG] Raw Planner Response:\n{response}\n") # Added for debugging
try:
return json.loads(clean_response)
except json.JSONDecodeError:
print(f"Failed to parse plan: {response}")
return []
实验结果
我们将重点关注库存单位 SOS001L12P 的端到端可解释性。该节点是销售量最大的库存单位，规划者和管理层会希望尽早发现相关问题，以确保需求满足和服务质量维持。
我们将通过 4 个步骤构建可解释性分析：
分析该库存单位与其供应链网络中邻居节点的共享关系
分析销售量的趋势
将销售量与生产信号关联，标注异常情况
结合需求预测质量，创建一份综合报告，解释该库存单位的健康状况
空间分析（Spatial Analysis）
为智能体设定的目标是：
“对节点 SOS001L12P 周围的空间结构进行全面分析，并为我提供带有标签的图边缘可视化结果，展示该库存单位与其邻居节点的连接关系。”
规划者智能体生成了一个包含 5 个步骤的计划，用于加载节点和边数据、提取邻居节点和边的属性、准备带有标签的图可视化结果，以及创建空间结构报告。
计划详情见此
[
{
"step_id": 1,
"name": "Load Node and Edge Data",
"desc ription": "Load 'Nodes.csv' to confirm 'SOS001L12P' as a valid node. Load all edge datasets: 'Edges (Plant).csv', 'Edges (Product Group).csv', 'Edges (Product Sub-Group).csv', and 'Edges (Storage Location).csv'. These files contain the structural information needed for spatial analysis.",
"type": "CODE"
},
{
"step_id": 2,
"name": "Extract Direct Neighbors and Edge Attributes",
"desc ription": "Iterate through each loaded edge dataset. For each dataset, filter rows where 'SOS001L12P' is present in either the 'node1' or 'node2' column. For each matching record, identify the neighboring node and extract the specific edge attribute that defines the relationship (e.g., 'Plant' from 'Edges (Plant).csv', 'GroupCode' from 'Edges (Product Group).csv', 'SubGroupCode' from 'Edges (Product Sub-Group).csv', 'Storage Location' from 'Edges (Storage Location).csv'). Consolidate all unique neighbors and their corresponding labeled relationships into a single structure.",
"type": "CODE"
},
{
"step_id": 3,
"name": "Prepare Graph for Visualization",
"desc ription": "Construct a graph ob ject (e.g., using NetworkX) with 'SOS001L12P' as the central node. Add all identified direct neighbors as nodes and create edges between 'SOS001L12P' and each neighbor. Assign the extracted edge attributes (e.g., 'Plant: Plant A', 'GroupCode: GRP1') as labels to these edges for clarity in the visualization.",
"type": "CODE"
},
{
"step_id": 4,
"name": "Visualize Graph Edges with Labels",
"desc ription": "Generate a clear graph visualization of the spatial structure around 'SOS001L12P'. The plot should display 'SOS001L12P' prominently in the center, with its direct neighbors connected by edges. Each edge must be explicitly labeled with the type of relationship and its specific attribute value (e.g., 'Plant: P001', 'Product Group: PG002'). Ensure appropriate layout and styling for readability.",
"type": "CODE"
},
{
"step_id": 5,
"name": "Summarize Spatial Connectivity",
"desc ription": "Provide a textual summary of the spatial structure around 'SOS001L12P'. Describe the types of entities it is connected to (Plants, Product Groups, Product Sub-Groups, Storage Locations), list the specific neighbors identified, and briefly explain the nature of these connections based on the edge labels.",
"type": "TEXT"
}
]
编码智能体为每个 CODE 步骤创建了 4 个工具。
主要输出结果是该库存单位与其邻居节点关系的图，所有关系均带有标签（如共享工厂、存储位置、产品组等）。
同时生成了一份简要的分析报告，其中指出：
“邻居关系：分析识别出 39 种不同的关系，将 SOS001L12P 与 39 个独特的邻居节点连接起来。”
结果呈现在此
节点 SOS001L12P 空间结构深度分析
已完成对节点 SOS001L12P 周边空间结构的全面分析。
分析结论
1. 节点有效性验证
节点 SOS001L12P 已在主数据中确认为有效节点。
2. 邻居节点关系
本次分析共识别出 39 条独立关联关系，将 SOS001L12P 与 39 个唯一邻居节点 相连。
这些关系按 关系类型（RelationshipType） 和 关系值（RelationshipValue） 分类如下：
- 工厂（Plant）
SOS001L12P 通过多个工厂编码与多个邻居相连，包括：
2103、2111、2112、2114、2115、2116、2117、2118、2119、2120、2121、2122。
- 组编码（GroupCode）
SOS001L12P 与以下节点共享组编码 S：
SOS008L02P、SOS005L04P、SOS003L04P、SOS002L09P、SOS500M24P、SOS250M48P、SOP001L12P、SO0005L04P、SO0002L09P、SO0001L12P、SO0500M24P、SE500G24P、SE200G24P。
- 子组编码（SubGroupCode）
SOS001L12P 通过子组编码 SOS 与以下节点关联：
SOS008L02P、SOS005L04P、SOS003L04P、SOS002L09P、SOS500M24P、SOS250M48P。
- 存储地点（Storage Location）
SOS001L12P 通过多个存储地点编码与邻居关联，包括：
330.0、1130.0、1230.0、1430.0、1530.0、1630.0、1730.0、1830.0、1930.0、2030.0、2130.0、2230.0。
完整文件输出
所有邻居节点及具体关系明细，可在以下文件查看：
C:/Auto-agent/workspace/output/SOS001L12P_neighbors_relationships.csv
可视化结果
已生成以 SOS001L12P 为中心 的网络图可视化，展示其所有直接邻居节点及连接边，并标注：
- 关系类型（RelationshipType）
- 关系值（RelationshipValue）
图表统计
- 总节点数：40（含 SOS001L12P 自身）
- 总边数：39
可视化图片路径：
C:/Auto-agent/workspace/output/SOS001L12P_neighbor_graph.png
销售订单（需求）信号分析
由于我们关注需求预测模型的准确性，分析销售趋势至关重要。设定的目标是：
“对 SOS001L12P 的销售订单时间信号进行分析，标注趋势、异常值以及销售量趋势中的任何异常情况。”
规划者智能体生成了一个包含 6 个步骤的计划，用于加载和处理销售数据、计算 7 天和 30 天滚动平均值、识别异常值、可视化趋势以及准备报告。
计划详情见此（原文未提供具体计划，此处保留原文表述）
编码智能体创建了 5 个工具，该流程的主要输出是以下趋势图。值得注意的是，在时间段的后半部分出现了下降趋势，这可能是一个需要调查的令人担忧的问题。
分析报告也提到了这一下降趋势：
“持续下降：从 1 月到 8 月，日销售量和滚动平均值（7 天和 30 天）均持续下降，这清楚地表明 SOS001L12P 的销售量呈持续下滑趋势。”
结果呈现在此
SOS001L12P 销售订单时序信号分析
本分析覆盖产品 SOS001L12P 在 2023 年 1 月 1 日 —2023 年 8 月 9 日 的销售数据。
1. 期间销量趋势
SOS001L12P 的销量在整个分析周期内呈现明显且持续的下降趋势。
- 2023 年 1 月初，日销量处于高位，单日最高销量达 21,394 件；截至 1 月 10 日，30 日滚动均值约为 12,629。
- 到 2023 年 8 月初，销量已大幅下滑。截至 8 月 9 日，30 日滚动均值降至约 5,165，表明八个月内稳定销量出现显著萎缩。
2. 持续下滑及其他问题
- 持续下滑：1 月至 8 月期间，日销量、7 日滚动均值与 30 日滚动均值均持续下降，明确表明 SOS001L12P 销量呈长期下行态势。
- 异常点：分析共识别出 14 个异常日期，主要表现为销量异常偏低，判定依据为 Z‑分数低于‑2.0，或连续 3 日负增长。其中显著的大幅下跌包括：
-2023 年 1 月 4 日：销量跌至 10,920.08
-2023 年 3 月 8 日：销量录得极低值 200.00
- 零销量：在周期末期出现零销量记录（如 8 月 8 日、8 月 9 日），进一步加剧下滑趋势，凸显销售表现存在严重问题。
生产信号分析
将生产异常报告与销售趋势关联起来，分析销售下滑的潜在原因至关重要。为此，我们为智能体设定了以下目标：
“对 SOS001L12P 的生产时间信号进行分析，标注趋势、异常值以及销售量趋势中的任何异常情况。”
规划者智能体生成了一个包含 7 个步骤的计划，与销售分析计划类似，用于计算趋势和异常值，同时还会可视化异常检测模型生成的异常情况。
计划详情见此
[
{
"step_id": 1,
"name": "Load Sales Order Data for SOS001L12P",
"desc ription": "Load the 'Sales Order.csv' file from C:\\AnomalyGNN\\dataset\\Raw Dataset\\Temporal Data\\Unit\\Sales Order.csv. Focus on the 'Date' and 'SOS001L12P' columns, treating 'SOS001L12P' as the sales volume.",
"type": "CODE"
},
{
"step_id": 2,
"name": "Preprocess Temporal Data",
"desc ription": "Convert the 'Date' column to datetime ob jects and set it as the Datafr ame index. Ensure the sales volume column (SOS001L12P) is numerical. Handle any missing values, potentially by filling with 0 or forward/backward fill if appropriate for sales data (specify chosen method).",
"type": "CODE"
},
{
"step_id": 3,
"name": "Analyze Sales Volume Trends",
"desc ription": "Calculate 7-day and 30-day rolling averages for the 'SOS001L12P' sales volume. These will help identify short-term and long-term trends in the sales signal. Store these as new columns in the Datafr ame.",
"type": "CODE"
},
{
"step_id": 4,
"name": "Detect Outliers using Z-Score",
"desc ription": "Calculate the Z-score for the 'SOS001L12P' sales volume. Identify potential outliers by marking data points where the absolute Z-score exceeds a predefined threshold (e.g., 2 or 3 standard deviations). Store the Z-score and an 'Is_Outlier' boolean column.",
"type": "CODE"
},
{
"step_id": 5,
"name": "Visualize Sales Order Temporal Signal",
"desc ription": "Create a time-series line plot showing the 'SOS001L12P' sales volume over time. Overlay the 7-day and 30-day rolling averages. Highlight the identified outliers on the plot to visually represent abnormalities in volume trends.",
"type": "CODE"
},
{
"step_id": 6,
"name": "Summarize Trends and Abnormalities",
"desc ription": "Provide a textual summary of the observed trends (e.g., seasonality, growth/decline), the frequency and magnitude of identified outliers, and any other notable abnormalities or shifts in the sales volume patterns for SOS001L12P. This summary should interpret the visualizations and statistical measures.",
"type": "TEXT"
}
]
智能体创建了相应的工具并执行，生成了输出结果。以下是生产趋势图，更重要的是，图中显示时间段后半部分出现了大量异常，这可能是影响销售的原因。
生成的报告中指出：
“尽管未检测到 Z 分数异常值，但更复杂的异常检测方法在 SOS001L12P 的生产数据中识别出了 17 个异常数据点。”
完整报告见此（原文未提供完整报告，此处保留原文表述）
端到端供应链规划者报告
既然我们已经对 SOS001L12P 进行了时空分析，下一步就是将这些发现与需求预测模型关联起来，观察模型如何适应这些趋势，并为该库存单位的健康状况准备一份完整报告，供规划者提交给管理层。
为此，我们设定了以下目标：
“我是一名供应链规划者。我希望你结合最近完成的所有分析以及其他数据源，为 SOS001L12P 生成一份端到端报告。我注意到，在时间段的后半部分，生产量呈下降趋势，同时出现了许多异常情况。请将生产量与需求预测关联起来，并评论我们的预测模型在该时间段的表现。”
规划者智能体生成了一个计划，用于关联生产、销售和需求预测数据，使用主要指标 WAPE（加权绝对百分比误差）评估预测模型性能，然后准备一份综合报告。
计划详情见此（原文未提供具体计划，此处保留原文表述）
综合分析生成了一份可供规划者直接使用的评估报告，其结论部分指出：
“对于库存单位 SOS001L12P，分析时间段的后半部分（2023 年 4 月 21 日 - 2023 年 8 月 9 日）的特点是波动性增加、实际生产量呈下降趋势，同时伴随大量异常情况。此期间的实际生产量也低于实际销售量。虽然需求预测模型有效地捕捉了实际销售趋势（后半部分的 WAPE 为 29.70%，相比整体的 35.44% 有所改善），但生产量未能与这些需求保持一致，导致生产量与销售量和预测需求之间的相关性较弱。这些差异（通常与已识别的生产异常同时发生）表明，潜在的供应限制或运营中断影响了我们持续满足需求的能力。”
完整报告见此（原文未提供完整报告，此处保留原文表述）
这是一份生产级别的报告，包含事实、数据和关键绩效指标（KPIs），以支持得出的解释结论。
而所有这一切，都是通过一个完全灵活的智能体框架实现的，该框架可以适应任何所需的可解释性目标。
开发和测试该应用程序，以及生成上述报告和结果，所需的令牌使用成本不到 1 美元。
结论
智能体系统的未来，不在于更大的工具目录或更复杂的编排框架，而在于能够自主决定“首先需要存在什么工具”的智能体。
当规划、编码和执行被视为推理步骤时，工具就不再是静态资产，而成为可丢弃的产物——根据问题需求被创建、使用和丢弃。这将智能体设计的重心，从“通过提示工程将智能体和工具绑定到编排框架”，转向“将软件生成作为核心能力”。
“计划-编码-执行”架构表明，生产级别的、基于证据的分析，可以由小型、透明的智能体实现，只需极少的粘合代码和极低的成本。随着大型语言模型的不断改进，最有价值的智能体将是那些能够自主将意图转化为可运行软件的智能体——无需提前告知它们具体如何实现。
从这个意义上说，自动规划和自动编码智能体不仅仅是一种便利，更是智能体系统的自然进化。
推荐学习书籍 《CDA一级教材》适合CDA一级考生备考，也适合业务及数据分析岗位的从业者提升自我。完整电子版已上线CDA网校，累计已有10万+在读~ !
京公网安备 11010802022788号
