# bytedance/trae-agent architecture

> Architecture diagram of the GitHub repository bytedance/trae-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bytedance/trae-agent
- Repository: https://github.com/bytedance/trae-agent

## Overview

##### Project type and purpose
- Trae Agent is a **CLI-based, LLM-driven software engineering agent** written in Python.
- Its main goal is to accept natural-language tasks, orchestrate tool invocations, record trajectories, and call external LLM services (OpenAI, Anthropic).

##### File structure
- Top-level:
- `trae_agent/` package – contains all core code
- `cli.py` – CLI entrypoint
- `pyproject.toml`, `trae_config.json` – build and config
- `TRAJECTORY_RECORDING.md`, `README.md` – docs
- Sub-packages:
- `agent/` – core agent logic: base classes, controller (`trae_agent.py`), step orchestration
- `tools/` – concrete “tools” the agent can call (bash, edit, sequential thinking, task_done)
- `utils/` – LLM clients (OpenAI, Anthropic, Azure), config loader, console I/O, trajectory recorder, lake-view summarizer

##### README for additional insights
- The agent supports **multi-LLM**, **interactive mode**, **trajectory recording**, **rich tool ecosystem**, and **flexible JSON + env var config**.
- Data flow: user → CLI (`trae-cli`) → Agent Core → Tools + LLM clients → external LLM APIs → Agent picks next action → optional file edits or CLI output → trajectory logged.

1. **User / CLI Interface**
2. **Agent Core** (`trae_agent.agent`)
3. **Tool Layer** (`trae_agent.tools`)
4. **LLM Client Layer** (`trae_agent.utils.llm_client`, `openai_client`, `anthropic_client`, `azure_client`)
5. **Configuration Manager** (`trae_agent.utils.config` + `trae_config.json` + env vars)
6. **Trajectory Recorder** (`trae_agent.utils.trajectory_recorder`)
7. **File System / Workspace** (project files being edited)
8. **External LLM Services** (OpenAI API, Anthropic API)

- User → CLI Interface (“trae-cli run …”)
- CLI → Agent Core (pass parsed args, task descriptions)
- Agent Core ↔ Configuration Manager (load priorities: CLI args → config file → env → defaults)
- Agent Core → Tool Layer (invoke tools: bash, edit, sequential thinking, task_done)
- Tool Layer → File System (for create/view/edit operations)
- Agent Core → LLM Client Layer (send prompt, receive response)
- LLM Client Layer → External LLM Services (HTTP calls)
- Agent Core → Trajectory Recorder (log each step, decisions, tool calls, LLM exchanges)
- Trajectory Recorder → File System (write `.json` logs)
- Agent Core → CLI (print progress, final results)

c. Architectural patterns / design principles:
- **Modular plugin pattern** for tools – each tool inherits from a base and registers itself
- **Separation of concerns**: CLI parsing, agent logic, tool implementations, client APIs, config, logging
- **Pipeline of decision steps** – agent loop uses sequential reasoning tool to break down tasks
- **Decorator-like clients** for LLM providers, sharing common interface (`llm_basics`)

d. Key technologies / frameworks:
- Python 3.12+, PEP-compliant modules
- UV for project sync
- External HTTP APIs to OpenAI / Anthropic
- JSON config + environment variables
- Standard Python logging / file I/O

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and CLI
    User["User"]:::external
    CLI["CLI Interface\n(trae_agent/cli.py)"]:::internal
    click CLI "https://github.com/bytedance/trae-agent/blob/main/trae_agent/cli.py"

    %% Agent Core Subgraph
    subgraph "Agent Core" 
        direction TB
        TraeAgent["TraeAgent\n(trae_agent/agent/trae_agent.py)"]:::internal
        BaseAgent["Base Agent\n(trae_agent/agent/base.py)"]:::internal
        AgentBasics["Agent Basics\n(trae_agent/agent/agent_basics.py)"]:::internal
        click TraeAgent "https://github.com/bytedance/trae-agent/blob/main/trae_agent/agent/trae_agent.py"
        click BaseAgent "https://github.com/bytedance/trae-agent/blob/main/trae_agent/agent/base.py"
        click AgentBasics "https://github.com/bytedance/trae-agent/blob/main/trae_agent/agent/agent_basics.py"
    end

    %% Tools Layer Subgraph
    subgraph "Tool Layer" 
        direction TB
        BaseTool["Tool Base\n(trae_agent/tools/base.py)"]:::internal
        BashTool["Bash Tool\n(trae_agent/tools/bash_tool.py)"]:::internal
        EditTool["Edit Tool\n(trae_agent/tools/edit_tool.py)"]:::internal
        SeqThink["Sequential Thinking Tool\n(trae_agent/tools/sequential_thinking_tool.py)"]:::internal
        TaskDone["Task Done Tool\n(trae_agent/tools/task_done_tool.py)"]:::internal
        click BaseTool "https://github.com/bytedance/trae-agent/blob/main/trae_agent/tools/base.py"
        click BashTool "https://github.com/bytedance/trae-agent/blob/main/trae_agent/tools/bash_tool.py"
        click EditTool "https://github.com/bytedance/trae-agent/blob/main/trae_agent/tools/edit_tool.py"
        click SeqThink "https://github.com/bytedance/trae-agent/blob/main/trae_agent/tools/sequential_thinking_tool.py"
        click TaskDone "https://github.com/bytedance/trae-agent/blob/main/trae_agent/tools/task_done_tool.py"
    end

    %% LLM Client Layer Subgraph
    subgraph "LLM Client Layer"
        direction TB
        BaseClient["Base Client\n(trae_agent/utils/base_client.py)"]:::internal
        LLMBasics["LLM Basics\n(trae_agent/utils/llm_basics.py)"]:::internal
        LLMClient["LLM Client\n(trae_agent/utils/llm_client.py)"]:::internal
        OpenAI["OpenAI Client\n(trae_agent/utils/openai_client.py)"]:::internal
        Anthropic["Anthropic Client\n(trae_agent/utils/anthropic_client.py)"]:::internal
        Azure["Azure Client\n(trae_agent/utils/azure_client.py)"]:::internal
        click BaseClient "https://github.com/bytedance/trae-agent/blob/main/trae_agent/utils/base_client.py"
        click LLMBasics "https://github.com/bytedance/trae-agent/blob/main/trae_agent/utils/llm_basics.py"
        click LLMClient "https://github.com/bytedance/trae-agent/blob/main/trae_agent/utils/llm_client.py"
        click OpenAI "https://github.com/bytedance/trae-agent/blob/main/trae_agent/utils/openai_client.py"
        click Anthropic "https://github.com/bytedance/trae-agent/blob/main/trae_agent/utils/anthropic_client.py"
        click Azure "https://github.com/bytedance/trae-agent/blob/main/trae_agent/utils/azure_client.py"
    end

    %% Utils Subgraph
    subgraph "Utilities"
        direction TB
        Config["Config Manager\n(trae_agent/utils/config.py + trae_config.json)"]:::config
        Recorder["Trajectory Recorder\n(trae_agent/utils/trajectory_recorder.py)"]:::config
        ConsoleIO["Console I/O\n(trae_agent/utils/cli_console.py)"]:::internal
        LakeView["Lake-View Summarizer\n(trae_agent/utils/lake_view.py)"]:::internal
        click Config "https://github.com/bytedance/trae-agent/blob/main/trae_agent/utils/config.py"
        click Recorder "https://github.com/bytedance/trae-agent/blob/main/trae_agent/utils/trajectory_recorder.py"
        click ConsoleIO "https://github.com/bytedance/trae-agent/blob/main/trae_agent/utils/cli_console.py"
        click LakeView "https://github.com/bytedance/trae-agent/blob/main/trae_agent/utils/lake_view.py"
    end

    %% Storage and External
    FS["File System / Workspace"]:::storage
    Logs["Trajectory Logs"]:::storage
    ExternalOpenAI["OpenAI API"]:::external
    ExternalAnthropic["Anthropic API"]:::external

    %% Project Metadata & Docs
    Meta["Project Metadata & Docs\n(pyproject.toml, README.md, TRAJECTORY_RECORDING.md)"]:::config
    click Meta "https://github.com/bytedance/trae-agent/blob/main/pyproject.toml"

    %% Connections
    User -->|"enters command"| CLI
    CLI -->|"invokes"| TraeAgent
    TraeAgent -->|"load config"| Config
    Config -->|"reads"| Meta
    TraeAgent -->|"invoke tool"| BaseTool
    TraeAgent -->|"invoke tool"| BashTool
    TraeAgent -->|"invoke tool"| EditTool
    TraeAgent -->|"invoke tool"| SeqThink
    TraeAgent -->|"invoke tool"| TaskDone
    BaseTool --> FS
    BashTool --> FS
    EditTool --> FS
    SeqThink --> FS
    TaskDone --> FS
    TraeAgent -->|"send prompt"| LLMClient
    LLMClient -->|"use basics"| LLMBasics
    LLMClient --> BaseClient
    LLMClient --> OpenAI
    LLMClient --> Anthropic
    LLMClient --> Azure
    OpenAI --> ExternalOpenAI
    Anthropic --> ExternalAnthropic
    TraeAgent -->|"log step"| Recorder
    Recorder --> Logs
    Recorder --> FS
    TraeAgent -->|"output progress"| ConsoleIO
    ConsoleIO --> CLI
    TraeAgent --> LakeView

    %% Styles
    classDef internal fill:#E3F2FD,stroke:#69A3F7;
    classDef external fill:#E6F4EA,stroke:#34A853;
    classDef config fill:#FFF3E0,stroke:#FB8C00;
    classDef storage fill:#F3E5F5,stroke:#8E24AA;
```
