1. 引言

TRAE 作为新一代 AI 编程助手，不仅支持对话式编码，还提供了强大的智能体（Agent）能力。通过创建和管理智能体，开发者可以将重复性、流程化的开发任务交给智能体自动完成，从而显著提升开发效率。本文将从零开始，详细介绍如何在 TRAE 中创建、配置、使用和管理智能体，并给出丰富的代码实例。

2. 什么是 TRAE 智能体

智能体是 TRAE 中的一种可复用的自动化执行单元。它封装了特定的提示词、上下文、工具调用规则和执行流程，可以在项目开发中按需调用。简单来说，智能体就像一个「懂行的虚拟同事」，你告诉它目标，它负责拆解并执行。

智能体的典型应用场景包括：

• 代码审查：自动检查提交的代码是否符合规范。
• 单元测试生成：为指定函数自动生成测试用例。
• 文档生成：根据代码注释生成 README 或接口文档。
• 重构辅助：按指定模式批量重构代码。

3. 创建第一个智能体

在 TRAE 中，创建智能体通常有两种方式：通过界面引导创建，或通过配置文件声明。下面分别介绍。

3.1 通过界面创建

打开 TRAE 的智能体管理面板，点击「新建智能体」，填写名称、描述和系统提示词即可。系统提示词是智能体的「人设」，决定了它的行为方式。

例如，创建一个「代码审查助手」：

名称：code-reviewer
描述：负责对代码变更进行规范性审查
系统提示词：
你是一名资深代码审查专家。请从可读性、性能、安全性三个维度审查代码，
并给出具体的修改建议。输出格式为 Markdown 列表，每条建议包含：
- 问题位置（文件:行号）
- 问题描述
- 修改建议
- 严重程度（高/中/低）

3.2 通过配置文件创建

TRAE 支持在项目根目录下使用配置文件声明智能体，便于团队共享和版本管理。配置文件通常为 .trae/agents/ 目录下的 YAML 文件。

# .trae/agents/code-reviewer.yaml
name: code-reviewer
description: 代码审查助手
version: 1.0.0
prompt: |
  你是一名资深代码审查专家。请从可读性、性能、安全性三个维度审查代码，
  并给出具体的修改建议。
tools:
  - read_file
  - list_files
  - git_diff
model: claude-sonnet-4-5
temperature: 0.2

配置文件中的 tools 字段声明了该智能体可以调用的工具，model 指定使用的模型，temperature 控制输出的随机性。

4. 智能体的核心配置详解

一个完整的智能体配置包含多个关键字段，理解它们有助于设计出更高效的智能体。

4.1 系统提示词（Prompt）

系统提示词是智能体的灵魂。好的提示词应当包含角色定义、任务目标、约束条件和输出格式。下面是一个「单元测试生成器」的提示词示例：

你是一名精通单元测试的工程师。给定一个函数源码，请完成以下任务：
1. 分析函数的输入、输出和边界条件；
2. 使用 JUnit 5 编写覆盖正常路径、异常路径和边界条件的测试用例；
3. 测试类命名规范：原类名 + Test 后缀；
4. 每个测试方法使用 @DisplayName 描述测试场景；
5. 输出完整的 Java 代码，不要省略 import 语句。

4.2 工具调用（Tools）

智能体可以调用 TRAE 提供的工具来读取文件、执行命令、搜索代码等。合理配置工具权限可以平衡能力与安全。

tools:
  - read_file        # 读取文件内容
  - write_file       # 写入文件
  - list_files       # 列出目录文件
  - run_command      # 执行终端命令
  - search_symbol    # 搜索代码符号
  - git_operations   # Git 操作

4.3 模型与参数

不同任务适合不同的模型和参数。代码生成类任务通常使用较低的温度以获得确定性输出，而创意类任务可以使用较高的温度。

model: claude-sonnet-4-5
temperature: 0.1
max_tokens: 4096
top_p: 0.9

5. 在项目中调用智能体

创建好智能体后，可以在 TRAE 的对话窗口中通过 @智能体名称 的方式调用。例如：

@code-reviewer 请审查 src/main/java/com/example/UserService.java 的最近变更

智能体收到指令后，会按照其系统提示词定义的流程执行任务，并返回结构化结果。

5.1 在代码中调用智能体 API

除了交互式调用，TRAE 还提供了 API 接口，允许开发者将智能体集成到自己的工具链中。下面是一个使用 Python 调用智能体 API 的示例：

import requests
API_URL = "https://api.trae.ai/v1/agents/run"
API_KEY = "your-api-key"
def run_agent(agent_name: str, task: str) -> str:
"""调用 TRAE 智能体执行任务"""
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
payload = {
"agent": agent_name,
"task": task,
"parameters": {
"temperature": 0.2,
"max_tokens": 2048
}
}
response = requests.post(API_URL, json=payload, headers=headers)
response.raise_for_status()
return response.json()["result"]
if name == "main":
result = run_agent("code-reviewer", "审查 UserService.java 的最近变更")
print(result)

5.2 使用 Node.js 调用智能体 API

const axios = require("axios");
const API_URL = "https://api.trae.ai/v1/agents/run";
const API_KEY = "your-api-key";
async function runAgent(agentName, task) {
const headers = {
Authorization: Bearer ${API_KEY},
"Content-Type": "application/json",
};
const payload = {
agent: agentName,
task: task,
parameters: {
temperature: 0.2,
max_tokens: 2048,
},
};
const response = await axios.post(API_URL, payload, { headers });
return response.data.result;
}
runAgent("code-reviewer", "审查 UserService.java 的最近变更")
.then((result) => console.log(result))
.catch((error) => console.error(error));

6. 智能体的进阶用法

6.1 多智能体协作

复杂任务可以拆分为多个子任务，由不同的智能体协作完成。例如，一个「全栈功能开发」流程可以拆分为：

1. @architect 设计接口和数据模型
2. @backend-dev 实现后端接口
3. @frontend-dev 实现前端页面
4. @code-reviewer 审查全部代码
5. @doc-writer 生成接口文档

通过合理的任务编排，多个智能体可以像团队一样流水线作业。

6.2 智能体上下文注入

在调用智能体时，可以通过参数注入项目上下文，帮助智能体更好地理解任务。下面是一个携带上下文的调用示例：

payload = {
    "agent": "backend-dev",
    "task": "实现用户注册接口",
    "context": {
        "project_language": "Java 17",
        "framework": "Spring Boot 3.2",
        "database": "MySQL 8.0",
        "code_style": "项目遵循阿里巴巴编码规范",
        "related_files": [
            "src/main/java/com/example/controller/UserController.java",
            "src/main/java/com/example/service/UserService.java"
        ]
    }
}

6.3 智能体输出结构化数据

通过提示词约束，可以让智能体输出 JSON 等结构化数据，便于程序化处理。下面是一个输出 JSON 的提示词示例：

请分析以下代码的复杂度，并严格按如下 JSON 格式输出，不要输出其他内容：
{
  "cyclomatic_complexity": 数字,
  "lines_of_code": 数字,
  "potential_issues": ["问题1", "问题2"],
  "suggestions": ["建议1", "建议2"]
}

7. 管理智能体

7.1 查看与编辑

在 TRAE 的智能体管理面板中，可以查看所有已创建的智能体，包括名称、描述、版本和最近使用时间。点击任意智能体即可编辑其配置。

7.2 版本管理

智能体配置支持版本管理。每次修改保存后都会生成新版本，可以随时回滚到历史版本。这在团队协作中尤为重要，可以避免配置变更带来的意外影响。

# 查看智能体版本历史
trae agent history code-reviewer
回滚到指定版本
trae agent rollback code-reviewer --version 1.2.0
导出智能体配置
trae agent export code-reviewer --output ./backup/code-reviewer.yaml

7.3 导入与导出

智能体配置可以导出为 YAML 文件，也可以从 YAML 文件导入。这方便了智能体在不同项目、不同机器之间的迁移和共享。

# 导入智能体配置
trae agent import ./configs/my-agent.yaml
批量导出所有智能体
trae agent export-all --output ./backup/agents/

7.4 删除与禁用

对于不再使用的智能体，可以将其禁用或删除。禁用后智能体不再出现在调用列表中，但配置仍然保留；删除则会彻底移除配置。

8. 实战：构建一个完整的代码审查智能体

下面我们综合运用前面所学，构建一个完整的「代码审查智能体」，并演示其使用效果。

8.1 定义智能体配置

# .trae/agents/code-reviewer.yaml
name: code-reviewer
description: 全面的代码审查助手，覆盖规范、性能、安全三个维度
version: 2.0.0
prompt: |
  你是一名资深代码审查专家，拥有 10 年以上的大型项目经验。
  请对用户提供的代码变更进行审查，并从以下三个维度给出建议：
  1. 代码规范：命名、格式、注释是否符合团队规范；
  2. 性能：是否存在明显的性能瓶颈，如不必要的循环、重复查询等；
  3. 安全：是否存在注入、越权、敏感信息泄露等安全隐患。
输出格式要求：
使用 Markdown 列表；
每条建议包含：问题位置（文件:行号）、问题描述、修改建议、严重程度；
严重程度分为：高、中、低；
如果没有问题，输出「未发现明显问题」。
tools:
read_file
list_files
git_diff
search_symbol
model: claude-sonnet-4-5
temperature: 0.1
max_tokens: 4096

8.2 编写调用脚本

import requests
import json
API_URL = "https://api.trae.ai/v1/agents/run"
API_KEY = "your-api-key"
def review_code(agent_name: str, file_path: str, diff_content: str) -> dict:
"""调用代码审查智能体"""
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
payload = {
"agent": agent_name,
"task": f"请审查文件 {file_path} 的以下变更：\n{diff_content}",
"context": {
"project_language": "Java 17",
"framework": "Spring Boot 3.2",
"code_style": "阿里巴巴编码规范"
}
}
response = requests.post(API_URL, json=payload, headers=headers)
response.raise_for_status()
return response.json()
if name == "main":
# 模拟一段代码变更
diff = """
public User getUserById(Long id) {
String sql = "SELECT * FROM user WHERE id = " + id;
return jdbcTemplate.queryForObject(sql, User.class);
}
"""
result = review_code("code-reviewer", "UserDao.java", diff)
print(json.dumps(result, ensure_ascii=False, indent=2))

8.3 运行结果示例

执行上述脚本后，智能体会返回结构化的审查结果，类似如下：

审查结果：
- 问题位置：UserDao.java:2
  问题描述：使用字符串拼接构造 SQL，存在 SQL 注入风险。
  修改建议：使用 PreparedStatement 或 JdbcTemplate 的参数占位符。
  严重程度：高
问题位置：UserDao.java:2
问题描述：SQL 语句未使用参数化查询，可读性较差。
修改建议：使用 ? 占位符并传入参数。
严重程度：中

9. 最佳实践与注意事项

• 提示词要具体：明确的角色、任务、约束和输出格式，能显著提升智能体的输出质量。
• 控制工具权限：只授予智能体完成任务所必需的工具权限，降低误操作风险。
• 合理设置参数：代码生成类任务使用低温度（0.1-0.3），创意类任务可适当提高。
• 善用上下文注入：提供项目语言、框架、相关文件等上下文，帮助智能体更准确地理解任务。
• 定期维护版本：智能体配置会随项目演进而变化，及时更新并管理版本。
• 注意敏感信息：不要在提示词或上下文中写入密钥、密码等敏感信息。

10. 总结

本文详细介绍了 TRAE 中智能体的创建、配置、调用和管理方法，并提供了丰富的代码实例。通过合理设计提示词、配置工具权限、注入项目上下文，开发者可以打造出高效、可靠的智能体，将重复性工作自动化，把精力集中在更有创造性的任务上。希望本文能帮助你快速上手 TRAE 智能体，提升开发效率。