30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度如果你正在寻找一个能真正理解你意图、自主完成任务而不仅仅是机械执行命令的AI助手那么你很可能已经接触过“AI Agent”这个概念。但现实往往是演示视频里Agent行云流水自己上手却要么卡在环境配置要么困于复杂的API调用最终那个“智能体”更像一个需要步步指导的“提线木偶”。今天要深入探讨的agency-agents项目或许能改变这种局面。它不是一个全新的底层框架而是一个基于成熟开源项目agency构建的、开箱即用的AI Agent集合。它的核心价值在于将Agent从“概念验证”快速推向“实际可用”为开发者提供了一个高起点让你不必从零开始造轮子就能直接体验和集成具备复杂任务分解与协作能力的智能体。本文将带你彻底搞懂agency-agents它是什么、解决了什么痛点、如何快速部署并通过一个完整的代码示例展示如何构建一个能自动编写代码、执行测试、并生成文档的“全栈开发Agent”。我们不止步于“跑通Demo”更会深入其架构分析最佳实践并列出你一定会遇到的坑及其解决方案。1. 这篇文章真正要解决的问题为什么我们需要agency-agents在AI应用开发中存在一个典型的“最后一公里”问题大模型API提供了强大的认知能力但要将这种能力转化为一个能可靠运行、完成特定工作流的自动化系统中间隔着巨大的工程鸿沟。你需要处理任务规划、工具调用、状态管理、错误处理、多Agent协作等一系列复杂问题。agency-agents项目正是为了填平这道鸿沟而生。它基于agency框架一个轻量级、可扩展的Agent开发框架预置了一系列具备特定技能的Agent如代码编写、文件操作、网页搜索等以及让这些Agent协同工作的标准流程。这意味着降低启动门槛你无需从零设计Agent的思维链Chain-of-Thought或工具调用Tool Calling逻辑直接使用预构建的、经过测试的Agent。聚焦业务逻辑你可以像搭积木一样组合这些Agent来构建复杂的工作流而无需关心底层通信和协调机制。获得生产级参考该项目本身就是一个最佳实践示例其代码结构、错误处理、日志记录方式都值得学习为你的自定义Agent开发提供范本。本文的目标读者是有一定Python基础对AI Agent感兴趣并希望快速构建一个可演示甚至可部署的智能体应用的开发者。读完本文你将能独立完成一个多Agent协作系统的环境搭建、配置和定制开发。2. 基础概念与核心原理在深入代码之前必须厘清几个关键概念否则很容易在后续配置中混淆。agency框架这是一个开源Python框架它定义了Agent的基本抽象如Agent类、消息传递机制以及空间Space的概念。你可以把它理解为构建多智能体系统的“操作系统”或“通信总线”。它负责Agent的注册、发现以及彼此间的对话路由。agency-agents项目这是建立在agency框架之上的一个“应用层”或“套件”。它提供了多个具体的、功能各异的Agent实现例如CoderAgent,BrowserAgent以及一些预配置的工作流示例。它的目标是展示agency框架的能力并让开发者能立即使用这些高级Agent。Agent智能体在本文语境下一个Agent是一个具有特定目标、并能通过调用工具Tools或与其他Agent通信来达成目标的软件实体。每个Agent通常绑定一个大语言模型LLM用于理解任务和做出决策。Skill技能/ Tool工具这是Agent能力的延伸。一个Skill可以是一个函数让Agent能执行特定操作如读写文件、执行Shell命令、调用API等。agency框架通过装饰器如action将普通Python函数暴露为Agent可调用的技能。Space空间一个虚拟的“房间”或“环境”多个Agent在其中共存并可以相互通信。所有Agent必须加入一个Space才能交互。它们之间的关系可以用一个简单的类比来理解agency框架是电话网络和通信协议agency-agents是一批预先安装好专业App如计算器、地图、浏览器的手机而你自己开发的Agent则是一个空白手机你可以从agency-agents那里获得灵感甚至直接安装导入它的某些AppSkill到你的手机上。3. 环境准备与前置条件开始实操前请确保你的环境满足以下要求。这是后续所有步骤的基础。操作系统推荐 Linux (Ubuntu 20.04) 或 macOS。Windows系统建议使用 WSL2 (Windows Subsystem for Linux) 以获得最佳体验。Python版本Python 3.10 或 3.11。这是关键许多依赖库对Python 3.12的兼容性可能还不完善为避免不必要的麻烦请使用指定版本。你可以使用pyenv或conda来管理多版本Python。包管理工具pip的最新版本。API密钥你需要一个或多个大语言模型的API密钥。agency-agents默认支持 OpenAI 的 GPT 模型。后续我们也会说明如何接入其他模型如 Anthropic Claude, 本地模型等。首先创建一个干净的虚拟环境这是Python项目的最佳实践可以避免依赖冲突。# 创建项目目录并进入 mkdir my-agent-project cd my-agent-project # 创建虚拟环境以 venv 为例 python3.10 -m venv venv # 激活虚拟环境 # Linux/macOS source venv/bin/activate # Windows (cmd) # venv\Scripts\activate # Windows (PowerShell) # .\venv\Scripts\Activate.ps1 # 升级pip pip install --upgrade pip4. 安装与基础配置接下来安装agency-agents及其核心依赖agency。# 安装 agency-agents它会自动安装 agency 等依赖 pip install agency-agents安装完成后你需要配置LLM的API密钥。agency框架通过环境变量来管理这些敏感信息。创建一个名为.env的文件在项目根目录下注意文件名开头的点。# 在项目根目录下创建 .env 文件 touch .env编辑.env文件填入你的OpenAI API密钥。# .env 文件内容 OPENAI_API_KEYsk-your-actual-openai-api-key-here重要安全提示绝对不要将.env文件提交到版本控制系统如Git。请确保它在.gitignore中。API密钥是付费凭证泄露会导致经济损失。在本地开发中python-dotenv库通常已被agency依赖会自动加载这个文件。5. 核心流程拆解运行你的第一个多Agent系统让我们从一个最简单的例子开始感受多Agent是如何协作的。这个例子包含两个Agent一个CoderAgent程序员Agent和一个WriterAgent作家Agent。我们将创建一个空间让它们互相打招呼并简单交流。创建一个名为first_agents.py的文件。# first_agents.py import asyncio from agency import Space from agency.agents import CoderAgent, WriterAgent from dotenv import load_dotenv import os # 加载环境变量 load_dotenv() async def main(): # 1. 创建一个Space空间 space Space() # 2. 创建并添加Agent到空间中 # CoderAgent: 擅长编程相关任务 coder CoderAgent(Alice, A helpful coding assistant.) # WriterAgent: 擅长写作和内容生成 writer WriterAgent(Bob, A creative writing assistant.) space.add(coder) space.add(writer) # 3. 启动空间 print(Starting the agent space...) await space.start() # 4. 让Agent们开始对话模拟一个用户请求 try: # 用户向CoderAgent Alice提问 response await coder.ask(Hello Alice, can you introduce your friend Bob to me?) print(fAlice says: {response}) # 等待一下让对话自然进行 await asyncio.sleep(2) # 我们也可以直接向WriterAgent Bob提问 response await writer.ask(Hi Bob, what do you think about Alices coding skills?) print(fBob says: {response}) finally: # 5. 清理并停止空间 await space.stop() if __name__ __main__: asyncio.run(main())代码逐行解析导入与配置导入必要的模块并加载环境变量你的API密钥。创建空间Space()实例化一个虚拟环境。添加Agent创建CoderAgent和WriterAgent实例每个Agent需要一个唯一的名字id和一段描述。space.add()方法将它们注册到空间中使它们能相互感知。启动空间space.start()是一个异步方法它会初始化所有Agent的内部状态。发起对话我们使用agent.ask()方法向特定Agent发送消息。这里模拟了一个用户分别与两个Agent交互的场景。在真实的多Agent协作中Agent之间会自动对话。资源清理使用space.stop()来优雅地关闭所有连接。运行这个脚本python first_agents.py你应该会看到类似以下的输出表明Agent正在思考并调用LLM生成回复Starting the agent area... Alice says: Hello! Of course. My friend Bob is a talented WriterAgent. Hes incredibly creative and has a way with words that can bring any idea to life. Hes great at crafting stories, generating content, and providing thoughtful feedback on written material. If you need help with writing, brainstorming, or editing, Bobs your agent! Bob says: Alice is an exceptional CoderAgent! Her programming skills are top-notch—she can tackle complex algorithms, debug tricky issues, and write clean, efficient code in multiple languages. Shes very logical, detail-oriented, and always finds elegant solutions to technical challenges. Working with her is a breeze because she communicates clearly and is always ready to collaborate. A true asset in any development team!恭喜你已经成功运行了一个多Agent系统。虽然这个对话很简单但背后是agency框架在管理消息路由和Agent生命周期。6. 构建一个实用的多Agent工作流自动代码开发与评审现在我们来构建一个更贴近实际开发的场景一个能接收需求、自动编写Python代码、执行单元测试并最终生成项目文档的自动化工作流。这将涉及多个agency-agents中的预置Agent。我们将使用以下AgentPlannerAgent负责分解复杂任务为子任务。CoderAgent负责编写和修改代码。BashAgent负责在安全沙箱中执行Shell命令如运行测试。WriterAgent负责撰写文档。创建一个新文件code_review_workflow.py。# code_review_workflow.py import asyncio import os from agency import Space from agency.agents import PlannerAgent, CoderAgent, BashAgent, WriterAgent from dotenv import load_dotenv load_dotenv() async def main(): space Space() # 1. 初始化各个职能的Agent planner PlannerAgent( idChiefPlanner, descriptionYou are a project manager who breaks down complex software development tasks into clear steps. ) coder CoderAgent( idSeniorDeveloper, descriptionYou are a senior Python developer. Write clean, efficient, and well-documented code. Always include error handling. ) bash BashAgent( idSystemOps, descriptionYou are a DevOps engineer. You can run commands in a sandboxed environment to test code and manage files., # 限制BashAgent的工作目录增强安全性 sandbox_path./workspace ) writer WriterAgent( idTechnicalWriter, descriptionYou are a technical writer. You create clear and concise documentation based on code and specifications. ) # 2. 将所有Agent加入空间 for agent in [planner, coder, bash, writer]: space.add(agent) print( Multi-Agent Code Development System Started!) print(Agents: ChiefPlanner, SeniorDeveloper, SystemOps, TechnicalWriter are online.) print(- * 50) await space.start() try: # 3. 用户提出一个开发需求 user_request Please develop a Python function that solves the classic FizzBuzz problem. Requirements: 1. Function name: fizzbuzz. 2. Input: An integer n. 3. Output: A list of strings from 1 to n, where: - Multiples of 3 replaced by Fizz - Multiples of 5 replaced by Buzz - Multiples of both 3 and 5 replaced by FizzBuzz 4. Please also write a simple unit test using Pythons unittest framework. 5. Finally, generate a brief README.md explaining the function. The entire project should be created in the ./workspace directory. print(f User Request:\n{user_request}\n) print( Agents are collaborating to complete the task...\n) # 4. 将任务首先交给规划师进行分解 plan await planner.ask(user_request) print(f [ChiefPlanner] Task Plan:\n{plan}\n) # 5. 规划师将编码任务分配给开发者 (这里简化了自动路由实际可通过Space广播) # 在实际复杂工作流中Planner会通过Space直接给Coder发送消息。 # 本例中我们手动模拟这一流程。 code_task fBased on the plan, write the implementation for the FizzBuzz function and its unit test. Put files in ./workspace. code_response await coder.ask(code_task) print(f [SeniorDeveloper] Code Implementation Done.\n{code_response}\n) # 6. 让运维Agent运行单元测试 test_command cd ./workspace python -m pytest -v test_fizzbuzz.py 21 || python -m unittest discover -s ./workspace -v test_result await bash.ask(test_command) print(f⚙️ [SystemOps] Test Execution Result:\n{test_result}\n) # 7. 根据代码和测试结果让技术文档员撰写README doc_brief fHere is the implemented code and test results. Please create a professional README.md file for this FizzBuzz project in ./workspace.\nCode written: {code_response[:500]}...\nTest Results: {test_result[:500]}... readme_content await writer.ask(doc_brief) print(f [TechnicalWriter] README Generated.\n{readme_content}\n) print(✅ Task completed! Check the ./workspace directory for the generated files.) finally: await space.stop() if __name__ __main__: # 确保工作目录存在 os.makedirs(./workspace, exist_okTrue) asyncio.run(main())这个工作流的核心逻辑任务输入用户提出一个包含具体需求的开发任务。规划分解PlannerAgent首先理解需求并将其分解为“编码”、“测试”、“文档”等子任务。这一步模拟了项目经理或技术负责人的角色。编码实现CoderAgent接收具体的编码指令生成Python源代码文件fizzbuzz.py和单元测试文件test_fizzbuzz.py。它会利用LLM的代码生成能力。测试验证BashAgent在指定的沙箱目录./workspace中执行Shell命令运行单元测试。它将测试结果成功或失败及日志反馈回来。这是关键一步将AI的“想象”落地为实际的“可执行验证”。文档生成WriterAgent综合代码和测试结果生成项目文档README.md。运行这个工作流python code_review_workflow.py运行后检查./workspace目录你应该能看到生成的fizzbuzz.py、test_fizzbuzz.py和README.md文件。这个简单的流水线展示了AI Agent在软件开发生命周期中自动化部分的潜力。7. 运行结果与效果验证运行上述脚本后你会在控制台看到详细的步骤输出。更重要的验证是检查生成的文件是否可用。验证步骤1检查生成的文件ls -la ./workspace/你应该能看到类似以下的文件-rw-r--r-- 1 user staff 543 Apr 10 10:00 README.md -rw-r--r-- 1 user staff 456 Apr 10 10:00 fizzbuzz.py -rw-r--r-- 1 user staff 789 Apr 10 10:00 test_fizzbuzz.py验证步骤2手动运行测试确认代码功能正确cd ./workspace python -m pytest test_fizzbuzz.py -v # 或者使用 unittest python -m unittest discover -v如果测试通过你会看到OK或所有测试用例成功的提示。这证明CoderAgent生成的代码不仅是语法正确的在逻辑上也符合FizzBuzz的要求。验证步骤3审查生成的文档cat ./workspace/README.md文档应该包含项目描述、安装说明、使用示例等信息。这验证了WriterAgent的信息整合能力。如何判断系统运行成功控制台输出没有出现Python异常 traceback并且每个Agent阶段都有明确的输出日志。文件生成在指定目录正确生成了目标文件。功能正确生成的代码可以通过自带的单元测试。逻辑连贯整个工作流规划-编码-测试-文档被自动执行无需人工干预步骤间的交接。如果失败第一步应该查看控制台报错信息。最常见的问题是API密钥未设置、网络超时或生成的代码存在语法错误导致测试失败。BashAgent的执行结果会详细返回错误信息这是重要的调试依据。8. 深入架构与自定义Skill开发仅仅使用预置Agent是不够的。要真正发挥agency和agency-agents的威力你需要学会自定义Skill让你的Agent获得独一无二的能力。假设我们需要一个能查询当前天气的Agent。我们将创建一个新的WeatherAgent并为它添加一个get_weather的Skill。这里我们使用一个模拟的天气API。创建一个新文件custom_agent.py。# custom_agent.py import asyncio from agency import Agent, action from agency import Space import aiohttp import os from dotenv import load_dotenv load_dotenv() # 1. 自定义一个Agent类继承自基类Agent class WeatherAgent(Agent): def __init__(self, id, description): super().__init__(id, description) # 可以在这里初始化一些资源比如API客户端 self.session None # 2. 使用 action 装饰器定义一个技能 # 这个技能可以被其他Agent或用户调用 action async def get_weather(self, city: str) - str: Get the current weather for a given city. Args: city: The name of the city. Returns: A string describing the weather. # 在实际应用中这里会调用真实的天气API如OpenWeatherMap # 为了示例我们模拟一个返回 simulated_weather_data { Beijing: Sunny, 22°C, Shanghai: Cloudy, 18°C, New York: Rainy, 12°C, London: Foggy, 10°C } weather simulated_weather_data.get(city, Weather information not available for this city.) return fThe current weather in {city} is: {weather} # 3. 可选重写生命周期方法 async def _start(self): Agent启动时调用 print(fWeatherAgent {self.id} is starting up...) self.session aiohttp.ClientSession() await super()._start() async def _stop(self): Agent停止时调用 print(fWeatherAgent {self.id} is shutting down...) if self.session: await self.session.close() await super()._stop() async def main(): space Space() # 4. 创建并使用自定义Agent weather_man WeatherAgent(WeatherMan, A friendly agent that provides weather information.) space.add(weather_man) await space.start() try: # 测试调用自定义技能 result await weather_man.ask(Whats the weather like in Beijing?) print(fWeatherMan says: {result}) # 也可以直接调用action更程序化的方式 # result await weather_man.get_weather(London) # print(result) finally: await space.stop() if __name__ __main__: asyncio.run(main())关键点解析继承Agent类这是创建自定义Agent的标准方式。action装饰器这是将方法暴露为Agent技能的核心。被装饰的方法可以接受参数并有类型提示和文档字符串这些信息会被框架用于生成给LLM的“工具描述”使LLM知道如何调用这个技能。生命周期方法_start()和_stop()允许你在Agent启动和关闭时进行资源初始化和清理如创建/关闭HTTP会话。技能调用其他Agent或用户可以通过agent.ask(“自然语言请求”)的方式间接调用技能LLM会理解意图并转化为对get_weather的调用。也可以直接使用await agent.get_weather(“London”)进行程序化调用。运行这个文件你会看到WeatherAgent成功响应了天气查询。通过这种方式你可以将任何Python函数数据库查询、调用内部API、操作硬件等封装成Agent的技能极大地扩展了Agent的能力边界。9. 常见问题与排查思路在实际使用agency-agents时你可能会遇到以下典型问题。这里提供一个排查清单。问题现象可能原因排查方式解决方案启动时报ModuleNotFoundError依赖未正确安装或虚拟环境未激活。1. 运行pip list | grep agency检查包是否存在。2. 确认终端提示符前有(venv)标识。1. 激活虚拟环境source venv/bin/activate。2. 重新安装pip install agency-agents。运行时代理无响应或报错OPENAI_API_KEYnot found环境变量未设置或未加载。1. 检查.env文件是否存在且路径正确。2. 在Python中print(os.getenv(‘OPENAI_API_KEY’))查看是否加载。1. 确保.env文件在脚本同级目录。2. 在代码开头显式调用load_dotenv()。3. 直接在终端导出变量export OPENAI_API_KEYsk-xxx。Agent回复慢或超时1. 网络连接问题。2. OpenAI API 限速或故障。3. 任务过于复杂LLM生成时间长。1. 检查网络连通性。2. 查看OpenAI控制台状态页。3. 尝试一个更简单的提示词。1. 增加超时设置在创建Agent时配置LLM客户端参数。2. 使用更快的模型如gpt-3.5-turbo。3. 将复杂任务拆解。BashAgent执行命令失败或权限错误1. 命令本身语法错误。2. 沙箱路径sandbox_path不存在或不可写。3. 尝试执行了危险命令如rm -rf /。1. 查看BashAgent返回的错误信息。2. 检查sandbox_path目录的权限。1. 确保sandbox_path目录已创建 (os.makedirs)。2. 在安全环境下测试命令。3. 仔细审查由LLM生成的命令必要时进行过滤或限制。多Agent协作时消息未按预期传递1. Agent未加入同一个Space。2. 消息发送的目标Agent ID错误。3. 使用的是异步函数但未正确await。1. 打印space._agents查看已注册的Agent。2. 检查调用ask或send方法时使用的ID。1. 确保所有协作Agent都通过space.add()添加。2. 使用space.broadcast()进行广播或使用space.find_agent(id)查找目标。3. 确保在异步函数中调用。自定义Skill未被LLM识别或调用1.action装饰器缺失或位置错误。2. 函数缺少类型提示和文档字符串。3. Agent未正确启动。1. 检查方法定义。2. 查看Agent的_action_schema属性确认技能是否已注册。1. 确保action装饰器在方法正上方。2. 为技能函数添加清晰的参数类型和docstring。3. 确保在space.start()后才调用技能。10. 最佳实践与工程建议将agency-agents用于实际项目时遵循以下建议可以避免很多麻烦并构建出更健壮的系统。1. 环境与配置管理始终使用虚拟环境为每个项目创建独立的虚拟环境。敏感信息管理永远不要将API密钥硬编码在代码中。使用.env文件并通过python-dotenv加载。在生产环境中使用安全的密钥管理服务如AWS Secrets Manager, HashiCorp Vault。配置外部化将模型类型、温度temperature、超时时间等参数放在配置文件如config.yaml中便于不同环境切换。2. Agent设计与技能规划单一职责每个Agent应专注于一个明确的领域如代码、写作、运维。这使系统更易于理解和调试。技能粒度自定义Skill应保持小而专。一个技能只做一件事。例如query_database和update_user_profile应该是两个独立的技能而不是一个庞大的handle_user_data函数。充分的错误处理在自定义Skill内部必须用try…except捕获所有可能的异常并返回有意义的错误信息给调用者避免整个Agent因一个技能崩溃。3. 安全性沙箱化执行对于BashAgent或任何执行外部命令/代码的Agent必须使用sandbox_path将其限制在特定目录。绝对不要赋予其不受限制的系统访问权限。输入验证与过滤对来自LLM或用户的输入进行严格的验证和过滤防止注入攻击。特别是当LLM生成的命令会被执行时。权限最小化Agent只应拥有完成其任务所必需的最低权限。例如一个文档Agent不需要数据库写权限。4. 性能与可靠性设置超时对LLM API调用和Agent间的消息传递设置合理的超时防止系统因某个环节挂起而僵死。异步编程agency框架基于asyncio。确保你的自定义技能也是异步的使用async def以避免阻塞整个事件循环。日志记录为你的Agent添加详细的日志记录记录关键决策、技能调用和错误。这对于调试复杂的工作流至关重要。5. 测试与监控单元测试Agent技能像测试普通函数一样测试你的自定义Skill。集成测试工作流编写端到端的测试模拟用户输入验证整个多Agent工作流的输出是否符合预期。监控API成本与用量尤其是使用GPT-4等昂贵模型时密切关注Token消耗设置预算警报。agency-agents项目为我们提供了一个绝佳的起点它展示了如何用代码将多个AI智能体组织成一个能协同工作的系统。从运行第一个对话到构建自动化的开发流水线再到开发自定义技能我们一步步揭开了多Agent系统的神秘面纱。它的价值不在于替代开发者而在于放大开发者的能力。你可以将它视为一个高度可定制、自动化的“数字团队”负责处理那些定义明确但执行繁琐的任务从而让你能更专注于架构设计、复杂问题解决和创造性工作。下一步你可以尝试接入更多模型探索agency框架如何接入 Claude、Gemini 或本地部署的 Llama 模型。实现更复杂的工作流例如一个接收Bug报告、自动定位代码、生成修复补丁、运行测试并提交PR的完整运维Agent。添加持久化与记忆让Agent能够记住之前的对话和任务上下文实现更连贯的长期协作。构建Web界面使用FastAPI或Gradio为你的多Agent系统创建一个用户友好的操作面板。记住所有强大的工具都需要在安全的边界内使用。在享受自动化带来的便利时务必时刻将安全、可控和可解释性放在首位。现在你已经拥有了启动项目的钥匙剩下的就是发挥你的想象力去构建那个属于你的智能体团队了。建议将本文中的示例代码保存并作为模板在遇到问题时随时回来查阅。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度