在构建基于 SQL 的问答系统时，代理（Agent）的动态决策能力至关重要。它通过与工具的多轮交互，逐步拼凑出答案所需的信息。本文将基于实际代码和执行日志，逐字节拆解代理执行过程中三类核心消息的交互细节，让每个工具调用、参数生成和结果处理的逻辑都清晰可溯。

一、消息体系：代理决策的 “神经系统”

代理执行流程本质是消息驱动的状态机，包含三种消息类型，通过stream方法按时间顺序输出，形成完整的 “决策链条”：

1. Human Message（用户输入）

• 角色：流程起点，携带用户自然语言问题
• 示例：

  plaintext

  ========================[1m Human Message [0m========================  
  Which country's customers spent the most?  
  

• 关键作用：触发代理对问题的初步解析，判断需要哪些工具辅助（如表结构查询、数据聚合等）。

2. Ai Message（代理的工具调用决策）

• 角色：代理的 “思考痕迹”，明确下一步操作（工具名、参数、唯一调用 ID）
• 结构：

  plaintext

  =======================[1m Ai Message [0m=======================  
  Tool Calls:  
    sql_db_schema (call_KJZ1Jx6JazyDdJa0uH1UeiOz)  # 工具名 + 唯一调用ID  
    Call ID: call_KJZ1Jx6JazyDdJa0uH1UeiOz         # 用于追踪全流程的标识符  
    Args:                                           # 工具入参（严格遵循工具定义格式）  
      table_names: Customer, Invoice                # 目标表名（逗号分隔字符串）  
  

• 核心逻辑：根据历史消息（用户问题 + 工具返回结果），动态决定调用哪个工具、传入什么参数。

3. Tool Message（工具执行结果反馈）

• 角色：工具向代理反馈的结构化信息，作为下一步决策的依据
• 示例（表结构工具返回）：

  sql

  ========================[1m Tool Message [0m========================  
  Name: sql_db_schema              # 工具名（与调用时一致）  
  Result:  
  CREATE TABLE "Customer" (  
      "CustomerId" INTEGER NOT NULL,  
      "Country" NVARCHAR(40),        # 关键业务字段（用于国家筛选）  
      FOREIGN KEY("SupportRepId") REFERENCES "Employee" ("EmployeeId")  
  )  
  /* 示例数据（帮助代理理解字段含义）  
  CustomerId    Country  
  1    Brazil  
  2    Germany  
  */  
  

二、全流程消息交互：以 “消费最多国家” 查询为例

1. 初始状态：用户问题触发流程

Human Message首次出现，代理此时对数据库结构一无所知：

plaintext

====================[1m Human Message [0m====================  
Which country's customers spent the most?  # 核心需求：按国家统计消费总额  

2. 第一步：代理决定获取表列表

Ai Message表明代理缺乏表信息，选择sql_db_list_tables工具（无参数，默认返回所有表名）：

plaintext

=====================[1m Ai Message [0m======================  
Tool Calls:  
  sql_db_list_tables (call_tFp7HYD6sAAmCShgeqkVZH6Q)  
  Args: （无，工具自动获取全表）  

Tool Message返回表列表，代理从中识别出关键表Customer（客户）和Invoice（发票）：

plaintext

====================[1m Tool Message [0m====================  
Name: sql_db_list_tables  
Result: Album, Artist, Customer, Employee, Genre, Invoice, ...  # 省略无关表  

3. 第二步：代理获取表结构细节

Ai Message基于上一步结果，调用sql_db_schema工具，传入目标表名参数：

plaintext

=====================[1m Ai Message [0m======================  
Tool Calls:  
  sql_db_schema (call_KJZ1Jx6JazyDdJa0uH1UeiOz)  
  Args:  
    table_names: Customer, Invoice  # 明确需要这两张表的结构（来自表列表结果）  

Tool Message返回详细 DDL 和示例数据，代理从中获取关键信息：

• Customer.Country存储国家名称
• Invoice.Total存储消费金额，CustomerId作为外键关联客户表
• 两表通过CustomerId建立JOIN关系

4. 第三步：代理生成并验证查询

Ai Message根据表结构生成 SQL 查询，并调用sql_db_query_checker工具验证语法：

plaintext

=====================[1m Ai Message [0m======================  
Tool Calls:  
  sql_db_query_checker (call_AQuTGbgH63u4gPgyV723yrjX)  
  Args:  
    query: SELECT c.Country, SUM(i.Total) as TotalSpent  # 关联查询语句  
           FROM Customer c JOIN Invoice i  
           ON c.CustomerId = i.CustomerId  
           GROUP BY c.Country ORDER BY TotalSpent DESC LIMIT 1;  

Tool Message确认查询合法（无语法错误提示），代理获得执行许可。

5. 第四步：代理执行最终查询

Ai Message调用sql_db_query工具，传入已验证的查询：

plaintext

=====================[1m Ai Message [0m======================  
Tool Calls:  
  sql_db_query (call_B88EwU44nwwpQL5M9nlcemSU)  
  Args: （同上查询语句）  

Tool Message返回结果[('USA', 523.06)]，代理确认数据足够回答问题。

6. 最终状态：生成自然语言答案

代理不再调用工具，直接基于查询结果生成回答，消息链终止：

plaintext

=====================[1m Ai Message [0m======================  
The country whose customers spent the most is the USA, with a total spending of 523.06.  

三、消息中的关键技术细节

1. 工具调用的 “参数传承” 机制

代理不会凭空生成参数，而是严格依赖历史消息：

• sql_db_schema的table_names参数值，来自sql_db_list_tables的返回结果
• sql_db_query的query参数，基于sql_db_schema返回的表结构和字段名生成
• 代码验证：通过toolkit.get_tools()获取的工具，其参数校验逻辑与消息链强绑定，确保入参合法。

2. 上下文的 “动态累加” 逻辑

每次Tool Message的结果都会作为新输入传递给 LLM，形成 “决策 - 反馈 - 修正” 闭环：

这种机制让代理能逐步缩小知识缺口，例如：在不知道Invoice表有Total字段时，绝不会生成聚合查询。

3. 错误处理的消息轨迹

当代理生成错误查询（如拼写错误的表名Customr），消息链会出现关键转折：

1. Tool Message返回错误：sqlite3.OperationalError: no such table: Customr
2. Ai Message重新生成查询：修正表名为Customer，再次调用sql_db_query
3. Tool Message返回正确结果：错误在消息链中被捕获并修复，无需人工干预。

四、消息调试：定位代理 “卡壳” 的 3 个核心步骤

1. 检查工具调用顺序是否符合业务逻辑

• 正确顺序：表列表（sql_db_list_tables）→ 表结构（sql_db_schema）→ 查询执行（sql_db_query）
• 反例：若跳过表结构查询直接执行查询，必因字段名错误失败，消息链中会出现连续的错误反馈。

2. 验证参数格式是否匹配工具要求

• sql_db_schema的table_names必须是逗号分隔的字符串（如"Customer, Invoice"），而非列表["Customer", "Invoice"]
• 错误参数会导致Tool Message返回Invalid input format，需在Ai Message的Args中检查格式。

3. 追踪上下文是否完整传递

• 关键检查点：sql_db_query的query中是否包含sql_db_schema返回的字段名（如Country、Total）
• 若字段名缺失，说明代理在生成查询时未正确利用表结构消息，需优化系统提示或 LLM 训练数据。

五、总结：消息是破解代理逻辑的 “钥匙”

通过解析消息链，我们看到代理的每个决策都是数据驱动的：

• Human Message定义问题边界
• Ai Message记录决策路径（调用什么工具、传什么参数）
• Tool Message提供执行依据（表结构、查询结果等）

掌握这套消息体系，就能：

1. 快速定位复杂查询失败的原因（如字段名错误、关联条件缺失）
2. 优化工具调用策略（如通过系统提示让代理优先检查语法）
3. 理解代理的 “思维盲区”（如无法处理未在表结构中出现的字段）

下次开发 SQL 问答系统时，记得用stream方法打印完整消息链 —— 这是破解代理逻辑最直接的方式。觉得有帮助的话，欢迎收藏本文，后续我们将深入探讨如何通过消息分析提升代理的复杂查询能力！