Trae Agent: Run Complex Dev Workflows With Plain English Prompts

Trae Agent is a command-line interface (CLI) powered by Large Language Models (LLMs) designed to automate general software engineering tasks. By providing instructions in plain English, you can delegate complex development workflows to the agent. It supports multiple model providers—including OpenAI and Anthropic—and features a versatile toolkit for file creation, text editing, Bash command execution, and structured, sequential reasoning.

To keep users informed, Trae Agent generates concise step-by-step summaries (via a feature called Lakeview), supports interactive development for iterative tasks, and maintains detailed execution traces for debugging and auditing. Configuration is handled easily through JSON files and environment variables.

✨ Features

🌊 Lakeview: Provides clear, human-readable summaries for every action the agent takes.
🤖 Multi-Model Support: Integrates directly with official OpenAI and Anthropic APIs.
🛠️ Comprehensive Toolkit: Capabilities include file manipulation, shell command execution, and sequential logic.
🎯 Interactive Mode: An ongoing conversation loop for real-time, iterative development.
📊 Trajectory Logging: Maintains a full record of agent actions for post-task analysis and debugging.
⚙️ Flexible Configuration: Setup is managed via JSON with support for environment variable overrides.
🚀 Streamlined Installation: Available via Pip, with UV recommended for efficient environment management.

Getting Started

Installation

We recommend using UV to set up the project environment.

git clone <repository-url>
cd trae-agent
uv sync

API Keys

You can configure Trae Agent using a configuration file or by exporting your keys as environment variables:

# For OpenAI
export OPENAI_API_KEY="your-openai-api-key"

# For Anthropic
export ANTHROPIC_API_KEY="your-anthropic-api-key"

Basic Usage

To execute a simple task, use the following command:

trae-cli run "create a hello world Python script"

How to Use Trae Agent

Command Line Interface

The primary entry point is the trae command, which includes several specialized subcommands.

trae run — Execute a Task

Use this command to initiate a specific engineering task:

# Basic execution
trae-cli run "write a Python script that calculates Fibonacci numbers"

# Specify a provider and model
trae-cli run "fix the bug in main.py" --provider anthropic --model claude-sonnet-4-20250514

# Define a custom working directory
trae-cli run "add unit tests for the utils module" --working-dir /path/to/project

# Export the trajectory for review
trae-cli run "refactor the database module" --trajectory-file debug_session.json

# Force the agent to generate patches
trae-cli run "update the API endpoints" --must-patch

trae interactive — Interactive Mode

For ongoing tasks that require back-and-forth communication, use interactive mode:

# Start a session
trae-cli interactive

# Start with a specific configuration
trae-cli interactive --provider openai --model gpt-4o --max-steps 30

While in interactive mode, you can:

• Enter any task description to trigger the agent.
• Type status to view the agent's current configuration.
• Type help for a full list of available commands.
• Type clear to refresh the terminal screen.
• Type exit or quit to end the session.

trae show-config — View Configuration

Check your current settings with:

trae-cli show-config

# View a specific configuration file
trae-cli show-config --config-file my_config.json

Configuration

Trae Agent stores settings in a JSON file (trae_config.json). Below is an example structure:

{
  "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
    }
  }
}

Settings are applied according to the following priority:

1. Command-line arguments (Highest)
2. Config file values
3. Environment variables
4. Built-in defaults (Lowest)

Environment Variables

• OPENAI_API_KEY: Your OpenAI API key.
• ANTHROPIC_API_KEY: Your Anthropic API key.

Available Tools

Trae Agent comes equipped with several built-in tools to handle diverse tasks:

str_replace_based_edit_tool: For file system management and text editing.

• view: Displays file content or lists directory structures.
• create: Generates new files.
• str_replace: Performs string replacement within existing files.
• insert: Adds text at a specified line number.

bash: For running shell commands and scripts.

• Executes shell commands with a persistent state across steps.
• Manages background or long-running processes.
• Captures and returns standard output (stdout) and error messages (stderr).

sequential_thinking: For structured problem-solving.

• Deconstructs complex requirements into manageable steps.
• Allows the agent to revise its strategy based on new information.
• Facilitates hypothesis generation and testing.

task_done: To signal completion.

• Formally marks a task as finished.
• Returns the final summary and results to the user.

Trajectory Logging

Trae Agent automatically records detailed execution logs, known as trajectories.

# This command generates an automatic trajectory file
trae-cli run "debug the auth module"

# The output will look like: trajectory_20250612_220546.json

# You can also manually name the file
trae-cli run "optimize the database queries" --trajectory-file optimization_debug.json

Every trajectory file contains:

• LLM Interactions: A full history of messages, model responses, and tool calls.
• Agent Steps: A record of state transitions and internal reasoning.
• Tool Usage: Details on which tools were invoked and their specific outputs.
• Metadata: Execution metrics including timestamps and token consumption.

For further details on log analysis, refer to TRAJECTORY_RECORDING.md.

Common Issues

Import Errors: If the CLI cannot find the project modules, try setting the PYTHONPATH:

PYTHONPATH=. trae-cli run "your task"

API Key Problems: Ensure your keys are correctly exported and recognized:

# Check if keys are active in the environment
echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY

# Review the agent's active configuration
trae show-config

Permission Errors: If the agent cannot modify files, verify directory permissions:

# Grant necessary permissions to your project directory
chmod +x /path/to/your/project