1. 从单兵作战到团队协作为什么你需要一个AI Agent团队如果你还在用ChatGPT或者Claude这类大模型一个人对着对话框问来问去试图让它帮你完成一个稍微复杂点的任务比如写一份完整的市场分析报告、或者开发一个带前后端的小工具那你大概率会感到沮丧。模型要么忘记你十分钟前的要求要么在代码写到一半时突然“失忆”把变量名搞混。这感觉就像你雇了一个能力超强但记性极差、还时不时开小差的超级实习生所有事都得你盯着反而更累了。这就是“单智能体”Single Agent模式的瓶颈。一个AI模型再强大它的“工作记忆”Working Memory和任务拆解能力也是有限的。而“AI Agent团队”Agency-Agents的理念正是为了解决这个问题。它不再是让一个AI大包大揽而是模拟一个真实的项目团队有项目经理Orchestrator Agent负责拆解任务和协调进度有前端工程师Frontend Agent写界面有后端工程师Backend Agent处理逻辑和数据还有测试工程师QA Agent来检查代码质量。每个“Agent”都是一个专门化的AI实例它们各司其职通过一套通信和协作机制共同完成一个复杂目标。最近爆火的Hermes Agent、Agency-Agents框架本质上都是在提供搭建这种“AI团队”的脚手架。它们不是某个具体的大模型而是组织和管理多个AI智能体协同工作的“操作系统”或“中间件”。想象一下你作为人类产品经理只需要向这个“AI团队”下达一个清晰的指令“开发一个用户能上传图片并自动生成描述文字的Web应用”剩下的需求分析、技术选型、代码编写、模块联调、甚至部署脚本都可以由这个自主协作的AI团队来完成。你的角色从“码农”变成了“指挥官”生产力将得到质的飞跃。这篇文章我就以一个实际构建过多个AI Agent应用的经验带你快速上手Agency-Agents这个框架在3分钟内搭建起你的第一个AI开发团队。我们会避开空洞的概念直接进入实战从环境准备、核心配置、到跑通第一个协作任务并分享几个我踩过坑才总结出来的关键技巧。无论你是想探索AI应用开发新范式的开发者还是希望用AI大幅提升工作效率的产品经理或业务人员这篇指南都能给你一条清晰的落地路径。2. Agency-Agents核心架构与快速部署在开始敲代码之前我们必须先理解Agency-Agents框架的基本工作模式。与那些需要你从头编写大量胶水代码的底层Agent SDK不同Agency-Agents追求的是“开箱即用”的团队协作体验。它的核心思想是“角色”Role和“技能”Skill。2.1 核心概念角色、技能与工作流角色Role这就是你的“团队成员”。框架预置了多种角色比如ProductManager、SoftwareArchitect、FullStackDeveloper、QAEngineer等。每个角色都内置了对应的“系统提示词”System Prompt使其行为模式贴近真实的岗位。例如ProductManager会擅长拆解用户故事和定义验收标准而FullStackDeveloper则更关注具体的技术实现。技能Skill这是角色所能执行的具体操作。一个角色可以拥有多个技能。技能可以是基础技能如“分析需求”、“编写Python代码”、“执行Shell命令”。工具调用技能如“调用搜索引擎API”、“访问数据库”、“发送邮件”。自定义技能这是框架最强大的地方你可以将任何函数封装成技能赋予你的AI团队成员。比如封装一个部署到云服务器的函数那么你的DevOpsEngineer角色就能使用“部署到AWS”这个技能。工作流Workflow这是定义团队如何协作的剧本。一个简单的工作流可以是线性的ProductManager接收任务 -SoftwareArchitect设计架构 -FullStackDeveloper编写代码 -QAEngineer进行测试。Agency-Agents允许你定义更复杂的、带条件分支的协作流程。2.2 3分钟极速部署一行命令搭建环境Agency-Agents的安装极其简单这得益于它完善的Python包管理。前提是你已经安装了Python3.8以上和pip。打开你的终端命令行执行以下命令# 1. 安装Agency-Agents核心包 pip install agency-agents # 2. 可选但推荐安装用于Web界面管理的扩展包 pip install agency-agents[web]第一行命令会在1分钟内完成核心框架的安装。第二行命令安装了额外的Web UI依赖它会提供一个本地网页让你能可视化地观察和管理你的AI团队协作过程对于调试和理解内部机制非常有帮助。安装完成后你还需要准备一样东西大模型API密钥。Agency-Agents本身不提供模型它需要连接后端的LLM服务。它支持OpenAI的GPT系列、Anthropic的Claude系列以及任何兼容OpenAI API格式的模型服务如国内的一些大模型平台。提示对于快速实验强烈建议使用OpenAI的GPT-4或GPT-3.5-Turbo它们的指令遵循能力和代码能力在Agency-Agents的预设角色中表现最为稳定。你需要在OpenAI官网获取一个API Key。将你的API Key设置为环境变量这是最安全便捷的方式# 在Linux/Mac的终端中 export OPENAI_API_KEY你的-sk-xxx密钥 # 在Windows的PowerShell中 $env:OPENAI_API_KEY你的-sk-xxx密钥至此你的基础环境已经在3分钟内准备完毕。接下来我们将创建第一个AI团队并让它们开始工作。3. 创建你的第一个AI团队从“Hello World”到协同编程让我们从一个最简单的例子开始创建一个由“产品经理”和“全栈工程师”组成的两人小组目标是生成一个Python版本的“Hello World”网页应用的需求文档和代码。3.1 编写团队组建脚本创建一个名为first_team.py的Python文件输入以下代码import asyncio from agency_agents import Agency, Role, Skill from agency_agents.llms import OpenAIChatLLM # 1. 初始化大模型连接 # 这里使用GPT-3.5-Turbo成本低响应快适合实验 llm OpenAIChatLLM(modelgpt-3.5-turbo) # 2. 创建角色产品经理 product_manager Role( nameAlice, profile一位严谨、注重细节的产品经理擅长将模糊需求转化为清晰的用户故事和功能列表。, llmllm, skills[Skill.ANALYZE_REQUIREMENTS, Skill.WRITE_DOCUMENT] # 使用内置技能 ) # 3. 创建角色全栈工程师 full_stack_engineer Role( nameBob, profile一位经验丰富的全栈工程师精通Python Flask框架和HTML/CSS追求代码简洁高效。, llmllm, skills[Skill.WRITE_CODE, Skill.REVIEW_CODE] ) # 4. 创建智能体机构Agency并将角色加入团队 agency Agency(name我的第一个AI团队) agency.hire(product_manager) agency.hire(full_stack_engineer) # 5. 定义一个异步函数来运行团队任务 async def main(): task 请开发一个简单的Web应用在网页上显示‘Hello, AI Team!’。请先输出需求分析再输出实现代码。 print(f【任务发布】: {task}) print(- * 50) # 将任务分配给产品经理Alice print(【Alice产品经理开始工作...】) pm_result await agency.assign_task(role_nameAlice, tasktask) print(f产品需求文档:\n{pm_result}\n) print(- * 50) # 将产品经理的输出作为输入分配给工程师Bob print(【Bob全栈工程师开始工作...】) dev_task f根据以下产品需求编写完整的Flask应用代码包含一个简单的HTML页面。\n需求{pm_result} code_result await agency.assign_task(role_nameBob, taskdev_task) print(f实现代码:\n{code_result}) # 运行主函数 if __name__ __main__: asyncio.run(main())代码解读与避坑点OpenAIChatLLM这是连接LLM的桥梁。如果你用的是Claude可以换成AnthropicLLM。model参数指定具体模型版本。Role的profile这是关键不要只用默认值。花一两句话详细描述角色的性格和专业领域能极大提升该Agent在专业任务上的表现。比如给工程师加上“注重代码可读性和错误处理”他生成的代码就会包含try...except块。Skill.ANALYZE_REQUIREMENTS这些是框架内置的通用技能。你可以在官方文档找到完整的技能列表。在后续进阶中我们会学习创建自定义技能。agency.assign_task这是向特定角色分派任务的核心方法。注意我们使用了await因为Agent的思考过程是异步的。运行这个脚本python first_team.py你会看到控制台依次输出产品经理Alice生成的需求文档可能包含目标用户、功能点、非功能需求等和工程师Bob生成的完整Flask应用代码包含app.py和templates/index.html。一个简单的协作流程就跑通了。3.2 启动Web UI可视化观察协作刚才的协作是在后台发生的。要更直观地看到对话和思考过程我们可以启动Web UI。在同一个目录下创建另一个文件run_web.pyfrom agency_agents import Agency from agency_agents.llms import OpenAIChatLLM from agency_agents.web import run_web_app llm OpenAIChatLLM(modelgpt-3.5-turbo) agency Agency(name可视化团队) # 这里可以复用或重新创建角色并加入到agency中 # ... # 运行Web应用默认在 http://localhost:8501 访问 run_web_app(agency)运行python run_web.py然后在浏览器打开http://localhost:8501。你可以在这个界面中直接向某个角色发送消息也能看到角色之间为了完成任务而自动产生的内部对话这对于调试复杂的多步协作至关重要。4. 实战进阶构建能真正“干活”的自定义技能团队内置的通用技能只能完成基础信息处理。要让AI团队真正替代部分开发工作必须为其装备“手脚”——也就是自定义技能。我们来实现一个经典场景让AI团队自动创建一个Git仓库并将生成的代码提交上去。4.1 创建自定义技能Git操作我们将创建一个GitSkill类封装几个常用的Git命令。import subprocess import os from agency_agents import Skill from typing import Dict, Any class GitSkill(Skill): 自定义技能Git仓库管理 def __init__(self, workspace_path: str ./projects): super().__init__() self.workspace_path workspace_path os.makedirs(self.workspace_path, exist_okTrue) # 确保工作目录存在 Skill.action(description初始化一个新的Git仓库) async def init_repo(self, repo_name: str) - Dict[str, Any]: 在workspace_path下创建并初始化一个Git仓库 repo_path os.path.join(self.workspace_path, repo_name) if os.path.exists(repo_path): return {status: error, message: f目录 {repo_path} 已存在} os.makedirs(repo_path) try: subprocess.run([git, init], cwdrepo_path, checkTrue, capture_outputTrue, textTrue) return {status: success, message: f仓库 {repo_name} 初始化成功, path: repo_path} except subprocess.CalledProcessError as e: return {status: error, message: fGit初始化失败: {e.stderr}} Skill.action(description将文件添加到Git暂存区并提交) async def commit_code(self, repo_name: str, file_path: str, commit_message: str) - Dict[str, Any]: 提交指定文件到仓库 repo_path os.path.join(self.workspace_path, repo_name) if not os.path.exists(os.path.join(repo_path, .git)): return {status: error, message: 不是一个Git仓库} full_file_path os.path.join(repo_path, file_path) if not os.path.exists(full_file_path): return {status: error, message: f文件 {file_path} 不存在} try: # 添加文件 subprocess.run([git, add, file_path], cwdrepo_path, checkTrue, capture_outputTrue, textTrue) # 提交 result subprocess.run([git, commit, -m, commit_message], cwdrepo_path, checkTrue, capture_outputTrue, textTrue) return {status: success, message: f提交成功: {commit_message}, output: result.stdout} except subprocess.CalledProcessError as e: return {status: error, message: fGit操作失败: {e.stderr}}关键点解析Skill.action装饰器这是将普通类方法声明为Agent可调用技能的关键。description参数非常重要Agent会根据这个描述来决定何时使用该技能。异步方法技能方法必须是async的以兼容Agency-Agents的异步运行时。返回值标准化建议返回一个结构化的字典如包含status,message,data这样在后续的工作流中便于其他Agent解析结果。4.2 组建“开发-运维”一体化团队现在我们创建一个拥有GitSkill的DevOpsEngineer角色并与之前的FullStackDeveloper协作。import asyncio from agency_agents import Agency, Role from agency_agents.llms import OpenAIChatLLM # 假设上面的GitSkill类定义在同一个文件或已导入 async def advanced_team_demo(): llm OpenAIChatLLM(modelgpt-4) # 使用能力更强的GPT-4进行复杂任务 # 创建开发工程师 developer Role( nameCharlie, profilePython开发专家擅长Flask/Django代码规范清晰。, llmllm, skills[Skill.WRITE_CODE] ) # 创建运维工程师并赋予其Git技能 git_skill GitSkill(workspace_path./ai_projects) devops Role( nameDavid, profileDevOps工程师负责代码仓库管理、CI/CD和部署。, llmllm, skills[git_skill] # 将自定义技能实例赋予角色 ) agency Agency(name高级研发团队) agency.hire(developer) agency.hire(devops) # 任务创建一个简单的待办事项API并管理代码 task 请开发一个简单的Flask RESTful API用于管理待办事项Todo。 需要两个端点 1. GET /todos: 获取所有待办事项列表。 2. POST /todos: 创建新的待办事项请求体包含‘title‘和‘done‘字段。 请使用内存中的列表临时存储数据即可。 完成后请将代码保存到文件并使用Git进行初始化和管理。 print(【任务开始】) # 1. 开发者写代码 code_task f{task}\n请首先输出完整的Python代码保存到‘todo_api.py‘文件中。 code_result await agency.assign_task(Charlie, code_task) print(fCharlie生成的代码:\n{code_result}\n) # 2. 我们将代码保存到文件模拟开发者完成了工作 # 注意在实际更自动化的流程中这一步可以由Agent调用‘写文件‘技能完成。 repo_name todo_flask_api os.makedirs(f./ai_projects/{repo_name}, exist_okTrue) with open(f./ai_projects/{repo_name}/todo_api.py, w) as f: # 这里需要从code_result中提取出代码部分我们假设它就是纯代码 f.write(code_result) # 3. 指令运维工程师初始化仓库并提交代码 devops_task f 在‘./ai_projects‘目录下有一个名为‘{repo_name}‘的新项目文件夹里面已有一个‘todo_api.py‘文件。 请执行以下操作 1. 初始化一个Git仓库。 2. 将‘todo_api.py‘文件提交到仓库提交信息为‘Initial commit: Todo API by AI team‘。 devops_result await agency.assign_task(David, devops_task) print(fDavid的操作结果:\n{devops_result}) # 4. 我们可以让David再验证一下 verify_task 请检查当前仓库的状态并确认提交历史。 verify_result await agency.assign_task(David, verify_task) print(f仓库验证结果:\n{verify_result}) if __name__ __main__: asyncio.run(advanced_team_demo())运行这个脚本你会看到开发者Charlie生成了Flask API代码然后运维工程师David自动调用了我们定义的init_repo和commit_code技能完成了Git仓库的初始化和代码提交。控制台会打印出每一步操作的成功或错误信息。注意这个例子中保存文件的操作是由我们脚本代劳的。在一个更完善的系统里你应该为开发者角色也创建一个FileSystemSkill自定义技能包含write_file,read_file等方法让AI团队能完全自主地操作文件系统。这体现了Agency-Agents的核心价值通过组合各种自定义技能打造出一个真正能闭环完成任务的自主团队。5. 避坑指南与效能提升关键技巧在实际使用Agency-Agents构建复杂工作流时你会遇到一些挑战。以下是我从多次失败和成功中总结出的关键经验。5.1 角色定义越具体越强大角色的profile描述是控制其行为风格的“宪法”。模糊的描述会导致不可预测的结果。反面例子profile“一个开发者”正面例子profile“”” 你是一名资深后端架构师特别擅长设计高并发、可扩展的微服务API。 你的代码风格严谨会为每个函数和复杂逻辑编写详细的文档字符串Docstring。 你非常重视错误处理对于可能失败的操作如网络请求、数据库查询一定会使用try-except块并记录日志。 在给出方案时你会同时考虑性能、安全性和后续的可维护性。 “””这样定义的角色在接到“设计一个用户登录接口”任务时大概率会输出包含JWT令牌、密码哈希、速率限制、数据库连接池等考量的详细设计而不仅仅是几行Flask路由代码。5.2 任务指令清晰、结构化、带约束给Agent的任务指令要像给优秀下属布置工作一样背景清晰、目标明确、交付物具体。糟糕指令“优化一下这个网站。”优秀指令 “你是一名前端性能优化专家。现有项目homepage.html的Lighthouse性能评分仅为65分。请分析其瓶颈并提出具体的代码修改方案。重点关注减少首屏加载时间当前3秒。优化图片资源当前未使用懒加载和WebP格式。请将你的建议分为‘高优先级’和‘中优先级’两类并给出每项修改预计能提升的分数。 最终输出一份Markdown格式的报告。”5.3 管理成本与上下文长度多个Agent协作会产生大量内部对话这些都会消耗LLM的上下文窗口Token。GPT-4的128K上下文很贵。技巧1设置max_tokens和temperature在为Role或Agency分配LLM时设置合理的max_tokens单次回复最大长度和较低的temperature如0.2以减少废话和不可控输出节约成本。llm OpenAIChatLLM(modelgpt-4, max_tokens2000, temperature0.2)技巧2使用“总结”技能对于长链条任务可以在工作流中插入一个Summarizer角色它的技能是将冗长的讨论或文档总结成要点然后将总结传递给下一个环节的Agent而不是传递全部历史。这能有效控制上下文膨胀。技巧3流式输出与超时控制对于长时间运行的任务使用异步流式输出如果框架支持来实时查看进展并为assign_task设置超时timeout参数防止某个Agent“卡住”导致整个流程僵死。5.4 错误处理与稳定性AI生成的内容可能不符合预期自定义技能的执行也可能失败如网络错误。为自定义技能添加健壮的异常捕获如前文GitSkill示例中的try...except块确保任何子进程或IO错误都能被捕获并以结构化的错误信息返回让其他Agent能理解发生了什么。设计“重试”或“人工审核”环节在关键的工作流节点如代码生成后、部署前可以设计一个HumanApproval环节或者让一个QAAgent根据规则如代码是否能通过语法检查来决定是继续执行还是回退到上一步重新生成。Agency-Agents支持基于条件的工作流你可以实现类似“如果代码检查失败则重新分配给开发者”的逻辑。5.5 技能冲突与权限管理当团队规模变大多个角色拥有相似或相同的技能时可能会产生冲突或重复劳动。明确技能归属在创建角色时仔细规划每个角色的技能树。让FrontendAgent拥有write_html_css技能而BackendAgent拥有write_python_api技能避免重叠。利用工作流控制调用顺序通过定义好的工作流如线性管道、有向无环图明确规定哪个角色在哪个阶段执行任务而不是让所有Agent同时响应一个广播消息。Agency-Agents的Workflow功能就是用来做这个的它比简单的assign_task更强大可以定义复杂的依赖关系和执行路径。6. 从Demo到生产规划你的AI Agent团队路线图通过上面的实战你已经掌握了搭建一个能跑起来的AI团队的基本方法。但要将其用于实际生产环境解决真实业务问题还需要更多的工程化工作。以下是一个可行的进阶路线图阶段一技能库扩展这是最基础也是最重要的一步。为你所在的领域构建丰富的自定义技能库。开发领域DockerBuildSkill、K8sDeploySkill、APITestSkill、LinterCheckSkill。数据分析领域QueryDatabaseSkill、GenerateChartSkill、SendEmailReportSkill。创意领域CallMidjourneyAPISkill、VideoEditSkill、SEOAnalyzeSkill。 每个技能都应像我们之前创建的GitSkill一样有清晰的输入、输出和异常处理。阶段二工作流引擎深化超越简单的线性任务分配利用Agency-Agents的Workflow或类似LangGraph可集成的工具设计复杂、动态的协作流程。条件分支如果测试失败则跳回开发阶段如果代码评审通过则自动触发部署。并行处理让前端Agent和后端Agent同时开始工作最后再由集成Agent进行联调。循环与迭代设计一个“写代码 - 单元测试 - 修复”的循环直到所有测试通过。阶段三记忆与知识库集成让AI团队拥有“长期记忆”和“公司知识”避免每次对话都从零开始。向量数据库将项目文档、API手册、历史对话记录存入向量数据库如Chroma、Pinecone。为团队配备一个RetrievalSkill使其在回答问题或做决策时能先检索相关知识。总结与沉淀在项目结束时自动触发一个ProjectSummarySkill将本次任务的关键决策、生成的代码、遇到的问题和解决方案自动整理成文档并存入知识库供未来团队参考。阶段四人机协同界面生产环境不可能完全无人值守。需要设计良好的人机交互点。关键审批节点在部署生产环境、发送客户邮件等高风险操作前必须设置人工审批环节。可以在工作流中插入一个发送通知到Slack/钉钉的技能等待人类确认。实时监控与干预利用Web UI或自定义仪表盘实时监控整个AI团队的协作状态、Token消耗、技能调用成功率。在Agent“跑偏”或陷入死循环时人类可以及时中断并给出新指令。阶段五评估与优化建立评估体系持续优化你的AI团队。定义成功指标任务完成率、代码正确率通过单元测试、人工干预频率、平均任务耗时、成本消耗。A/B测试尝试为同一个角色设计不同的profile描述或者使用不同的大模型如GPT-4 vs Claude-3在相同的测试任务集上对比效果。持续迭代根据评估结果和实际使用反馈不断调整角色的profile、优化技能的实现、精简工作流。这是一个持续的运维过程。从我个人的实践来看目前Agency-Agents这类框架最适合的场景是“有明确规则和模式的复杂重复性工作”比如根据标准模板生成不同业务的CRUD代码、自动化处理每日数据报告并邮件发送、按照固定流程进行应用的基础设施部署等。对于完全开放性的、需要大量创造性突破的任务AI团队的表现还不稳定但作为人类的“超级辅助团”它已经能释放出惊人的生产力。
1. 从单兵作战到团队协作为什么你需要一个AI Agent团队如果你还在用ChatGPT或者Claude这类大模型一个人对着对话框问来问去试图让它帮你完成一个稍微复杂点的任务比如写一份完整的市场分析报告、或者开发一个带前后端的小工具那你大概率会感到沮丧。模型要么忘记你十分钟前的要求要么在代码写到一半时突然“失忆”把变量名搞混。这感觉就像你雇了一个能力超强但记性极差、还时不时开小差的超级实习生所有事都得你盯着反而更累了。这就是“单智能体”Single Agent模式的瓶颈。一个AI模型再强大它的“工作记忆”Working Memory和任务拆解能力也是有限的。而“AI Agent团队”Agency-Agents的理念正是为了解决这个问题。它不再是让一个AI大包大揽而是模拟一个真实的项目团队有项目经理Orchestrator Agent负责拆解任务和协调进度有前端工程师Frontend Agent写界面有后端工程师Backend Agent处理逻辑和数据还有测试工程师QA Agent来检查代码质量。每个“Agent”都是一个专门化的AI实例它们各司其职通过一套通信和协作机制共同完成一个复杂目标。最近爆火的Hermes Agent、Agency-Agents框架本质上都是在提供搭建这种“AI团队”的脚手架。它们不是某个具体的大模型而是组织和管理多个AI智能体协同工作的“操作系统”或“中间件”。想象一下你作为人类产品经理只需要向这个“AI团队”下达一个清晰的指令“开发一个用户能上传图片并自动生成描述文字的Web应用”剩下的需求分析、技术选型、代码编写、模块联调、甚至部署脚本都可以由这个自主协作的AI团队来完成。你的角色从“码农”变成了“指挥官”生产力将得到质的飞跃。这篇文章我就以一个实际构建过多个AI Agent应用的经验带你快速上手Agency-Agents这个框架在3分钟内搭建起你的第一个AI开发团队。我们会避开空洞的概念直接进入实战从环境准备、核心配置、到跑通第一个协作任务并分享几个我踩过坑才总结出来的关键技巧。无论你是想探索AI应用开发新范式的开发者还是希望用AI大幅提升工作效率的产品经理或业务人员这篇指南都能给你一条清晰的落地路径。2. Agency-Agents核心架构与快速部署在开始敲代码之前我们必须先理解Agency-Agents框架的基本工作模式。与那些需要你从头编写大量胶水代码的底层Agent SDK不同Agency-Agents追求的是“开箱即用”的团队协作体验。它的核心思想是“角色”Role和“技能”Skill。2.1 核心概念角色、技能与工作流角色Role这就是你的“团队成员”。框架预置了多种角色比如ProductManager、SoftwareArchitect、FullStackDeveloper、QAEngineer等。每个角色都内置了对应的“系统提示词”System Prompt使其行为模式贴近真实的岗位。例如ProductManager会擅长拆解用户故事和定义验收标准而FullStackDeveloper则更关注具体的技术实现。技能Skill这是角色所能执行的具体操作。一个角色可以拥有多个技能。技能可以是基础技能如“分析需求”、“编写Python代码”、“执行Shell命令”。工具调用技能如“调用搜索引擎API”、“访问数据库”、“发送邮件”。自定义技能这是框架最强大的地方你可以将任何函数封装成技能赋予你的AI团队成员。比如封装一个部署到云服务器的函数那么你的DevOpsEngineer角色就能使用“部署到AWS”这个技能。工作流Workflow这是定义团队如何协作的剧本。一个简单的工作流可以是线性的ProductManager接收任务 -SoftwareArchitect设计架构 -FullStackDeveloper编写代码 -QAEngineer进行测试。Agency-Agents允许你定义更复杂的、带条件分支的协作流程。2.2 3分钟极速部署一行命令搭建环境Agency-Agents的安装极其简单这得益于它完善的Python包管理。前提是你已经安装了Python3.8以上和pip。打开你的终端命令行执行以下命令# 1. 安装Agency-Agents核心包 pip install agency-agents # 2. 可选但推荐安装用于Web界面管理的扩展包 pip install agency-agents[web]第一行命令会在1分钟内完成核心框架的安装。第二行命令安装了额外的Web UI依赖它会提供一个本地网页让你能可视化地观察和管理你的AI团队协作过程对于调试和理解内部机制非常有帮助。安装完成后你还需要准备一样东西大模型API密钥。Agency-Agents本身不提供模型它需要连接后端的LLM服务。它支持OpenAI的GPT系列、Anthropic的Claude系列以及任何兼容OpenAI API格式的模型服务如国内的一些大模型平台。提示对于快速实验强烈建议使用OpenAI的GPT-4或GPT-3.5-Turbo它们的指令遵循能力和代码能力在Agency-Agents的预设角色中表现最为稳定。你需要在OpenAI官网获取一个API Key。将你的API Key设置为环境变量这是最安全便捷的方式# 在Linux/Mac的终端中 export OPENAI_API_KEY你的-sk-xxx密钥 # 在Windows的PowerShell中 $env:OPENAI_API_KEY你的-sk-xxx密钥至此你的基础环境已经在3分钟内准备完毕。接下来我们将创建第一个AI团队并让它们开始工作。3. 创建你的第一个AI团队从“Hello World”到协同编程让我们从一个最简单的例子开始创建一个由“产品经理”和“全栈工程师”组成的两人小组目标是生成一个Python版本的“Hello World”网页应用的需求文档和代码。3.1 编写团队组建脚本创建一个名为first_team.py的Python文件输入以下代码import asyncio from agency_agents import Agency, Role, Skill from agency_agents.llms import OpenAIChatLLM # 1. 初始化大模型连接 # 这里使用GPT-3.5-Turbo成本低响应快适合实验 llm OpenAIChatLLM(modelgpt-3.5-turbo) # 2. 创建角色产品经理 product_manager Role( nameAlice, profile一位严谨、注重细节的产品经理擅长将模糊需求转化为清晰的用户故事和功能列表。, llmllm, skills[Skill.ANALYZE_REQUIREMENTS, Skill.WRITE_DOCUMENT] # 使用内置技能 ) # 3. 创建角色全栈工程师 full_stack_engineer Role( nameBob, profile一位经验丰富的全栈工程师精通Python Flask框架和HTML/CSS追求代码简洁高效。, llmllm, skills[Skill.WRITE_CODE, Skill.REVIEW_CODE] ) # 4. 创建智能体机构Agency并将角色加入团队 agency Agency(name我的第一个AI团队) agency.hire(product_manager) agency.hire(full_stack_engineer) # 5. 定义一个异步函数来运行团队任务 async def main(): task 请开发一个简单的Web应用在网页上显示‘Hello, AI Team!’。请先输出需求分析再输出实现代码。 print(f【任务发布】: {task}) print(- * 50) # 将任务分配给产品经理Alice print(【Alice产品经理开始工作...】) pm_result await agency.assign_task(role_nameAlice, tasktask) print(f产品需求文档:\n{pm_result}\n) print(- * 50) # 将产品经理的输出作为输入分配给工程师Bob print(【Bob全栈工程师开始工作...】) dev_task f根据以下产品需求编写完整的Flask应用代码包含一个简单的HTML页面。\n需求{pm_result} code_result await agency.assign_task(role_nameBob, taskdev_task) print(f实现代码:\n{code_result}) # 运行主函数 if __name__ __main__: asyncio.run(main())代码解读与避坑点OpenAIChatLLM这是连接LLM的桥梁。如果你用的是Claude可以换成AnthropicLLM。model参数指定具体模型版本。Role的profile这是关键不要只用默认值。花一两句话详细描述角色的性格和专业领域能极大提升该Agent在专业任务上的表现。比如给工程师加上“注重代码可读性和错误处理”他生成的代码就会包含try...except块。Skill.ANALYZE_REQUIREMENTS这些是框架内置的通用技能。你可以在官方文档找到完整的技能列表。在后续进阶中我们会学习创建自定义技能。agency.assign_task这是向特定角色分派任务的核心方法。注意我们使用了await因为Agent的思考过程是异步的。运行这个脚本python first_team.py你会看到控制台依次输出产品经理Alice生成的需求文档可能包含目标用户、功能点、非功能需求等和工程师Bob生成的完整Flask应用代码包含app.py和templates/index.html。一个简单的协作流程就跑通了。3.2 启动Web UI可视化观察协作刚才的协作是在后台发生的。要更直观地看到对话和思考过程我们可以启动Web UI。在同一个目录下创建另一个文件run_web.pyfrom agency_agents import Agency from agency_agents.llms import OpenAIChatLLM from agency_agents.web import run_web_app llm OpenAIChatLLM(modelgpt-3.5-turbo) agency Agency(name可视化团队) # 这里可以复用或重新创建角色并加入到agency中 # ... # 运行Web应用默认在 http://localhost:8501 访问 run_web_app(agency)运行python run_web.py然后在浏览器打开http://localhost:8501。你可以在这个界面中直接向某个角色发送消息也能看到角色之间为了完成任务而自动产生的内部对话这对于调试复杂的多步协作至关重要。4. 实战进阶构建能真正“干活”的自定义技能团队内置的通用技能只能完成基础信息处理。要让AI团队真正替代部分开发工作必须为其装备“手脚”——也就是自定义技能。我们来实现一个经典场景让AI团队自动创建一个Git仓库并将生成的代码提交上去。4.1 创建自定义技能Git操作我们将创建一个GitSkill类封装几个常用的Git命令。import subprocess import os from agency_agents import Skill from typing import Dict, Any class GitSkill(Skill): 自定义技能Git仓库管理 def __init__(self, workspace_path: str ./projects): super().__init__() self.workspace_path workspace_path os.makedirs(self.workspace_path, exist_okTrue) # 确保工作目录存在 Skill.action(description初始化一个新的Git仓库) async def init_repo(self, repo_name: str) - Dict[str, Any]: 在workspace_path下创建并初始化一个Git仓库 repo_path os.path.join(self.workspace_path, repo_name) if os.path.exists(repo_path): return {status: error, message: f目录 {repo_path} 已存在} os.makedirs(repo_path) try: subprocess.run([git, init], cwdrepo_path, checkTrue, capture_outputTrue, textTrue) return {status: success, message: f仓库 {repo_name} 初始化成功, path: repo_path} except subprocess.CalledProcessError as e: return {status: error, message: fGit初始化失败: {e.stderr}} Skill.action(description将文件添加到Git暂存区并提交) async def commit_code(self, repo_name: str, file_path: str, commit_message: str) - Dict[str, Any]: 提交指定文件到仓库 repo_path os.path.join(self.workspace_path, repo_name) if not os.path.exists(os.path.join(repo_path, .git)): return {status: error, message: 不是一个Git仓库} full_file_path os.path.join(repo_path, file_path) if not os.path.exists(full_file_path): return {status: error, message: f文件 {file_path} 不存在} try: # 添加文件 subprocess.run([git, add, file_path], cwdrepo_path, checkTrue, capture_outputTrue, textTrue) # 提交 result subprocess.run([git, commit, -m, commit_message], cwdrepo_path, checkTrue, capture_outputTrue, textTrue) return {status: success, message: f提交成功: {commit_message}, output: result.stdout} except subprocess.CalledProcessError as e: return {status: error, message: fGit操作失败: {e.stderr}}关键点解析Skill.action装饰器这是将普通类方法声明为Agent可调用技能的关键。description参数非常重要Agent会根据这个描述来决定何时使用该技能。异步方法技能方法必须是async的以兼容Agency-Agents的异步运行时。返回值标准化建议返回一个结构化的字典如包含status,message,data这样在后续的工作流中便于其他Agent解析结果。4.2 组建“开发-运维”一体化团队现在我们创建一个拥有GitSkill的DevOpsEngineer角色并与之前的FullStackDeveloper协作。import asyncio from agency_agents import Agency, Role from agency_agents.llms import OpenAIChatLLM # 假设上面的GitSkill类定义在同一个文件或已导入 async def advanced_team_demo(): llm OpenAIChatLLM(modelgpt-4) # 使用能力更强的GPT-4进行复杂任务 # 创建开发工程师 developer Role( nameCharlie, profilePython开发专家擅长Flask/Django代码规范清晰。, llmllm, skills[Skill.WRITE_CODE] ) # 创建运维工程师并赋予其Git技能 git_skill GitSkill(workspace_path./ai_projects) devops Role( nameDavid, profileDevOps工程师负责代码仓库管理、CI/CD和部署。, llmllm, skills[git_skill] # 将自定义技能实例赋予角色 ) agency Agency(name高级研发团队) agency.hire(developer) agency.hire(devops) # 任务创建一个简单的待办事项API并管理代码 task 请开发一个简单的Flask RESTful API用于管理待办事项Todo。 需要两个端点 1. GET /todos: 获取所有待办事项列表。 2. POST /todos: 创建新的待办事项请求体包含‘title‘和‘done‘字段。 请使用内存中的列表临时存储数据即可。 完成后请将代码保存到文件并使用Git进行初始化和管理。 print(【任务开始】) # 1. 开发者写代码 code_task f{task}\n请首先输出完整的Python代码保存到‘todo_api.py‘文件中。 code_result await agency.assign_task(Charlie, code_task) print(fCharlie生成的代码:\n{code_result}\n) # 2. 我们将代码保存到文件模拟开发者完成了工作 # 注意在实际更自动化的流程中这一步可以由Agent调用‘写文件‘技能完成。 repo_name todo_flask_api os.makedirs(f./ai_projects/{repo_name}, exist_okTrue) with open(f./ai_projects/{repo_name}/todo_api.py, w) as f: # 这里需要从code_result中提取出代码部分我们假设它就是纯代码 f.write(code_result) # 3. 指令运维工程师初始化仓库并提交代码 devops_task f 在‘./ai_projects‘目录下有一个名为‘{repo_name}‘的新项目文件夹里面已有一个‘todo_api.py‘文件。 请执行以下操作 1. 初始化一个Git仓库。 2. 将‘todo_api.py‘文件提交到仓库提交信息为‘Initial commit: Todo API by AI team‘。 devops_result await agency.assign_task(David, devops_task) print(fDavid的操作结果:\n{devops_result}) # 4. 我们可以让David再验证一下 verify_task 请检查当前仓库的状态并确认提交历史。 verify_result await agency.assign_task(David, verify_task) print(f仓库验证结果:\n{verify_result}) if __name__ __main__: asyncio.run(advanced_team_demo())运行这个脚本你会看到开发者Charlie生成了Flask API代码然后运维工程师David自动调用了我们定义的init_repo和commit_code技能完成了Git仓库的初始化和代码提交。控制台会打印出每一步操作的成功或错误信息。注意这个例子中保存文件的操作是由我们脚本代劳的。在一个更完善的系统里你应该为开发者角色也创建一个FileSystemSkill自定义技能包含write_file,read_file等方法让AI团队能完全自主地操作文件系统。这体现了Agency-Agents的核心价值通过组合各种自定义技能打造出一个真正能闭环完成任务的自主团队。5. 避坑指南与效能提升关键技巧在实际使用Agency-Agents构建复杂工作流时你会遇到一些挑战。以下是我从多次失败和成功中总结出的关键经验。5.1 角色定义越具体越强大角色的profile描述是控制其行为风格的“宪法”。模糊的描述会导致不可预测的结果。反面例子profile“一个开发者”正面例子profile“”” 你是一名资深后端架构师特别擅长设计高并发、可扩展的微服务API。 你的代码风格严谨会为每个函数和复杂逻辑编写详细的文档字符串Docstring。 你非常重视错误处理对于可能失败的操作如网络请求、数据库查询一定会使用try-except块并记录日志。 在给出方案时你会同时考虑性能、安全性和后续的可维护性。 “””这样定义的角色在接到“设计一个用户登录接口”任务时大概率会输出包含JWT令牌、密码哈希、速率限制、数据库连接池等考量的详细设计而不仅仅是几行Flask路由代码。5.2 任务指令清晰、结构化、带约束给Agent的任务指令要像给优秀下属布置工作一样背景清晰、目标明确、交付物具体。糟糕指令“优化一下这个网站。”优秀指令 “你是一名前端性能优化专家。现有项目homepage.html的Lighthouse性能评分仅为65分。请分析其瓶颈并提出具体的代码修改方案。重点关注减少首屏加载时间当前3秒。优化图片资源当前未使用懒加载和WebP格式。请将你的建议分为‘高优先级’和‘中优先级’两类并给出每项修改预计能提升的分数。 最终输出一份Markdown格式的报告。”5.3 管理成本与上下文长度多个Agent协作会产生大量内部对话这些都会消耗LLM的上下文窗口Token。GPT-4的128K上下文很贵。技巧1设置max_tokens和temperature在为Role或Agency分配LLM时设置合理的max_tokens单次回复最大长度和较低的temperature如0.2以减少废话和不可控输出节约成本。llm OpenAIChatLLM(modelgpt-4, max_tokens2000, temperature0.2)技巧2使用“总结”技能对于长链条任务可以在工作流中插入一个Summarizer角色它的技能是将冗长的讨论或文档总结成要点然后将总结传递给下一个环节的Agent而不是传递全部历史。这能有效控制上下文膨胀。技巧3流式输出与超时控制对于长时间运行的任务使用异步流式输出如果框架支持来实时查看进展并为assign_task设置超时timeout参数防止某个Agent“卡住”导致整个流程僵死。5.4 错误处理与稳定性AI生成的内容可能不符合预期自定义技能的执行也可能失败如网络错误。为自定义技能添加健壮的异常捕获如前文GitSkill示例中的try...except块确保任何子进程或IO错误都能被捕获并以结构化的错误信息返回让其他Agent能理解发生了什么。设计“重试”或“人工审核”环节在关键的工作流节点如代码生成后、部署前可以设计一个HumanApproval环节或者让一个QAAgent根据规则如代码是否能通过语法检查来决定是继续执行还是回退到上一步重新生成。Agency-Agents支持基于条件的工作流你可以实现类似“如果代码检查失败则重新分配给开发者”的逻辑。5.5 技能冲突与权限管理当团队规模变大多个角色拥有相似或相同的技能时可能会产生冲突或重复劳动。明确技能归属在创建角色时仔细规划每个角色的技能树。让FrontendAgent拥有write_html_css技能而BackendAgent拥有write_python_api技能避免重叠。利用工作流控制调用顺序通过定义好的工作流如线性管道、有向无环图明确规定哪个角色在哪个阶段执行任务而不是让所有Agent同时响应一个广播消息。Agency-Agents的Workflow功能就是用来做这个的它比简单的assign_task更强大可以定义复杂的依赖关系和执行路径。6. 从Demo到生产规划你的AI Agent团队路线图通过上面的实战你已经掌握了搭建一个能跑起来的AI团队的基本方法。但要将其用于实际生产环境解决真实业务问题还需要更多的工程化工作。以下是一个可行的进阶路线图阶段一技能库扩展这是最基础也是最重要的一步。为你所在的领域构建丰富的自定义技能库。开发领域DockerBuildSkill、K8sDeploySkill、APITestSkill、LinterCheckSkill。数据分析领域QueryDatabaseSkill、GenerateChartSkill、SendEmailReportSkill。创意领域CallMidjourneyAPISkill、VideoEditSkill、SEOAnalyzeSkill。 每个技能都应像我们之前创建的GitSkill一样有清晰的输入、输出和异常处理。阶段二工作流引擎深化超越简单的线性任务分配利用Agency-Agents的Workflow或类似LangGraph可集成的工具设计复杂、动态的协作流程。条件分支如果测试失败则跳回开发阶段如果代码评审通过则自动触发部署。并行处理让前端Agent和后端Agent同时开始工作最后再由集成Agent进行联调。循环与迭代设计一个“写代码 - 单元测试 - 修复”的循环直到所有测试通过。阶段三记忆与知识库集成让AI团队拥有“长期记忆”和“公司知识”避免每次对话都从零开始。向量数据库将项目文档、API手册、历史对话记录存入向量数据库如Chroma、Pinecone。为团队配备一个RetrievalSkill使其在回答问题或做决策时能先检索相关知识。总结与沉淀在项目结束时自动触发一个ProjectSummarySkill将本次任务的关键决策、生成的代码、遇到的问题和解决方案自动整理成文档并存入知识库供未来团队参考。阶段四人机协同界面生产环境不可能完全无人值守。需要设计良好的人机交互点。关键审批节点在部署生产环境、发送客户邮件等高风险操作前必须设置人工审批环节。可以在工作流中插入一个发送通知到Slack/钉钉的技能等待人类确认。实时监控与干预利用Web UI或自定义仪表盘实时监控整个AI团队的协作状态、Token消耗、技能调用成功率。在Agent“跑偏”或陷入死循环时人类可以及时中断并给出新指令。阶段五评估与优化建立评估体系持续优化你的AI团队。定义成功指标任务完成率、代码正确率通过单元测试、人工干预频率、平均任务耗时、成本消耗。A/B测试尝试为同一个角色设计不同的profile描述或者使用不同的大模型如GPT-4 vs Claude-3在相同的测试任务集上对比效果。持续迭代根据评估结果和实际使用反馈不断调整角色的profile、优化技能的实现、精简工作流。这是一个持续的运维过程。从我个人的实践来看目前Agency-Agents这类框架最适合的场景是“有明确规则和模式的复杂重复性工作”比如根据标准模板生成不同业务的CRUD代码、自动化处理每日数据报告并邮件发送、按照固定流程进行应用的基础设施部署等。对于完全开放性的、需要大量创造性突破的任务AI团队的表现还不稳定但作为人类的“超级辅助团”它已经能释放出惊人的生产力。
