---
outline: deep
---

# 创建你的 AI Agent

欢迎使用 Mythra Agent Studio！本指南将帮助你轻松创建和管理属于你自己的 AI Agent（智能代理）。


## 什么是 AI Agent？

简单来说，AI Agent 就是一个"定制化的 AI 助手"。你可以根据自己的需求，让这个助手拥有特定的"性格"和"能力"：

- 想要一个专业的代码审查助手？没问题！
- 想要一个创意写作伙伴？轻松搞定！
- 想要一个数据分析专家？完全可以！

即使你对 AI 技术不太了解，也能通过本系统轻松创建自己的 AI Agent。

## Agent 列表页面

打开 Agent Manager，你首先会看到 **Agent 列表页面**。这里展示了你已经创建的所有 AI Agent。

### 页面功能一览

| 功能 | 说明 |
|------|------|
| **创建 Agent** | 点击右上角的「Create Agent」按钮，开始创建新的 AI Agent |
| **启用/禁用** | 通过每个 Agent 右侧的开关，可以快速启用或禁用该 Agent |
| **编辑** | 点击「⋯」菜单中的「Edit」，修改 Agent 的配置 |
| **删除** | 点击「⋯」菜单中的「Delete」，删除不需要的 Agent |

> 💡 **小贴士**：禁用的 Agent 不会被删除，只是暂时停用，随时可以重新启用。


## 创建你的第一个 Agent

点击「Create Agent」按钮后，你将进入 Agent 创建页面。下面我们详细介绍每个字段的填写方法。

### 基本信息

#### ID（标识符）

- **这是什么？** Agent 的唯一身份标识，类似于用户名。
- **如何填写？** 只能使用英文字母、数字、连字符（-）和下划线（_），**必须以字母开头**。
- **是否必填？** ✅ 必填
- **示例**：`my-assistant`、`code_reviewer`、`DataAnalyzer`

> ⚠️ **注意**：ID 一旦创建就无法修改，请谨慎填写。

#### Name（名称）

- **这是什么？** Agent 的显示名称，会展示在界面上。
- **如何填写？** 可以使用任何语言，建议起一个容易理解的名字。
- **是否必填？** ✅ 必填
- **示例**：`我的助手`、`代码审查专家`、`数据分析助手`

#### Version（版本）

- **这是什么？** Agent 的版本号，方便你追踪 Agent 的更新。
- **如何填写？** 建议使用「主版本号.次版本号.修订号」的格式。
- **是否必填？** ✅ 必填（默认为 `1.0.0`）
- **示例**：`1.0.0`、`2.1.3`

#### Icon（图标）

- **这是什么？** Agent 的头像图标，让你的 Agent 更有个性。
- **如何填写？** 点击上传按钮，选择一张图片即可。
- **是否必填？** ❌ 可选
- **支持格式**：PNG、JPG、GIF、SVG、WebP
- **大小限制**：不超过 500KB

---

### Agent 类型

这是最重要的选择！我们提供两种 Agent 类型，适合不同需求的用户：

#### 🎯 声明式 AI Agent（Declarative AI Agent）

**适合人群**：所有用户，特别是 AI 新手

**特点**：你只需要用自然语言描述你想要的 Agent"性格"和能力，系统会帮你完成剩下的工作。

**使用场景**：
- 想要一个特定领域的专家助手
- 想要一个有特定说话风格的 AI
- 不想写代码，只想快速创建一个 Agent

#### 🔌 外部 AI Agent（External AI Agent）

**适合人群**：有一定开发能力的工程师

**特点**：你已经在外部服务中实现了 AI Agent，通过 WebSocket 协议接入本系统。

**使用场景**：
- 你已经开发了自己的 AI Agent 服务
- 需要更复杂的自定义逻辑
- 想要使用特定的 AI 模型或框架

> 💡 **提示**：想了解如何开发外部 Agent？请参阅 [开发外部 AI Agent](./develop-external-agent.md) 和 [Agent 消息协议](./agent-message-protocol.md)。


## 声明式 AI Agent 配置详解

选择「Declarative AI Agent」类型后，你需要配置以下内容：

### Base Agent（基础 Agent）

基础 Agent 决定了你的 Agent 拥有哪些"基础能力"：

| 类型 | 说明 | 适合场景 |
|------|------|----------|
| **Chat** | 对话型 Agent，擅长聊天和回答问题，没有额外的工具能力 | 简单问答、日常对话、知识咨询 |
| **Builder** | 功能强大的 Agent，拥有工具调用、文件操作、命令执行等高级能力 | 代码生成、文件处理、自动化任务 |

> 💡 **建议**：如果你不确定该选哪个，可以先选择「Chat」，体验一下基本功能。如果后续需要更强的能力，可以随时修改为「Builder」。

### System Prompt（系统提示词）

这是创建声明式 Agent 的核心！系统提示词就像是给 AI 的"人设说明书"，告诉它：

- 它是谁
- 它应该做什么
- 它应该如何回答问题
- 它有什么特殊要求

#### 系统提示词示例

**示例 1：代码审查助手**

```
你是一位专业的代码审查专家。你的任务是：
1. 仔细阅读用户提交的代码
2. 指出潜在的 bug 和安全问题
3. 提出代码风格和最佳实践方面的建议
4. 给出具体的改进建议

请用友好但专业的语气进行回复，在指出问题的同时也要肯定做得好的地方。
```

**示例 2：创意写作伙伴**

```
你是一位富有创意的写作助手。你的风格是：
- 充满想象力和创意
- 善于使用生动的比喻和描写
- 鼓励用户发挥创造力

当用户分享他们的写作想法时，请给予积极的反馈和建设性的建议。
```

**示例 3：学习辅导老师**

```
你是一位耐心的学习辅导老师。你的教学理念是：
- 循序渐进，从简单到复杂
- 用通俗易懂的语言解释概念
- 通过提问引导学生思考，而不是直接给出答案
- 鼓励学生，增强他们的学习信心

请根据学生的问题调整你的回答难度和详细程度。
```

#### 系统提示词编写技巧

1. **明确角色定位**：告诉 AI 它是谁，比如"你是一位..."、"你是一个..."
2. **列出具体任务**：用编号列表说明 AI 应该做什么
3. **设定回答风格**：说明你希望 AI 用什么样的语气和风格回答
4. **设置边界**：说明 AI 不应该做什么，或者遇到不确定的情况该如何处理
5. **提供示例**：如果可能，给出一些期望的回答示例

> ⚠️ **注意**：系统提示词最多支持 10,000 个字符。


## 外部 AI Agent 配置详解

选择「External AI Agent」类型后，你需要配置以下内容：

### Transport（传输协议）

- **这是什么？** 与外部 Agent 服务通信的协议。
- **当前支持**：WebSocket
- **是否必填？** ✅ 必填（默认为 WebSocket）

### URL（服务地址）

- **这是什么？** 外部 Agent 服务的 WebSocket 连接地址。
- **如何填写？** 填写完整的 WebSocket URL。
- **是否必填？** ✅ 必填
- **示例**：`ws://localhost:8080/agent`、`wss://your-service.com/agent`

> 💡 **提示**：`ws://` 用于本地开发或非加密连接，`wss://` 用于加密的安全连接（推荐用于生产环境）。

> 📖 **相关文档**：想了解如何开发外部 Agent？请参阅 [开发外部 AI Agent](./develop-external-agent.md)。想了解如何开发 CLI Agent？请参阅 [开发 CLI Agent](./develop-cli-agent.md)。详细的通信协议请参阅 [Agent 消息协议](./agent-message-protocol.md)。


## 编辑和删除 Agent

### 编辑 Agent

1. 在 Agent 列表页面，点击 Agent 右侧的「⋯」菜单
2. 选择「Edit」
3. 修改需要更新的字段
4. 点击「Save」保存

> ⚠️ **注意**：Agent 的 ID 一旦创建就无法修改。

### 删除 Agent

1. 在 Agent 列表页面，点击 Agent 右侧的「⋯」菜单
2. 选择「Delete」
3. 在确认对话框中点击「Delete」确认删除

> ⚠️ **警告**：删除操作无法撤销，请谨慎操作！



## 配置文件说明

### 文件存储位置

你创建的所有 AI Agent 都以配置文件的形式保存在当前项目的 `.mythra` 目录下：

```
项目根目录/
└── .mythra/
    ├── agents.json          # Agent 清单文件
    └── agents/              # Agent 配置目录
        ├── my-agent/        # 每个 Agent 有独立的目录
        ├── code-reviewer/
        └── ...
```

### ⚠️ 请勿手动修改

**重要提示**：这些配置文件由系统自动管理，请勿手动修改或删除！

- 手动修改可能导致系统无法正常工作
- 文件格式可能随系统升级而变化
- 请始终使用 Agent Manager 来创建、编辑和删除 Agent

系统会自动维护这些配置文件，确保它们始终处于正确状态。

### 备份与恢复

如果你想备份你的 AI Agents，只需备份整个 `.mythra` 目录即可：

**备份方法**：
1. 复制项目根目录下的 `.mythra` 文件夹
2. 保存到安全的位置（如云盘、外部硬盘等）

**恢复方法**：
1. 将备份的 `.mythra` 文件夹复制回项目根目录
2. 覆盖原有的 `.mythra` 目录
3. 重新打开 Agent Manager，你的 Agents 就会恢复

> 💡 **建议**：定期备份 `.mythra` 目录，以防意外丢失你的 Agent 配置。


## 常见问题

### Q: 我应该选择哪种 Agent 类型？

**A:** 如果你只是想快速创建一个定制化的 AI 助手，选择「声明式 AI Agent」。如果你是开发者，已经有自己的 AI Agent 服务，选择「外部 AI Agent」。

### Q: 系统提示词应该写多长？

**A:** 没有固定要求，关键是把你的需求说清楚。可以从简单的几句话开始，然后根据实际效果逐步完善。

### Q: Base Agent 选 Chat 还是 Builder？

**A:** 如果你只需要对话功能，选 Chat。如果你需要 Agent 帮你操作文件、执行命令、调用工具等，选 Builder。

### Q: 我可以创建多少个 Agent？

**A:** 目前没有数量限制，你可以根据需要创建任意数量的 Agent。

### Q: Agent 创建后可以修改类型吗？

**A:** 可以。你可以在编辑页面修改 Agent 的类型，但需要注意，修改类型后需要重新配置相关参数。


## 开始使用吧！

现在你已经了解了 Agent Manager 的所有功能，是时候创建你的第一个 AI Agent 了！

记住：
- 🎯 **声明式 Agent** = 写提示词，简单快捷
- 🔌 **外部 Agent** = 接入外部服务，灵活强大

祝你使用愉快！如有任何问题，欢迎随时查阅本指南。