wehub/bytedance--trae-agent

Fork 0

Files

T

wehub-resource-sync 4902d40668

Pre-commit / Pre-commit checks (push) Waiting to run

Details

Unit Tests / test (push) Waiting to run

Details

docs: make Chinese README the default

2026-07-13 10:49:04 +00:00

10 KiB

Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Trae Agent

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

技术细节请参阅我们的技术报告.

项目状态： 项目仍在积极开发中。若你愿意帮助我们改进 Trae Agent，请参阅 docs/roadmap.md 和 CONTRIBUTING。

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

✨ 功能特性

🌊 Lakeview：为智能体步骤提供简短精炼的摘要
🤖 多 LLM 支持：兼容 OpenAI、Anthropic、Doubao、Azure、OpenRouter、Ollama 和 Google Gemini API
🛠️ 丰富的工具生态：文件编辑、bash 执行、顺序思考（sequential thinking）等
🎯 交互模式：面向迭代开发的对话式界面
📊 轨迹记录：详细记录所有智能体操作，便于调试与分析
⚙️ 灵活配置：基于 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 配置（推荐）

复制示例配置文件：

cp trae_config.yaml.example trae_config.yaml

编辑 trae_config.yaml，填入你的 API 凭据和偏好设置：

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 密钥。

使用 Base 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 服务（可选）

要启用模型上下文协议（Model Context Protocol，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 为软件工程任务提供全面的工具集，包括文件 editing、Bash 执行、structured thinking（结构化思考）和 task completion（任务完成）。有关所有可用工具及其功能的详细信息，请参阅 docs/tools.md。

轨迹记录（Trajectory Recording）

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 交互、agent 步骤、工具使用情况和执行元数据。更多详情请参阅 docs/TRAJECTORY_RECORDING.md。

🔧 开发

贡献

贡献指南请参阅 CONTRIBUTING.md。

故障排查

Import Errors:

PYTHONPATH=. trae-cli run "your task"

API Key Issues:

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

Command Not Found:

uv run trae-cli run "your task"

Permission Errors:

chmod +x /path/to/your/project

📄 许可证

本项目采用 MIT License — 详情请参阅 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 project that served as a valuable reference for the tool ecosystem.

10 KiB Raw Permalink Blame History Unescape Escape