How bytedance/trae-agent works
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