trae-agent README

The project's README from github.com/bytedance/trae-agent. As one markdown file: README.md.

Trae Agent

arXiv:2507.23370 Python 3.12+ License: MIT Pre-commit Unit Tests Discord

Trae Agent is an LLM-based agent for general purpose software engineering tasks. It provides a powerful CLI interface that can understand natural language instructions and execute complex software engineering workflows using various tools and LLM providers.

For technical details please refer to our technical report.

Project Status: The project is still being actively developed. Please refer to docs/roadmap.md and CONTRIBUTING if you are willing to help us improve Trae Agent.

Difference with Other CLI Agents: Trae Agent offers a transparent, modular architecture that researchers and developers can easily modify, extend, and analyze, making it an ideal platform for studying AI agent architectures, conducting ablation studies, and developing novel agent capabilities. This research-friendly design enables the academic and open-source communities to contribute to and build upon the foundational agent framework, fostering innovation in the rapidly evolving field of AI agents.

✨ Features

🚀 Installation

Requirements

Setup

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

⚙️ Configuration

  1. Copy the example configuration file:

    cp trae_config.yaml.example trae_config.yaml

  2. Edit trae_config.yaml with your API credentials and preferences:

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

Note: The trae_config.yaml file is ignored by git to protect your API keys.

Using Base URL

In some cases, we need to use a custom URL for the api. Just add the base_url field after provider, take the following config as an example:

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

Note: For field formatting, use spaces only. Tabs (\t) are not allowed.

Environment Variables (Alternative)

You can also configure API keys using environment variables and store them in the .env file:

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 Services (Optional)

To enable Model Context Protocol (MCP) services, add an mcp_servers section to your configuration:

mcp_servers:
  playwright:
    command: npx
    args:
      - "@playwright/[email protected]"

Configuration Priority: Command-line arguments > Configuration file > Environment variables > Default values

Legacy JSON Configuration: If using the older JSON format, see docs/legacy_config.md. We recommend migrating to YAML.

📖 Usage

Basic Commands

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

# Check configuration
trae-cli show-config

# Interactive mode
trae-cli interactive

Provider-Specific Examples

# 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

Advanced Options

# 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 Mode Commands

Preparation

Important: You need to make sure Docker is configured in your environment.

Usage

# 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

Interactive Mode Commands

In interactive mode, you can use:

🛠️ Advanced Features

Available Tools

Trae Agent provides a comprehensive toolkit for software engineering tasks including file editing, bash execution, structured thinking, and task completion. For detailed information about all available tools and their capabilities, see docs/tools.md.

Trajectory Recording

Trae Agent automatically records detailed execution trajectories for debugging and analysis:

# 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

Trajectory files contain LLM interactions, agent steps, tool usage, and execution metadata. For more details, see docs/TRAJECTORY_RECORDING.md.

🔧 Development

Contributing

For contribution guidelines, please refer to CONTRIBUTING.md.

Troubleshooting

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

✍️ Citation

@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},
}

🙏 Acknowledgments

We thank Anthropic for building the anthropic-quickstart project that served as a valuable reference for the tool ecosystem.

trae-agent (bytedance/trae-agent)

Searching Database…

12.1K ·GitHub
Trae-agent
这是什么？Trae Agent 是一个基于大语言模型（LLM）的智能体，可作为通用软件工程任务的命令行助手。它能理解自然语言指令，并借助各种工具和多家大模型服务商，执行复杂的编程工作流。
这是命令行工具，还是可以导入的库？它主要是一个带交互模式的命令行工具，采用透明的模块化架构，便于研究和扩展。
我该如何安装和运行它？通过 pip 或 UV 安装，复制示例 YAML 配置文件，填入你的 API 凭据，然后运行 CLI 命令或启动交互模式。
使用前需要先有 API 密钥并安装 UV 吗？需要。你需要先安装 UV，并且要有所选服务商的 API 密钥，可选 OpenAI、Anthropic、Doubao、Azure、OpenRouter、Ollama 或 Google Gemini 中的任意一家。
这个工具稳定到可以日常使用吗？项目仍在积极开发中，可能会持续有变动。README 中提供了一份路线图文档，介绍后续的工作计划。
这个工具面向哪些人？面向希望使用 AI 编程智能体完成工程任务的开发者，以及研究或扩展智能体架构的研究人员。
它能在 Windows 和 Mac 上运行，还是只支持 Linux？它是一个 Python 命令行工具，文档中没有提到任何操作系统限制，因此可以跨平台运行于 Linux、macOS 和 Windows。
Trae Agent 可以使用哪些大模型服务商？支持 OpenAI、Anthropic、Doubao、Azure、OpenRouter、Ollama 和 Google Gemini 的 API，可通过 YAML 配置文件或环境变量进行设置。
什么是 Lakeview？Lakeview 是一项功能，会在智能体处理任务的过程中，为其每个步骤提供简短精炼的摘要。
它能在 Docker 中运行吗？可以。它提供了 Docker 模式及其专用命令，但需要你的环境中已经配置好 Docker。
它会记录智能体做过的事情吗？会。轨迹记录功能会记录所有大模型交互、智能体步骤、工具使用情况以及执行元数据，便于调试和分析。
它能连接 MCP 服务器吗？可以。你可以选择在配置中添加 mcpservers 部分，以启用 Model Context Protocol（模型上下文协议）服务。
What are similar projects?Agent-S, qwen-code, overmind, TradingAgents, Baize, copperhead, turnstone, claude-code
Which topics is it in?software-engineering, azure, openrouter, coding-agents, model-context-protocol, ollama, agentic-ai, gemini, anthropic, mcp-server, coding-agent, ai-agent
Creator
bytedance
Size
3 MB
Stars
12.1K
Updated
CommitFeb 05
Age
1y
Commits · 90 Days