148 lines
4.8 KiB
Markdown
148 lines
4.8 KiB
Markdown
# 智能体开发指南
|
||
|
||
Yuxi 的智能体系统基于 LangGraph 构建，提供了灵活而强大的 Agent 开发能力。通过统一的 `AgentManager`，系统能够自动发现和管理所有智能体，让开发者能够专注于业务逻辑的实现。
|
||
|
||
## 智能体架构
|
||
|
||
### 核心概念
|
||
|
||
系统的智能体架构围绕几个核心组件展开：
|
||
|
||
- **BaseAgent**：所有智能体的基类，定义了统一的接口规范
|
||
- **AgentContext**：智能体的配置上下文，包含模型、提示词、工具等配置
|
||
- **Graph**：LangGraph 图结构，定义智能体的执行流程
|
||
- **Middleware**：中间件系统，用于扩展和定制智能体行为
|
||
|
||
### 自动发现机制
|
||
|
||
智能体采用自动发现模式。在 `backend/package/yuxi/agents/__init__.py` 中，系统会遍历 `backend/package/yuxi/agents` 目录，自动注册所有继承自 `BaseAgent` 的类。这意味着开发者只需要按照规范编写代码，智能体就会自动被系统识别，无需手动配置。
|
||
|
||
仓库预置了几个可以直接使用的智能体示例：
|
||
|
||
- **chatbot**：通用对话智能体，支持动态工具调度
|
||
- **reporter**：报表生成智能体，演示多工具协作
|
||
- **deep_agent**：深度分析智能体，支持复杂推理任务
|
||
|
||
这些示例展示了如何组织代码结构、如何定义上下文、如何组合中间件，新增智能体时可以作为参考。
|
||
|
||
## 创建自定义智能体
|
||
|
||
### 目录结构
|
||
|
||
在 `backend/package/yuxi/agents` 目录下创建新的智能体包，建议保持以下结构：
|
||
|
||
```
|
||
backend/package/yuxi/agents/
|
||
└── my_agent/
|
||
├── __init__.py # 暴露主类
|
||
├── graph.py # Graph 构造逻辑
|
||
└── metadata.toml # 元数据配置（可选）
|
||
```
|
||
|
||
### 基本实现
|
||
|
||
智能体类需要继承 `BaseAgent` 并实现异步的 `get_graph` 方法：
|
||
|
||
```python
|
||
from yuxi.agents.common import BaseAgent
|
||
from langgraph.prebuilt import create_agent
|
||
|
||
class MyAgent(BaseAgent):
|
||
async def get_graph(self, **kwargs):
|
||
# 获取配置上下文
|
||
context = self.get_context()
|
||
|
||
# 获取工具列表
|
||
tools = await get_tools_from_context(context)
|
||
|
||
# 构建 LangGraph 图
|
||
graph = create_agent(
|
||
model=load_chat_model(context.model),
|
||
tools=tools,
|
||
checkpointer=await self._get_checkpointer(),
|
||
)
|
||
|
||
return graph
|
||
```
|
||
|
||
### 能力配置
|
||
|
||
`capabilities` 属性用于声明智能体的前端能力，控制 UI 组件的显示：
|
||
|
||
```python
|
||
class MyAgent(BaseAgent):
|
||
capabilities = ["file_upload", "files", "todo"] # 支持文件上传、文件管理、待办事项
|
||
```
|
||
|
||
**可用能力：**
|
||
|
||
| capability | 说明 | 前端效果 |
|
||
|------------|------|----------|
|
||
| `file_upload` | 文件上传 | 显示上传按钮 |
|
||
| `files` | 文件管理 | 显示文件管理面板 |
|
||
| `todo` | 待办事项 | 显示待办组件 |
|
||
|
||
**示例：**
|
||
|
||
```python
|
||
# 只需要文件上传能力
|
||
capabilities = ["file_upload"]
|
||
|
||
# 需要文件上传和待办事项
|
||
capabilities = ["file_upload", "todo"]
|
||
|
||
# 全部能力
|
||
capabilities = ["file_upload", "files", "todo"]
|
||
```
|
||
|
||
注意：即使启用了能力，也需要在中间件中正确配置对应的处理逻辑，功能才能正常工作。例如启用 `file_upload` 需要配合 `inject_attachment_context` 中间件。
|
||
|
||
### 配置文件
|
||
|
||
可以通过 `metadata.toml` 定义智能体的元数据：
|
||
|
||
```toml
|
||
name = "我的智能体"
|
||
description = "这是一个示例智能体"
|
||
examples = [
|
||
"帮我写一首诗",
|
||
"解释一下量子计算",
|
||
]
|
||
```
|
||
|
||
这些信息会在前端界面展示，帮助用户了解每个智能体的用途。
|
||
|
||
## 相关主题
|
||
|
||
- [上下文配置](./context-config.md) - BaseContext 和自定义配置
|
||
- [工具系统](./tools-system.md) - 工具获取机制和 Skills 集成
|
||
- [中间件系统](./middleware.md) - 中间件开发与使用
|
||
- [MCP 集成](./mcp-integration.md) - MCP 服务器配置
|
||
- [SubAgents 管理](./subagents-management.md) - 子智能体配置、调用链和开发注意事项
|
||
|
||
## 开发建议
|
||
|
||
### 代码组织
|
||
|
||
- 将智能体的核心逻辑放在 `graph.py` 中
|
||
- 复杂的工具逻辑单独放在 `toolkits` 目录下
|
||
- 共享的组件放在 `common` 目录下
|
||
|
||
### 热重载
|
||
|
||
在容器环境中，修改代码后会自动触发热重载。如果需要强制刷新，可以调用：
|
||
|
||
```python
|
||
agent_manager.get_agent(<agent_id>, reload=True)
|
||
```
|
||
|
||
### 调试技巧
|
||
|
||
1. 使用前端的「调试面板」查看详细的请求和响应
|
||
2. 查看后端日志：`docker logs api-dev -f`
|
||
3. 利用 LangGraph 的可视化能力理解图结构
|
||
|
||
---
|
||
|
||
智能体系统的设计目标是让开发者能够快速构建和迭代 AI 应用。通过本文档介绍的概念和示例，你应该能够掌握创建自定义智能体的核心方法。遇到问题时，建议先参考预置智能体的实现，它们涵盖了大多数常见场景。
|