前言
在上一篇文章中，我们介绍了如何基于 4sapi 快速搭建一个基础的多模型 AI Agent。随着 AI 技术在企业中的深入应用，单一 Agent 已经无法满足复杂业务场景的需求。多智能体协作系统正在成为企业级 AI 应用的标准架构，通过多个专业化 Agent 的分工协作，能够处理比单一 Agent 复杂 10 倍以上的任务。
本文将深入讲解企业级 AI Agent 工作流的设计与实现，基于 4sapi 统一接口构建一个包含任务规划、代码生成、测试验证、文档编写四个专业化 Agent 的完整协作系统。所有代码均可直接运行，你可以基于此架构快速扩展出适合自己业务场景的智能体系统。
一、企业级多 Agent 系统架构设计
1.1 传统单一 Agent 的局限性
单一 Agent 在处理复杂任务时存在以下明显缺陷：
- 能力边界有限：一个模型无法同时精通所有领域
- 上下文窗口限制：无法处理超长任务链
- 错误累积：一步出错会导致后续所有步骤偏离
- 可扩展性差：新增功能需要修改核心代码
1.2 多 Agent 协作系统核心架构
我们采用 "主从式 + 流水线" 混合架构，包含一个主控 Agent 和多个专业化执行 Agent：
plaintext
用户请求 → 主控Agent → 任务拆解与分配 → 执行Agent池 → 结果汇总 → 用户响应
↑ ↓
└──── 状态监控 ──────┘
各角色职责：
- 主控 Agent：基于 GPT-5.5，负责任务理解、拆解、分配和结果整合
- 代码生成 Agent：基于 GPT-5.5，专注于高质量代码编写
- 测试验证 Agent：基于 Claude 4.7，负责代码审查和测试用例生成
- 文档编写 Agent：基于 Gemini 3.1 Pro，擅长技术文档和图表生成
- 工具调用 Agent：通用工具执行器，支持网络搜索、文件操作等
1.3 4sapi 在多 Agent 系统中的核心价值
- 统一接口：所有 Agent 使用相同的 OpenAI 协议调用不同模型
- 模型即插即用：随时替换或升级单个 Agent 的底层模型
- 统一监控：在一个控制台查看所有 Agent 的调用统计和费用
- 高并发支持：同时支持数十个 Agent 并行执行任务
二、核心基础设施实现
2.1 环境配置与基础类
首先创建项目结构和基础配置：
bash
运行
mkdir multi-agent-system
cd multi-agent-system
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install openai python-dotenv tenacity pydantic loguru
创建config.py配置文件：
python
运行
from pydantic import BaseSettings
class Settings(BaseSettings):
API_KEY: str
BASE_URL: str = "https://4sapi.com/v1"
DEFAULT_MODEL: str = "gpt-5.5"
TEMPERATURE: float = 0.7
MAX_TOKENS: int = 4096
TIMEOUT: int = 60
class Config:
env_file = ".env"
settings = Settings()
创建.env文件：
env
API_KEY=sk-你的4sapi密钥
创建base_agent.py基础 Agent 类：
python
运行
from openai import OpenAI
from loguru import logger
from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
from config import settings
class BaseAgent:
def __init__(self, name: str, model: str = None, system_prompt: str = ""):
self.name = name
self.model = model or settings.DEFAULT_MODEL
self.system_prompt = system_prompt
self.client = OpenAI(
api_key=settings.API_KEY,
base_url=settings.BASE_URL,
timeout=settings.TIMEOUT
)
@retry(
stop=stop_after_attempt(3),
wait=wait_exponential(multiplier=1, min=2, max=10),
retry=retry_if_exception_type((Exception,))
)
def call(self, messages: list, **kwargs) -> str:
"""调用模型接口"""
try:
logger.info(f"[{self.name}] 调用模型: {self.model}")
# 插入系统提示词
if self.system_prompt and not any(msg["role"] == "system" for msg in messages):
messages.insert(0, {"role": "system", "content": self.system_prompt})
response = self.client.chat.completions.create(
model=self.model,
messages=messages,
temperature=kwargs.get("temperature", settings.TEMPERATURE),
max_tokens=kwargs.get("max_tokens", settings.MAX_TOKENS),
stream=kwargs.get("stream", False)
)
result = response.choices[0].message.content
logger.info(f"[{self.name}] 调用成功，输出长度: {len(result)}")
return result
except Exception as e:
logger.error(f"[{self.name}] 调用失败: {str(e)}")
raise
2.2 消息总线与状态管理
实现一个简单的消息总线，用于 Agent 之间的通信和状态共享：
python
运行
from typing import Dict, Any, List
from dataclasses import dataclass
from datetime import datetime
import uuid
@dataclass
class Task:
task_id: str
name: str
description: str
assigned_to: str
status: str = "pending" # pending, running, completed, failed
result: Any = None
created_at: datetime = datetime.now()
updated_at: datetime = datetime.now()
class MessageBus:
def __init__(self):
self.tasks: Dict[str, Task] = {}
self.results: Dict[str, Any] = {}
def create_task(self, name: str, description: str, assigned_to: str) -> str:
"""创建新任务"""
task_id = str(uuid.uuid4())
task = Task(
task_id=task_id,
name=name,
description=description,
assigned_to=assigned_to
)
self.tasks[task_id] = task
return task_id
def update_task_status(self, task_id: str, status: str, result: Any = None):
"""更新任务状态"""
if task_id not in self.tasks:
raise ValueError(f"任务不存在: {task_id}")
task = self.tasks[task_id]
task.status = status
task.result = result
task.updated_at = datetime.now()
if status == "completed" and result is not None:
self.results[task_id] = result
def get_task(self, task_id: str) -> Task:
"""获取任务信息"""
return self.tasks.get(task_id)
def get_all_completed_results(self) -> Dict[str, Any]:
"""获取所有已完成任务的结果"""
return {task.name: task.result for task in self.tasks.values() if task.status == "completed"}
三、专业化 Agent 实现
3.1 主控 Agent
主控 Agent 是整个系统的大脑，负责任务拆解和协调：
python
运行
from base_agent import BaseAgent
from message_bus import MessageBus
import json
class MasterAgent(BaseAgent):
def __init__(self):
super().__init__(
name="主控Agent",
model="gpt-5.5",
system_prompt="""
你是一个专业的任务拆解和协调专家。你的职责是：
1. 将用户的复杂需求拆解为多个可执行的子任务
2. 为每个子任务分配合适的执行Agent
3. 监控任务执行进度
4. 整合所有子任务的结果，生成最终响应
可用的执行Agent：
- code_agent: 代码生成专家，擅长编写高质量、可运行的代码
- test_agent: 测试验证专家，负责代码审查和测试用例编写
- doc_agent: 文档编写专家，擅长技术文档和使用说明
请严格按照JSON格式输出任务拆解结果，格式如下：
{
"tasks": [
{
"name": "任务名称",
"description": "详细的任务描述",
"assigned_to": "执行Agent名称"
}
]
}
"""
)
def decompose_task(self, user_query: str) -> list:
"""拆解用户任务"""
messages = [
{"role": "user", "content": f"请将以下需求拆解为可执行的子任务：\n{user_query}"}
]
result = self.call(messages)
# 解析JSON结果
try:
# 提取JSON部分（处理可能的markdown格式）
if "```json" in result:
json_str = result.split("```json")[1].split("```")[0].strip()
else:
json_str = result.strip()
task_data = json.loads(json_str)
return task_data.get("tasks", [])
except Exception as e:
logger.error(f"任务拆解失败: {str(e)}")
logger.error(f"原始输出: {result}")
raise
def orchestrate(self, user_query: str, message_bus: MessageBus) -> str:
"""执行任务编排"""
logger.info("开始任务拆解...")
tasks = self.decompose_task(user_query)
if not tasks:
return "无法拆解任务，请重新描述你的需求。"
logger.info(f"拆解为 {len(tasks)} 个子任务")
# 创建任务
task_ids = []
for task in tasks:
task_id = message_bus.create_task(
name=task["name"],
description=task["description"],
assigned_to=task["assigned_to"]
)
task_ids.append(task_id)
return task_ids
3.2 代码生成 Agent
python
运行
class CodeAgent(BaseAgent):
def __init__(self):
super().__init__(
name="代码生成Agent",
model="gpt-5.5",
system_prompt="""
你是一位资深的软件工程师，擅长编写高质量、可维护、可运行的代码。
请遵循以下原则：
1. 代码必须完整可运行，包含必要的导入和依赖说明
2. 添加清晰的注释和文档字符串
3. 遵循Python PEP8编码规范
4. 处理可能的异常情况
5. 输出代码时使用```python和```包裹
"""
)
def execute(self, task_description: str) -> dict:
"""执行代码生成任务"""
messages = [
{"role": "user", "content": task_description}
]
code = self.call(messages)
return {
"code": code,
"language": "python",
"description": "根据需求生成的完整代码"
}
3.3 测试验证 Agent
python
运行
class TestAgent(BaseAgent):
def __init__(self):
super().__init__(
name="测试验证Agent",
model="claude-4-7-opus",
system_prompt="""
你是一位专业的软件测试工程师，擅长代码审查和测试用例设计。
请对提供的代码进行以下检查：
1. 语法错误和逻辑错误
2. 安全漏洞
3. 性能问题
4. 代码规范
5. 编写对应的单元测试用例
输出格式：
## 代码审查报告
### 发现的问题
- 问题1
- 问题2
### 改进建议
- 建议1
- 建议2
## 单元测试代码
```python
# 测试代码
""")
def execute (self, code: str) -> dict:"""执行测试验证任务"""messages = [{"role": "user", "content": f" 请审查以下代码并编写测试用例：\npython\n{code}\n"}]
review_result = self.call(messages)return {"review_report": review_result,"code_under_test": code}
plaintext
### 3.4 文档编写Agent
```python
class DocAgent(BaseAgent):
def __init__(self):
super().__init__(
name="文档编写Agent",
model="gemini-3.1-pro",
system_prompt="""
你是一位专业的技术文档工程师，擅长编写清晰、易懂的技术文档。
请根据提供的代码和需求，编写完整的技术文档，包含以下部分：
1. 功能介绍
2. 安装依赖
3. 使用方法
4. API说明
5. 注意事项
使用Markdown格式编写，确保结构清晰，易于阅读。
"""
)
def execute(self, code: str, requirements: str) -> dict:
"""执行文档编写任务"""
messages = [
{"role": "user", "content": f"需求：{requirements}\n\n代码：\n```python\n{code}\n```\n\n请编写完整的技术文档。"}
]
documentation = self.call(messages)
return {
"documentation": documentation,
"requirements": requirements
}
四、完整工作流实现
4.1 Agent 工厂与执行器
创建agent_factory.py：
python
运行
from typing import Dict, Type
from base_agent import BaseAgent
from master_agent import MasterAgent
from code_agent import CodeAgent
from test_agent import TestAgent
from doc_agent import DocAgent
class AgentFactory:
_agents: Dict[str, Type[BaseAgent]] = {
"master": MasterAgent,
"code_agent": CodeAgent,
"test_agent": TestAgent,
"doc_agent": DocAgent
}
@classmethod
def create_agent(cls, agent_type: str) -> BaseAgent:
"""创建指定类型的Agent"""
if agent_type not in cls._agents:
raise ValueError(f"不支持的Agent类型: {agent_type}")
return cls._agents[agent_type]()
@classmethod
def register_agent(cls, agent_type: str, agent_class: Type[BaseAgent]):
"""注册新的Agent类型"""
cls._agents[agent_type] = agent_class
创建workflow_executor.py：
python
运行
from loguru import logger
from message_bus import MessageBus
from agent_factory import AgentFactory
class WorkflowExecutor:
def __init__(self):
self.message_bus = MessageBus()
self.agent_factory = AgentFactory()
self.master_agent = self.agent_factory.create_agent("master")
def run(self, user_query: str) -> dict:
"""执行完整工作流"""
logger.info(f"开始处理用户需求: {user_query}")
# 步骤1：任务拆解
task_ids = self.master_agent.orchestrate(user_query, self.message_bus)
if not task_ids:
return {"status": "failed", "error": "任务拆解失败"}
# 步骤2：执行所有任务
for task_id in task_ids:
task = self.message_bus.get_task(task_id)
logger.info(f"执行任务: {task.name} (分配给: {task.assigned_to})")
try:
# 更新任务状态为运行中
self.message_bus.update_task_status(task_id, "running")
# 创建对应的Agent并执行任务
agent = self.agent_factory.create_agent(task.assigned_to)
# 根据任务类型传递不同的参数
if task.assigned_to == "code_agent":
result = agent.execute(task.description)
elif task.assigned_to == "test_agent":
# 获取代码生成任务的结果
code_task = next((t for t in self.message_bus.tasks.values() if t.assigned_to == "code_agent"), None)
if code_task and code_task.status == "completed":
code = code_task.result["code"]
result = agent.execute(code)
else:
raise Exception("代码生成任务未完成，无法进行测试")
elif task.assigned_to == "doc_agent":
# 获取代码生成任务的结果
code_task = next((t for t in self.message_bus.tasks.values() if t.assigned_to == "code_agent"), None)
if code_task and code_task.status == "completed":
code = code_task.result["code"]
result = agent.execute(code, user_query)
else:
raise Exception("代码生成任务未完成，无法编写文档")
else:
result = agent.execute(task.description)
# 更新任务状态为完成
self.message_bus.update_task_status(task_id, "completed", result)
logger.info(f"任务完成: {task.name}")
except Exception as e:
logger.error(f"任务失败: {task.name}, 错误: {str(e)}")
self.message_bus.update_task_status(task_id, "failed", str(e))
# 步骤3：结果整合
completed_results = self.message_bus.get_all_completed_results()
failed_tasks = [t.name for t in self.message_bus.tasks.values() if t.status == "failed"]
if failed_tasks:
return {
"status": "partial_success",
"completed_results": completed_results,
"failed_tasks": failed_tasks,
"message": "部分任务执行失败"
}
else:
return {
"status": "success",
"results": completed_results,
"message": "所有任务执行成功"
}
4.2 主程序入口
创建main.py：
python
运行
from workflow_executor import WorkflowExecutor
import sys
def main():
if len(sys.argv) < 2:
print("使用方法: python main.py <你的需求>")
print("示例: python main.py '编写一个简单的计算器程序，支持加减乘除运算'")
return
user_query = " ".join(sys.argv[1:])
executor = WorkflowExecutor()
result = executor.run(user_query)
print("\n" + "="*50)
print("执行结果:")
print("="*50)
if result["status"] == "success":
print("✅ 所有任务执行成功！")
# 输出代码
if "代码生成" in result["results"]:
print("\n📝 生成的代码:")
print(result["results"]["代码生成"]["code"])
# 输出测试报告
if "测试验证" in result["results"]:
print("\n🔍 测试报告:")
print(result["results"]["测试验证"]["review_report"])
# 输出文档
if "文档编写" in result["results"]:
print("\n📚 技术文档:")
print(result["results"]["文档编写"]["documentation"])
elif result["status"] == "partial_success":
print("⚠️ 部分任务执行失败")
print(f"失败的任务: {', '.join(result['failed_tasks'])}")
print("\n已完成的结果:")
for name, res in result["completed_results"].items():
print(f"\n{name}:")
print(res)
else:
print(f"❌ 执行失败: {result['error']}")
if __name__ == "__main__":
main()
五、实战演示：构建一个 RESTful API 服务
现在我们来测试这个多 Agent 系统，让它为我们构建一个完整的 RESTful API 服务：
bash
运行
python main.py "编写一个基于FastAPI的用户管理RESTful API，包含用户的增删改查功能，使用SQLite数据库，添加JWT认证"
系统执行流程：
-
主控 Agent 将需求拆解为 3 个子任务：
- 代码生成：编写 FastAPI 应用代码
- 测试验证：审查代码并编写测试用例
- 文档编写：生成 API 文档和使用说明
-
代码生成 Agent 基于 GPT-5.5 生成完整的 FastAPI 代码，包含：
- 数据库模型定义
- 用户 CRUD 接口
- JWT 认证实现
- 错误处理
-
测试验证 Agent 基于 Claude 4.7 对代码进行审查：
- 发现潜在的安全问题
- 提出性能优化建议
- 编写完整的 pytest 测试用例
-
文档编写 Agent 基于 Gemini 3.1 Pro 生成详细文档：
- 功能介绍
- 安装部署步骤
- API 接口说明
- 示例请求和响应
六、生产环境优化建议
6.1 性能优化
- 异步支持：将所有 Agent 调用改为异步，支持并行执行
- 结果缓存：使用 Redis 缓存常见任务的结果
- 模型降级：当高优先级模型不可用时自动降级到备用模型
- 批量处理：对于可以批量处理的任务使用批量 API
6.2 监控与可观测性
- 集成 Prometheus：监控 API 调用次数、延迟和错误率
- 日志聚合：使用 ELK 栈收集所有 Agent 的日志
- 链路追踪：为每个任务添加唯一 ID，实现全链路追踪
- 告警系统：当任务失败率超过阈值时发送告警
6.3 安全与合规
- 输入验证：对所有用户输入进行严格验证
- 权限控制：为不同用户设置不同的 Agent 访问权限
- 数据脱敏：对敏感数据进行脱敏处理
- 审计日志：记录所有用户操作和 Agent 调用
七、总结与扩展
本文详细介绍了如何基于 4sapi 构建一个企业级的多 Agent 协作系统。通过将复杂任务拆解为多个专业化 Agent 的协作，我们能够处理比单一 Agent 复杂得多的业务场景。
4sapi 的核心优势在这个系统中得到了充分体现：
- 我们只用了一套 OpenAI SDK 就调用了 GPT-5.5、Claude 4.7 和 Gemini 3.1 Pro 三个不同厂商的模型
- 每个 Agent 可以独立选择最适合自己的模型，无需修改任何底层代码
- 统一的监控和计费系统大大降低了运维成本
- 国内直连的高速网络确保了系统的响应速度
