Trae Agent

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

• 🌊 Lakeview: Provides short and concise summarisation for agent steps
• 🤖 Multi-LLM Support: Works with OpenAI, Anthropic, Doubao, Azure, OpenRouter, Ollama and Google Gemini APIs
• 🛠️ Rich Tool Ecosystem: File editing, bash execution, sequential thinking, and more
• 🎯 Interactive Mode: Conversational interface for iterative development
• 📊 Trajectory Recording: Detailed logging of all agent actions for debugging and analysis
• ⚙️ Flexible Configuration: YAML-based configuration with environment variable support
• 🚀 Easy Installation: Simple pip-based installation

🚀 Installation

Requirements

• UV (https://docs.astral.sh/uv/)
• API key for your chosen provider (OpenAI, Anthropic, Google Gemini, OpenRouter, etc.)

Setup

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

⚙️ Configuration

YAML Configuration (Recommended)

1. Copy the example configuration file: bash cp trae_config.yaml.example trae_config.yaml

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

```yaml agents: traeagent: enablelakeview: true model: traeagentmodel # the model configuration name for Trae Agent maxsteps: 200 # max number of agent steps tools: # tools used with Trae Agent - bash - strreplacebasededittool - sequentialthinking - taskdone

modelproviders: # model providers configuration anthropic: apikey: youranthropicapikey provider: anthropic openai: apikey: youropenaiapi_key provider: openai

models: traeagentmodel: modelprovider: anthropic model: claude-sonnet-4-20250514 maxtokens: 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:

bash 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:

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

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

```bash

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

```bash

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

```bash

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

```bash

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 testworkspace/traeagent_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: - Type any task description to execute it - status - Show agent information - help - Show available commands - clear - Clear the screen - exit or quit - End the session

🛠️ 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:

```bash

Auto-generated trajectory file

trae-cli run "Debug the authentication module"

Saves to: trajectories/trajectoryYYYYMMDDHHMMSS.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: bash PYTHONPATH=. trae-cli run "your task"

API Key Issues: ```bash

Verify API keys

echo $OPENAIAPIKEY trae-cli show-config ```

Command Not Found: bash uv run trae-cli run "your task"

Permission Errors: bash chmod +x /path/to/your/project

📄 License

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

✍️ Citation

bibtex @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.