Trae-Agent中的tool reflection机制

Trae Agent 反思机制详解

概述

Trae Agent 的反思机制（Reflection Mechanism）是一种自动错误处理和自纠正机制。当工具执行失败时，系统会自动生成反思提示，帮助 LLM 识别错误并调整策略。

核心作用

功能	说明
错误检测	自动检测工具执行失败
错误提示	生成人类可读的失败提示
策略引导	建议 LLM 尝试不同方法或修复参数
状态标记	标记当前处于 "Reflecting" 状态

代码位置

文件 : trae_agent/agent/base_agent.py

1. 反思触发点

python 复制代码

async def _tool_call_handler(
    self, 
    tool_calls: list[ToolCall] | None, 
    step: AgentStep
) -> list[LLMMessage]:
    """处理工具调用，包含反思逻辑"""
    
    # 1. 执行工具调用
    if self._model_config.parallel_tool_calls:
        tool_results = await self._tool_caller.parallel_tool_call(tool_calls)
    else:
        tool_results = await self._tool_caller.sequential_tool_call(tool_calls)
    
    step.tool_results = tool_results
    
    # 2. 将工具结果添加到消息
    for tool_result in tool_results:
        message = LLMMessage(role="user", tool_result=tool_result)
        messages.append(message)
    
    # 3. 【关键】检查是否有失败的工具，生成反思
    reflection = self.reflect_on_result(tool_results)
    if reflection:
        step.state = AgentStepState.REFLECTING  # 标记反思状态
        step.reflection = reflection
        
        # 显示反思状态
        self._update_cli_console(step)
        
        # 将反思添加到对话
        messages.append(LLMMessage(role="assistant", content=reflection))
    
    return messages

2. 反思生成逻辑

python 复制代码

def reflect_on_result(self, tool_results: list[ToolResult]) -> str | None:
    """
    反思工具执行结果
    只在有工具失败时返回提示，成功时返回 None
    """
    
    # 如果没有工具结果，不反思
    if len(tool_results) == 0:
        return None

    # 只收集失败的工具错误信息
    reflection = "\n".join(
        f"The tool execution failed with error: {tool_result.error}. "
        f"Consider trying a different approach or fixing the parameters."
        for tool_result in tool_results
        if not tool_result.success  # ← 关键：只处理失败的工具
    )

    return reflection if reflection else None

反思触发条件

场景	工具结果	是否反思	原因
工具执行成功	`success=True`	❌ 不反思	无需纠正，继续正常流程
工具执行失败	`success=False`	✅ 反思	需要提示 LLM 调整策略
没有工具调用	`tool_results=[]`	❌ 不反思	无结果可反思
部分失败	部分成功部分失败	✅ 反思	只针对失败的部分生成提示

实际流程示例

场景：执行测试脚本失败

css 复制代码

第 1 步：LLM 决定执行测试
┌─────────────────────────────────────────────────────────────┐
│ LLM Response:                                               │
│ "I'll run the test script to verify the bug."              │
│                                                             │
│ Tool Calls:                                                 │
│ [`bash`] `{"command": "python test_bug.py"}`               │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
第 2 步：工具执行
┌─────────────────────────────────────────────────────────────┐
│ Tool Result:                                                │
│ success: False                                              │
│ error: "FileNotFoundError: No such file: test_bug.py"      │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
第 3 步：生成反思（关键）
┌─────────────────────────────────────────────────────────────┐
│ reflection = reflect_on_result(tool_results)                │
│                                                             │
│ 输出:                                                       │
│ "The tool execution failed with error: FileNotFoundError:  │
│  No such file: test_bug.py. Consider trying a different    │
│  approach or fixing the parameters."                       │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
第 4 步：添加到对话历史
┌─────────────────────────────────────────────────────────────┐
│ Messages:                                                   │
│ 1. {role: "user", tool_result: {...}}  ← 工具结果          │
│ 2. {role: "assistant", content: "The tool execution..."}   │
│                                         ← 反思提示         │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
第 5 步：下轮 LLM 看到反思
┌─────────────────────────────────────────────────────────────┐
│ LLM 理解:                                                   │
│ "哦，上一步执行测试脚本失败了，因为文件不存在。            │
│  我需要先创建测试文件，然后再执行。"                       │
│                                                             │
│ 下轮行动:                                                   │
│ [`str_replace_based_edit_tool`] `{"command": "create",...}`│
└─────────────────────────────────────────────────────────────┘

反思机制的优势

1. 自动错误检测

python 复制代码

# 不需要 LLM 自己判断工具是否成功
# 系统自动检测 success=False 的情况
if not tool_result.success:
    # 自动生成反思

2. 引导自我纠正

python 复制代码

# 明确的纠正建议
"Consider trying a different approach or fixing the parameters."

# LLM 收到后会:
# 1. 意识到上一步失败了
# 2. 思考失败原因
# 3. 调整策略重新尝试

3. 状态可视化

python 复制代码

step.state = AgentStepState.REFLECTING

# CLI 显示:
# 💭 Step 3: Reflecting
#    The tool execution failed with error: ...

4. 避免死循环

python 复制代码

# 没有反思机制时:
# LLM: 执行命令 A → 失败 → 再执行命令 A → 失败 → 循环...

# 有反思机制时:
# LLM: 执行命令 A → 失败 → 【反思】→ 执行命令 B → 成功

与其他模块的交互

与 CLI 模块的交互

python 复制代码

# 在 _tool_call_handler 中
if reflection:
    step.state = AgentStepState.REFLECTING
    step.reflection = reflection
    
    # 更新 CLI 显示
    self._update_cli_console(step)
    # 显示: 💭 Step X: Reflecting

与对话历史的交互

python 复制代码

# 反思作为 assistant 消息添加到对话
messages.append(LLMMessage(role="assistant", content=reflection))

# 下轮 LLM 能看到完整的上下文:
# 1. 工具调用请求
# 2. 工具执行结果（失败）
# 3. 反思提示（建议调整）

可扩展性

reflect_on_result 是一个可重写的方法，子类可以自定义反思逻辑：

python 复制代码

class CustomAgent(BaseAgent):
    def reflect_on_result(self, tool_results: list[ToolResult]) -> str | None:
        """自定义反思逻辑"""
        
        # 基础错误收集
        errors = [
            tool_result.error 
            for tool_result in tool_results 
            if not tool_result.success
        ]
        
        if not errors:
            return None
        
        # 自定义反思策略
        if "timeout" in str(errors):
            return "The command timed out. Consider breaking it into smaller steps."
        elif "permission" in str(errors):
            return "Permission denied. Check file permissions or use sudo."
        else:
            return f"Errors occurred: {errors}. Please analyze and fix."

总结

问题	答案
什么时候反思？	工具执行失败时 (`success=False`)
反思什么？	工具错误信息和纠正建议
谁生成反思？	`reflect_on_result` 方法自动生成
反思给谁看？	添加到对话历史，下轮 LLM 能看到
目的是什么？	帮助 LLM 从错误中学习，调整策略
可以自定义吗？	可以，重写 `reflect_on_result` 方法

核心设计原则：

自动化 - 无需人工干预，自动检测和提示
非侵入 - 只在出错时触发，正常流程不受影响
可扩展 - 支持自定义反思策略
可视化 - 通过 CLI 状态显示，便于调试

最后更新: 2026-03-16