Trae Agent

Trae Agent 是一款基于 LLM 的通用软件工程任务智能体。它提供强大的 CLI 界面，能够理解自然语言指令，并利用各种工具和 LLM 服务提供商执行复杂的软件工程工作流。

技术细节请参考 我们的技术报告。

项目状态：该项目仍在积极开发中。如果您希望帮助我们改进 Trae Agent，请参考 docs/roadmap.md 和 CONTRIBUTING。

与其他 CLI 智能体的区别：Trae Agent 提供透明、模块化的架构，研究人员和开发人员可以轻松修改、扩展和分析，使其成为研究 AI 智能体架构、进行消融实验和开发新型智能体能力的理想平台。这种**“研究友好型设计”** 使学术界和开源社区能够为基础智能体框架做出贡献并在此基础上进行构建，从而在快速发展的 AI 智能体领域推动创新。

✨ 特性

• 🌊 Lakeview：为智能体步骤提供简洁明了的总结
• 🤖 多 LLM 支持：兼容 OpenAI、Anthropic、Doubao、Azure、OpenRouter、Ollama 和 Google Gemini API
• 🛠️ 丰富的工具生态：文件编辑、bash 执行、顺序思维等
• 🎯 交互模式：用于迭代开发的对话式界面
• 📊 轨迹记录：详细记录所有智能体操作，便于调试和分析
• ⚙️ 灵活配置：基于 YAML 的配置，支持环境变量
• 🚀 轻松安装：简单的 pip 安装方式

🚀 安装

要求

• UV（https://docs.astral.sh/uv/）
• 所选提供商的 API 密钥（OpenAI、Anthropic、Google Gemini、OpenRouter 等）

设置

git clone https://github.com/bytedance/trae-agent.git
cd trae-agent
uv sync --all-extras
source .venv/bin/activate

⚙️ 配置

YAML 配置（推荐）

1. 复制示例配置文件：

   cp trae_config.yaml.example trae_config.yaml
   

2. 使用您的 API 凭证和偏好设置编辑 trae_config.yaml：

agents:
  trae_agent:
    enable_lakeview: true
    model: trae_agent_model  # the model configuration name for Trae Agent
    max_steps: 200  # max number of agent steps
    tools:  # tools used with Trae Agent
      - bash
      - str_replace_based_edit_tool
      - sequentialthinking
      - task_done

model_providers:  # model providers configuration
  anthropic:
    api_key: your_anthropic_api_key
    provider: anthropic
  openai:
    api_key: your_openai_api_key
    provider: openai

models:
  trae_agent_model:
    model_provider: anthropic
    model: claude-sonnet-4-20250514
    max_tokens: 4096
    temperature: 0.5

注意： trae_config.yaml 文件会被 git 忽略，以保护您的 API 密钥。

使用基础 URL

在某些情况下，我们需要为 api 使用自定义 URL。只需在 provider 后添加 base_url 字段，以下面的配置为例：

openai:
    api_key: your_openrouter_api_key
    provider: openai
    base_url: https://openrouter.ai/api/v1

注意： 字段格式设置仅允许使用空格，不允许使用制表符（\t）。

环境变量（替代方案）

您也可以使用环境变量配置 API 密钥，并将其存储在 .env 文件中：

export OPENAI_API_KEY="your-openai-api-key"
export OPENAI_BASE_URL="your-openai-base-url"
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export ANTHROPIC_BASE_URL="your-anthropic-base-url"
export GOOGLE_API_KEY="your-google-api-key"
export GOOGLE_BASE_URL="your-google-base-url"
export OPENROUTER_API_KEY="your-openrouter-api-key"
export OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
export DOUBAO_API_KEY="your-doubao-api-key"
export DOUBAO_BASE_URL="https://ark.cn-beijing.volces.com/api/v3/"

MCP 服务（可选）

要启用模型上下文协议（MCP）服务，请在您的配置中添加 mcp_servers 部分：

mcp_servers:
  playwright:
    command: npx
    args:
      - "@playwright/mcp@0.0.27"

配置优先级： 命令行参数 > 配置文件 > 环境变量 > 默认值

旧版 JSON 配置： 若使用旧版 JSON 格式，请参见 docs/legacy_config.md。建议迁移至 YAML。

📖 用法

基本命令

# Simple task execution
trae-cli run "Create a hello world Python script"

# Check configuration
trae-cli show-config

# Interactive mode
trae-cli interactive

特定提供商示例

# OpenAI
trae-cli run "Fix the bug in main.py" --provider openai --model gpt-4o

# Anthropic
trae-cli run "Add unit tests" --provider anthropic --model claude-sonnet-4-20250514

# Google Gemini
trae-cli run "Optimize this algorithm" --provider google --model gemini-2.5-flash

# OpenRouter (access to multiple providers)
trae-cli run "Review this code" --provider openrouter --model "anthropic/claude-3-5-sonnet"
trae-cli run "Generate documentation" --provider openrouter --model "openai/gpt-4o"

# Doubao
trae-cli run "Refactor the database module" --provider doubao --model doubao-seed-1.6

# Ollama (local models)
trae-cli run "Comment this code" --provider ollama --model qwen3

高级选项

# Custom working directory
trae-cli run "Add tests for utils module" --working-dir /path/to/project

# Save execution trajectory
trae-cli run "Debug authentication" --trajectory-file debug_session.json

# Force patch generation
trae-cli run "Update API endpoints" --must-patch

# Interactive mode with custom settings
trae-cli interactive --provider openai --model gpt-4o --max-steps 30

Docker 模式命令

准备工作

重要提示：您需要确保环境中已配置 Docker。

使用方法

# Specify a Docker image to run the task in a new container
trae-cli run "Add tests for utils module" --docker-image python:3.11

# Specify a Docker image to run the task in a new container and mount the directory
trae-cli run "write a script to print helloworld" --docker-image python:3.12 --working-dir test_workdir/

# Attach to an existing Docker container by ID (`--working-dir` is invalid with `--docker-container-id`)
trae-cli run "Update API endpoints" --docker-container-id 91998a56056c

# Specify an absolute path to a Dockerfile to build an environment
trae-cli run "Debug authentication" --dockerfile-path test_workspace/Dockerfile

# Specify a path to a local Docker image file (tar archive) to load
trae-cli run "Fix the bug in main.py" --docker-image-file test_workspace/trae_agent_custom.tar

# Remove the Docker container after finishing the task (keep default)
trae-cli run "Add tests for utils module" --docker-image python:3.11 --docker-keep false

交互模式命令

在交互模式下，您可以使用：

• 输入任何任务描述以执行任务
• status - 显示代理信息
• help - 显示可用命令
• clear - 清屏
• exit 或 quit - 结束会话

🛠️ 高级功能

可用工具

Trae Agent 提供了一套全面的工具集，用于软件工程任务，包括文件编辑、bash 执行、结构化思考和任务完成。有关所有可用工具及其功能的详细信息，请参见 docs/tools.md。

轨迹记录

Trae Agent 会自动记录详细的执行轨迹，以便进行调试和分析：

# Auto-generated trajectory file
trae-cli run "Debug the authentication module"
# Saves to: trajectories/trajectory_YYYYMMDD_HHMMSS.json

# Custom trajectory file
trae-cli run "Optimize database queries" --trajectory-file optimization_debug.json

轨迹文件包含LLM交互、代理步骤、工具使用情况以及执行元数据。有关更多详细信息，请参见docs/TRAJECTORY_RECORDING.md。

🔧 开发

贡献

有关贡献指南，请参阅CONTRIBUTING.md。

故障排除

导入错误：

PYTHONPATH=. trae-cli run "your task"

API 密钥问题：

# Verify API keys
echo $OPENAI_API_KEY
trae-cli show-config

命令未找到：

uv run trae-cli run "your task"

权限错误：

chmod +x /path/to/your/project

📄 许可证

本项目采用 MIT 许可证授权 - 详情参见 LICENSE 文件。

✍️ 引用

@article{traeresearchteam2025traeagent,
      title={Trae Agent: An LLM-based Agent for Software Engineering with Test-time Scaling},
      author={Trae Research Team and Pengfei Gao and Zhao Tian and Xiangxin Meng and Xinchen Wang and Ruida Hu and Yuanan Xiao and Yizhou Liu and Zhao Zhang and Junjie Chen and Cuiyun Gao and Yun Lin and Yingfei Xiong and Chao Peng and Xia Liu},
      year={2025},
      eprint={2507.23370},
      archivePrefix={arXiv},
      primaryClass={cs.SE},
      url={https://arxiv.org/abs/2507.23370},
}

🙏 致谢

感谢 Anthropic 开发了 anthropic-quickstart 项目，该项目为工具生态系统提供了宝贵的参考。