Trae Agent：打造高效的软件工程自动化助手

“

前言：
随着软件交付节奏加快，工程师常常需要在 CLI、脚本、测试、文档之间反复切换。Trae Agent 致力于让你通过自然语言指令，就能在代码编辑、测试、部署等环节执行复杂工作流，解放双手与思维焦点。

一、Trae Agent 简介

Trae Agent 是一个面向通用软件工程任务的 LLM 驱动代理（agent）工具，提供了：

  • 自然语言任务执行：通过 trae-cli run "任务描述"，即可完成从生成脚本到修复 Bug、编写测试的全流程。
  • 多模支持：兼容 OpenAI 和 Anthropic 官方 API，灵活切换模型和参数。
  • 丰富工具箱：集成文件编辑、Bash 执行、顺序思考（sequential thinking）等多种工具，覆盖绝大多数开发场景。
  • 交互式模式：trae-cli interactive 打开对话式界面，实时查看状态、调用帮助、清理环境。
  • 灵活配置：支持 JSON 配置文件与环境变量，优先级清晰。
  • 轨迹记录：自动或自定义保存详细的执行日志（trajectory），助力调试、审核与分析。

二、核心功能一览

功能模块 作用 适用场景
🌊 Lakeview 为每一步代理执行提供简洁摘要 快速理解多步任务脉络
🤖 Multi-LLM Support 支持 OpenAI、Anthropic 多家模型 按需求选择高精度或低成本模型
🛠️ Rich Tool Ecosystem 文件编辑、Bash、顺序思考、标记任务完成等工具一应俱全 代码生成、脚本调试、文档修改
🎯 Interactive Mode 对话式界面，实时发命令、查看状态、帮助、清屏、退出 灵活实验、快速验证
📊 Trajectory Recording 记录所有 LLM 交互、代理步骤、工具调用、执行元数据 调试故障、审计合规、性能分析
⚙️ Flexible Configuration JSON 配置 + 环境变量，命令行参数优先 在 CI/CD 与本地开发环境间轻松切换

三、安装与快速上手

“

步骤概览（HowTo）

  1. 克隆项目
  2. 同步依赖
  3. 配置 API Key
  4. 执行任务
git clone <repository-url>      # 克隆仓库到本地  
cd trae-agent                   # 进入项目目录  
uv sync                         # 使用 UV 同步依赖（推荐）  
export OPENAI_API_KEY="xxx"     # 配置 OpenAI API Key  
export ANTHROPIC_API_KEY="yyy"  # 配置 Anthropic API Key  
trae-cli run "创建一个 Hello World 脚本"
  • 命令行参数优先，可通过 --model、--provider、--max-steps 动态覆盖配置文件。
  • 交互模式：trae-cli interactive --provider openai --model gpt-4o，进入对话式环境。

四、配置详解

配置项支持四种优先级（由高到低）：

  1. 命令行参数
  2. 配置文件（trae_config.json）
  3. 环境变量
  4. 默认值
{
  "default_provider": "anthropic",
  "max_steps": 20,
  "model_providers": {
    "openai": {
      "api_key": "your_openai_api_key",
      "model": "gpt-4o",
      "max_tokens": 128000,
      "temperature": 0.5,
      "top_p": 1
    },
    "anthropic": {
      "api_key": "your_anthropic_api_key",
      "model": "claude-sonnet-4-20250514",
      "max_tokens": 4096,
      "temperature": 0.5,
      "top_p": 1,
      "top_k": 0
    }
  }
}
  • default_provider：默认 LLM 提供方
  • max_steps：最大思考与执行步数，防止死循环
  • model_providers：多模型参数，支持并行测试与对比

五、轨迹记录功能深度解析

5.1 为什么要记录轨迹？

  • 调试：精确回溯 Agent 在每一步的决策、工具调用与 LLM 响应。
  • 审计：在合规场景下，完整保留执行记录与版本信息。
  • 优化：通过元数据分析模型使用效率、Token 消耗与工具调用频率。

5.2 轨迹文件结构

轨迹文件为 JSON 格式，主要字段：

字段 含义
task 原始任务描述
start_time / end_time ISO 时间戳
provider / model 使用的 LLM 提供方及模型
max_steps 允许最大步数
llm_interactions 包含每次请求的消息、响应、Token 用量和工具调用
agent_steps 逐步记录 Agent 状态（thinking、calling_tool、reflecting、completed、error）
success 任务是否成功
final_result 最终输出
execution_time 执行总时长（秒）

“

示例片段：

{
  "timestamp": "2025-06-12T22:05:47.000000",
  "provider": "anthropic",
  "input_messages": [...],
  "response": {
    "content": "I'll help you create a hello world script...",
    "tool_calls": [...]
  }
}
``` :contentReference[oaicite:1]{index=1}

5.3 启用与自定义轨迹文件名

  • 自动文件名（默认当前目录）：

    trae-cli run "任务描述"
# 会生成：trajectory_YYYYMMDD_HHMMSS.json

  • 指定文件名：

    trae-cli run "修复 main.py 错误" --trajectory-file my_debug.json

六、工具生态与拓展

  1. str_replace_based_edit_tool

    • …查看、创建、编辑文件

  2. bash

    • 执行脚本与命令，持久化工作目录

  3. sequential_thinking

    • 分块思考、多次反馈、灵活回退

  4. task_done

    • 标记任务结束，并输出总结

“

示例：

trae-cli run "为 utils 模块添加单元测试" --working-dir ./project

执行过程中，Agent 会依次思考、写测试、运行、报告结果。

七、常见问题（FAQ）

1. Trae Agent 支持哪些平台？

支持所有能运行 Python 3.12+ 的操作系统，包括 macOS、Linux 和 Windows（通过 WSL）。

2. 如何切换 LLM 提供方？

通过 `–provider openai` 或 `–provider anthropic`，也可在配置文件中修改 `default_provider`。

3. 轨迹文件是否会覆盖已有文件？

若指定文件名已存在，则会覆盖；默认生成的时间戳文件不会重复。

4. 怎样查看可用命令？

“`bash
trae-cli –help
trae-cli run –help
“`

5. 如何调优模型参数？

在配置文件或命令行添加 `–temperature`、`–top_p` 等参数即可。

八、HowTo：快速开启轨迹记录

# 1. 安装并同步
git clone <repo>
cd trae-agent
uv sync

# 2. 配置环境变量
export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."

# 3. 执行并记录
trae-cli run "重构数据库模块" --trajectory-file db_refactor.json

九、结语

通过 Trae Agent，你可以将常见的软件工程任务抽象为自然语言指令，借助 LLM 和插件工具，快速完成脚本编写、Bug 修复、测试生成与部署准备。其灵活的配置与详尽的轨迹记录，为团队协作、调试与审计提供有力支持。立即动手试用，让 AI 助手替你分担重复枯燥的开发工作，聚焦更重要的核心逻辑与创意实现。