在实际的软件开发流程中单个开发者或单一AI助手处理复杂任务时常常会遇到上下文切换频繁、工具链整合困难、任务拆解不彻底等问题。尤其是在面对一个包含需求分析、架构设计、代码实现、测试验证和文档编写的完整项目时手动串联各个环节不仅效率低下而且容易出错。HARHarness for Agentic Workflows作为一个开源框架正是为了解决多智能体Multi-Agent协同编码工作流中的这些痛点而生。它不是一个单一的代码生成工具而是一个用于编排、管理和执行由多个AI智能体构成的自动化工作流的“马具”Harness。本文面向希望将AI深度融入开发流程的工程师、技术负责人以及对多智能体系统Multi-Agent Systems感兴趣的开发者。我们将从零开始理解HAR的核心概念搭建一个基础的多智能体编码环境并通过一个具体的“创建REST API服务”任务演示如何定义工作流、配置智能体并执行最终获得可运行的代码。你将学会如何利用HAR将复杂的开发任务分解并交由不同的专业智能体协作完成从而提升开发的一致性和自动化水平。1. 理解HAR多智能体工作流的编排引擎在深入配置和代码之前必须厘清HAR的核心定位。它不是一个像GitHub Copilot或Codex那样的代码补全模型也不是一个像Continue这样的IDE插件。HAR是一个更高层次的“工作流编排器”。1.1 什么是智能体Agent与多智能体系统Multi-Agent System在HAR的语境下一个智能体是一个具备特定能力如编写Python代码、生成测试、撰写文档的独立执行单元。它通常由一个大语言模型LLM驱动并配备了一系列工具Tools例如读写文件、执行Shell命令、调用API等。智能体能够根据目标、当前上下文和可用工具自主决定下一步行动。多智能体系统则由多个这样的智能体组成它们通过一个协调机制在HAR中就是工作流进行通信与合作共同完成一个超越单个智能体能力的复杂目标。这类似于一个开发团队里面有架构师、后端开发、前端开发、测试工程师和文档工程师各司其职协同工作。1.2 HAR如何工作从YAML定义到工作流执行HAR的工作机制可以概括为“定义-编排-执行”三部曲定义Definition开发者使用YAML或Python来定义一个工作流Workflow。这个工作流文件描述了任务Task最终要达成的目标例如“创建一个用户管理的REST API服务”。智能体Agents参与工作流的成员及其角色如architect、backend_engineer、tester。步骤Steps工作流的具体执行步骤定义了每个步骤由哪个智能体执行、执行什么动作Action、以及步骤之间的依赖关系如上一步的输出作为下一步的输入。编排OrchestrationHAR的核心引擎会解析工作流定义。它负责实例化各个智能体为它们分配合适的LLM如OpenAI GPT-4、Claude、智谱GLM等和工具。按照步骤定义的依赖关系图调度智能体的执行顺序。管理智能体之间的通信传递必要的上下文信息如生成的代码片段、设计文档。执行Execution引擎按序触发每个步骤。智能体被激活后会基于其角色、当前上下文和可用工具生成行动计划并执行。执行结果如新创建的代码文件、测试报告会被记录并传递给后续步骤。这种模式将开发者从繁琐的、线性的任务拆解与执行中解放出来转而专注于更高层次的工作流设计和智能体能力定义。1.3 HAR与相关工具Continue, Codex的定位差异为了避免混淆这里简要对比几个常被一同提及的工具工具/概念核心定位与HAR的关系HAR多智能体工作流编排框架。负责定义、管理和执行由多个AI智能体组成的自动化流程。本体。提供编排能力。ContinueIDE内的AI编码助手插件。在VS Code等环境中提供代码补全、解释、重构等交互式帮助。HAR工作流中的一个智能体可以配置使用Continue的API或类似能力来执行“编写代码”这个动作。HAR是编排者Continue是被调用的“工人”之一。OpenAI Codex强大的代码生成模型。根据自然语言描述生成代码。HAR中的智能体可以配置使用Codex或GPT-4作为其背后的大语言模型LLM来获得代码理解和生成能力。智谱Coding Plan代码规划与生成服务。根据需求生成实现计划和代码。类似于Codex它可以作为HAR中某个智能体如planner或architect的LLM后端。简而言之HAR站在一个更宏观的层面它不直接生成代码而是组织那些能生成代码、运行测试、撰写文档的智能体们有序工作。2. 环境准备与项目初始化要运行HAR你需要一个能够运行Python的环境并准备好LLM的API访问权限。以下步骤将引导你完成基础环境的搭建。2.1 基础环境要求确保你的系统满足以下条件Python: 版本 3.8 或更高。这是运行HAR框架本身所必需的。包管理工具:pip或poetry。本文使用pip。LLM API密钥: 你需要至少一个大型语言模型的API访问权限。HAR支持多种提供商例如OpenAI (GPT-4, GPT-3.5)Anthropic (Claude)智谱AI (GLM)本地模型 (通过Ollama、LM Studio等)代码编辑器: VS Code 是推荐选择因为它有丰富的AI插件生态如Continue便于与HAR工作流中的智能体配合调试。2.2 安装HARHAR可以通过PyPI安装。建议在独立的虚拟环境中进行以避免依赖冲突。# 创建并激活一个Python虚拟环境以venv为例 python -m venv har-env # 在Windows上激活 har-env\Scripts\activate # 在macOS/Linux上激活 source har-env/bin/activate # 安装HAR核心包 pip install har安装完成后可以通过以下命令验证安装是否成功并查看基本帮助信息har --help2.3 配置LLM API密钥HAR需要通过环境变量或配置文件来获取LLM的访问凭证。最安全的方式是使用环境变量。对于OpenAI# 在终端中设置环境变量临时 export OPENAI_API_KEYyour-openai-api-key-here # 在Windows CMD中 set OPENAI_API_KEYyour-openai-api-key-here # 在Windows PowerShell中 $env:OPENAI_API_KEYyour-openai-api-key-here对于智谱AIexport ZHIPUAI_API_KEYyour-zhipuai-api-key-here注意将API密钥直接写在命令行历史或脚本中可能存在安全风险。对于生产环境应使用密钥管理服务或安全的配置注入方式。在本地学习时可以考虑将环境变量写入shell配置文件如~/.bashrc或~/.zshrc但需确保文件权限安全。2.4 初始化你的第一个HAR项目创建一个新的目录作为你的项目空间并在此目录下初始化HAR所需的基本结构。mkdir my-first-har-workflow cd my-first-har-workflowHAR项目通常包含以下核心文件workflow.yaml或workflow.py: 工作流定义文件。agents/目录: 存放自定义智能体的配置或代码。tools/目录: 存放自定义工具的代码。.env文件: 可选用于存储环境变量但需注意不要提交到版本控制。我们首先创建一个最简单的workflow.yaml来验证环境。3. 构建一个多智能体REST API开发工作流我们将创建一个具体的工作流目标是自动生成一个简单的用户管理REST API服务使用FastAPI框架并包含基础测试。这个工作流将涉及三个智能体设计者、开发者和测试者。3.1 定义工作流YAML文件在项目根目录创建user_api_workflow.yaml文件。# user_api_workflow.yaml name: 用户管理API生成工作流 description: 一个由多智能体协作生成FastAPI用户管理服务代码的工作流。 # 定义参与本工作流的智能体 agents: designer: role: 系统架构师 # 指定该智能体使用的LLM模型配置 llm: provider: openai # 使用OpenAI model: gpt-4 # 指定模型为GPT-4 # 智能体可以使用的工具集这里使用HAR内置的文件操作工具 tools: - type: filesystem developer: role: 后端工程师 llm: provider: openai model: gpt-4 tools: - type: filesystem - type: shell # 增加shell工具用于可能需要的包安装命令 tester: role: 测试工程师 llm: provider: openai model: gpt-3.5-turbo # 测试任务相对简单可使用成本更低的模型 tools: - type: filesystem # 定义工作流的执行步骤 steps: - name: 需求分析与设计 agent: designer action: type: prompt # 动作类型执行一个提示词任务 prompt: | 你是一位经验丰富的系统架构师。请为“用户管理”功能设计一个简单的REST API。 要求 1. 使用Python的FastAPI框架。 2. 包含以下端点创建用户、获取用户列表、根据ID获取单个用户、更新用户、删除用户。 3. 用户模型至少包含id (整数, 主键), username (字符串), email (字符串)。 4. 数据暂时使用内存中的列表存储即可无需连接真实数据库。 5. 请将设计思路和API端点规划写到一个Markdown文件中。 请生成一个名为 design.md 的文件包含你的设计文档。 outputs: - path: ./design.md # 指定输出文件路径 - name: 实现核心代码 agent: developer # depends_on 定义了步骤间的依赖关系此步骤需在“需求分析与设计”完成后执行 depends_on: [需求分析与设计] action: type: prompt prompt: | 你是一位专业的Python后端工程师。请根据 design.md 文件中的设计实现完整的FastAPI应用代码。 要求 1. 创建主应用文件 main.py。 2. 实现所有设计好的端点。 3. 代码结构清晰包含必要的导入和注释。 4. 在 main.py 同目录下创建一个 requirements.txt 文件列出项目依赖如fastapi, uvicorn。 请开始实现。 outputs: - path: ./main.py - path: ./requirements.txt - name: 生成单元测试 agent: tester depends_on: [实现核心代码] action: type: prompt prompt: | 你是一位测试工程师。请为 main.py 中的FastAPI用户管理API编写Pytest单元测试。 要求 1. 创建测试文件 test_main.py。 2. 为每个API端点创建、列表、详情、更新、删除编写至少一个测试用例。 3. 使用FastAPI的 TestClient。 4. 确保测试能够独立运行。 请生成测试代码。 outputs: - path: ./test_main.py - name: 验证与总结 agent: developer depends_on: [生成单元测试] action: type: prompt prompt: | 请检查当前目录下生成的所有代码文件main.py, test_main.py, requirements.txt。 1. 尝试模拟安装依赖pip install -r requirements.txt如果shell工具可用。 2. 尝试运行测试pytest test_main.py -v并捕获输出。 3. 将检查结果和测试运行摘要写到一个名为 verification.log 的文件中。 4. 如果发现任何明显错误如语法错误、导入缺失请在日志中说明。 outputs: - path: ./verification.log3.2 关键配置与参数详解这个YAML文件定义了整个工作流的蓝图有几个关键部分需要理解Agents (智能体):role: 定义了智能体的角色这个角色描述会影响LLM的行为模式。llm.provider/model: 指定了驱动该智能体的“大脑”。你可以为不同复杂度的任务分配不同能力的模型以优化成本。tools: 赋予了智能体与外界交互的能力。filesystem工具允许读写文件shell工具允许执行命令行指令。这是智能体能“动手”操作项目文件的基础。Steps (步骤):depends_on: 这是实现工作流编排的关键。它创建了一个有向无环图DAG确保“设计”完成后才“开发”“开发”完成后才“测试”。HAR引擎会解析这些依赖并决定执行顺序。action.type: “prompt”: 这是目前最常见的动作类型即给智能体一个指令Prompt。Prompt的质量直接决定输出结果的质量。好的Prompt应清晰、具体、包含约束条件。outputs: 指定本步骤预期产生的文件。HAR会监控这些文件是否被创建或修改并将其作为步骤完成的标志之一同时文件内容会成为后续步骤的上下文的一部分。上下文传递: 注意在“实现核心代码”步骤的Prompt中我们提到了“根据design.md文件”。HAR引擎会自动将上游步骤“需求分析与设计”的输出文件design.md的路径或内容摘要作为上下文提供给当前步骤的智能体。这是智能体间协作的基础。3.3 运行工作流在终端中确保你位于项目目录my-first-har-workflow下并且已经设置了OPENAI_API_KEY环境变量。然后执行以下命令har run ./user_api_workflow.yamlHAR引擎会开始执行工作流。你将在终端看到详细的日志输出包括正在执行哪个步骤。调用哪个智能体。智能体思考和执行的过程如果日志级别设置得足够详细。每个步骤的执行状态成功、失败。执行完成后检查你的项目目录应该会看到生成的文件my-first-har-workflow/ ├── user_api_workflow.yaml ├── design.md # 设计文档 ├── main.py # FastAPI 应用代码 ├── requirements.txt # 依赖列表 ├── test_main.py # 单元测试 └── verification.log # 验证日志3.4 验证生成结果检查设计文档打开design.md查看架构师智能体是否给出了合理的API设计。检查核心代码打开main.py查看代码结构是否清晰端点是否完整。一个可能生成的main.py示例如下# main.py - 由HAR智能体生成 from fastapi import FastAPI, HTTPException from pydantic import BaseModel from typing import List, Optional app FastAPI(titleUser Management API) # 内存中临时存储 users_db [] current_id 1 class UserCreate(BaseModel): username: str email: str class UserResponse(UserCreate): id: int app.post(/users/, response_modelUserResponse, status_code201) def create_user(user: UserCreate): global current_id new_user UserResponse(idcurrent_id, **user.dict()) users_db.append(new_user) current_id 1 return new_user app.get(/users/, response_modelList[UserResponse]) def get_users(): return users_db app.get(/users/{user_id}, response_modelUserResponse) def get_user(user_id: int): for user in users_db: if user.id user_id: return user raise HTTPException(status_code404, detailUser not found) # ... 更新和删除端点的代码运行测试你可以手动运行生成的测试验证代码是否基本可用。pip install -r requirements.txt pytest test_main.py -v查看验证日志打开verification.log看开发者智能体最后一步的检查结果。4. 常见问题排查与优化在实际运行HAR工作流时你可能会遇到一些问题。以下是典型问题的排查路径。4.1 工作流执行失败排查表问题现象可能原因检查方式处理建议执行har run时报错ModuleNotFoundErrorHAR依赖包未正确安装或虚拟环境未激活。运行 pip listgrep har确认har包是否存在。检查终端提示符是否在虚拟环境中。步骤执行失败日志显示Invalid API KeyLLM API密钥未设置或设置错误。运行echo $OPENAI_API_KEY(或对应变量) 检查是否为空或错误。确认环境变量名称正确并重新设置有效的API密钥。确保在运行har run的同一终端会话中已导出变量。智能体“卡住”或长时间无响应Prompt指令不清晰导致LLM陷入循环或网络超时。查看HAR的详细日志 (har run -v)。检查Prompt是否要求了模糊或开放式的任务。优化Prompt使其目标明确、有明确的终止条件如“生成一个文件”。检查网络连接和LLM服务状态。生成的文件内容不符合预期或质量差1. 使用的LLM模型能力不足。2. Prompt描述不够具体。3. 智能体角色定义不清晰。对比生成的代码和设计文档。检查Prompt中是否包含了足够的约束和示例。1. 为关键步骤如架构设计、核心开发升级到更强的模型如GPT-4。2. 细化Prompt提供更具体的输入输出格式要求。3. 在agent.role中赋予更专业的角色描述。后续步骤无法读取前序步骤生成的文件文件路径在outputs中指定错误或文件未被成功创建。检查工作流YAML中outputs.path的路径是否准确。确认前序步骤日志显示文件已创建。使用相对路径时确保其相对于工作流运行目录。可以在Prompt中明确指示智能体“将输出保存到./xxx文件”。依赖步骤未执行depends_on字段配置错误可能存在循环依赖。检查YAML中各个步骤的name和depends_on的值是否完全匹配包括大小写和空格。确保depends_on中引用的步骤名称与对应步骤的name字段完全一致。绘制简单的步骤依赖图进行检查。4.2 提升工作流质量的实践迭代优化PromptPrompt工程是多智能体工作流成功的关键。不要期望一次写出完美的Prompt。根据首次运行结果不断调整Prompt的清晰度、具体度和约束条件。分而治之细化步骤如果一个步骤的Prompt过于复杂智能体可能无法很好执行。将其拆分为多个更小、更专注的步骤由同一个或不同的智能体完成。例如将“实现核心代码”拆分为“创建数据模型”、“实现CRUD端点”、“添加异常处理”等。利用自定义工具HAR允许你编写Python代码来创建自定义工具。如果你的智能体需要与特定API、数据库或内部系统交互自定义工具是必不可少的。例如可以创建一个git工具让智能体提交代码或创建一个docker工具来构建镜像。引入人工审核节点并非所有步骤都需要全自动。可以在关键节点如设计评审、代码合并前设置需要人工干预的步骤。HAR支持暂停工作流并等待外部输入。管理成本和时长使用GPT-4等高级模型成本较高。在工作流设计时根据任务难度合理分配模型。简单的文档生成、格式化任务可以使用GPT-3.5-turbo核心逻辑设计则使用GPT-4。同时为步骤设置超时限制避免因意外循环导致巨额费用。5. 进阶自定义智能体与工具当基础工作流跑通后你可以通过自定义智能体和工具来扩展HAR的能力使其更贴合你的团队和项目规范。5.1 创建自定义智能体配置你可以将智能体的配置特别是复杂的Prompt模板提取到独立的YAML文件中实现复用。在项目下创建agents/目录并新建senior_backend_agent.yaml。# agents/senior_backend_agent.yaml role: 高级后端工程师精通FastAPI与SQLAlchemy llm: provider: openai model: gpt-4 temperature: 0.2 # 降低随机性使输出更确定 max_tokens: 4000 system_prompt: | 你是一位严谨的高级后端工程师擅长使用FastAPI和SQLAlchemy ORM构建可维护的RESTful服务。 你遵循PEP 8代码规范注重错误处理、日志记录和API文档使用OpenAPI。 在生成代码时你会优先考虑性能、安全性和可测试性。 tools: - type: filesystem - type: shell然后在工作流YAML中引用这个自定义智能体# 在workflow.yaml的agents部分 agents: senior_dev: # 使用 !include 指令引用外部配置 config: !include ./agents/senior_backend_agent.yaml5.2 开发自定义工具假设你需要一个智能体能运行特定的代码质量检查工具如black格式化、ruff检查。你可以创建一个Python工具。在项目下创建tools/目录和code_quality_tool.py。# tools/code_quality_tool.py from har.tools.base import BaseTool from typing import Dict, Any import subprocess import os class CodeQualityTool(BaseTool): name code_quality description 运行代码质量检查black格式化ruff lint def run(self, file_path: str, action: str check) - Dict[str, Any]: 运行代码质量工具。 Args: file_path: 要检查的文件路径。 action: ‘check‘ 仅检查’format‘ 执行格式化。 if not os.path.exists(file_path): return {success: False, error: f文件不存在: {file_path}} results {} # 运行 black if action format: cmd [black, file_path] else: cmd [black, --check, file_path] try: result subprocess.run(cmd, capture_outputTrue, textTrue, timeout30) results[black] { success: result.returncode 0, stdout: result.stdout, stderr: result.stderr } except Exception as e: results[black] {success: False, error: str(e)} # 类似地添加 ruff 检查... # ... return {success: all(r[success] for r in results.values()), details: results}在工作流YAML中注册并使用这个工具。# 在workflow.yaml顶部附近声明自定义工具路径 tool_definitions: - module: tools.code_quality_tool class_name: CodeQualityTool agents: quality_agent: role: 质量保障工程师 llm: {...} tools: - type: filesystem - type: code_quality # 使用自定义工具通过自定义工具你可以将团队内部的任何脚本、流程或标准封装起来让AI智能体代表你去执行极大地扩展了自动化边界。HAR将多智能体协作从理论概念转化为可实践的工程框架。它要求开发者从“编写每一行代码”转变为“设计高效的协作流程和定义清晰的智能体职责”。成功的HAR应用不在于追求全自动而在于找到人机协作的最佳平衡点让AI智能体可靠地处理那些模式固定、定义明确的子任务从而让开发者能更专注于创造性的架构设计和复杂问题求解。从本文的简单示例开始尝试将你日常开发中的重复性任务如生成样板代码、编写基础测试、更新接口文档改造成HAR工作流逐步构建属于你自己团队的AI赋能开发流水线。
在实际的软件开发流程中单个开发者或单一AI助手处理复杂任务时常常会遇到上下文切换频繁、工具链整合困难、任务拆解不彻底等问题。尤其是在面对一个包含需求分析、架构设计、代码实现、测试验证和文档编写的完整项目时手动串联各个环节不仅效率低下而且容易出错。HARHarness for Agentic Workflows作为一个开源框架正是为了解决多智能体Multi-Agent协同编码工作流中的这些痛点而生。它不是一个单一的代码生成工具而是一个用于编排、管理和执行由多个AI智能体构成的自动化工作流的“马具”Harness。本文面向希望将AI深度融入开发流程的工程师、技术负责人以及对多智能体系统Multi-Agent Systems感兴趣的开发者。我们将从零开始理解HAR的核心概念搭建一个基础的多智能体编码环境并通过一个具体的“创建REST API服务”任务演示如何定义工作流、配置智能体并执行最终获得可运行的代码。你将学会如何利用HAR将复杂的开发任务分解并交由不同的专业智能体协作完成从而提升开发的一致性和自动化水平。1. 理解HAR多智能体工作流的编排引擎在深入配置和代码之前必须厘清HAR的核心定位。它不是一个像GitHub Copilot或Codex那样的代码补全模型也不是一个像Continue这样的IDE插件。HAR是一个更高层次的“工作流编排器”。1.1 什么是智能体Agent与多智能体系统Multi-Agent System在HAR的语境下一个智能体是一个具备特定能力如编写Python代码、生成测试、撰写文档的独立执行单元。它通常由一个大语言模型LLM驱动并配备了一系列工具Tools例如读写文件、执行Shell命令、调用API等。智能体能够根据目标、当前上下文和可用工具自主决定下一步行动。多智能体系统则由多个这样的智能体组成它们通过一个协调机制在HAR中就是工作流进行通信与合作共同完成一个超越单个智能体能力的复杂目标。这类似于一个开发团队里面有架构师、后端开发、前端开发、测试工程师和文档工程师各司其职协同工作。1.2 HAR如何工作从YAML定义到工作流执行HAR的工作机制可以概括为“定义-编排-执行”三部曲定义Definition开发者使用YAML或Python来定义一个工作流Workflow。这个工作流文件描述了任务Task最终要达成的目标例如“创建一个用户管理的REST API服务”。智能体Agents参与工作流的成员及其角色如architect、backend_engineer、tester。步骤Steps工作流的具体执行步骤定义了每个步骤由哪个智能体执行、执行什么动作Action、以及步骤之间的依赖关系如上一步的输出作为下一步的输入。编排OrchestrationHAR的核心引擎会解析工作流定义。它负责实例化各个智能体为它们分配合适的LLM如OpenAI GPT-4、Claude、智谱GLM等和工具。按照步骤定义的依赖关系图调度智能体的执行顺序。管理智能体之间的通信传递必要的上下文信息如生成的代码片段、设计文档。执行Execution引擎按序触发每个步骤。智能体被激活后会基于其角色、当前上下文和可用工具生成行动计划并执行。执行结果如新创建的代码文件、测试报告会被记录并传递给后续步骤。这种模式将开发者从繁琐的、线性的任务拆解与执行中解放出来转而专注于更高层次的工作流设计和智能体能力定义。1.3 HAR与相关工具Continue, Codex的定位差异为了避免混淆这里简要对比几个常被一同提及的工具工具/概念核心定位与HAR的关系HAR多智能体工作流编排框架。负责定义、管理和执行由多个AI智能体组成的自动化流程。本体。提供编排能力。ContinueIDE内的AI编码助手插件。在VS Code等环境中提供代码补全、解释、重构等交互式帮助。HAR工作流中的一个智能体可以配置使用Continue的API或类似能力来执行“编写代码”这个动作。HAR是编排者Continue是被调用的“工人”之一。OpenAI Codex强大的代码生成模型。根据自然语言描述生成代码。HAR中的智能体可以配置使用Codex或GPT-4作为其背后的大语言模型LLM来获得代码理解和生成能力。智谱Coding Plan代码规划与生成服务。根据需求生成实现计划和代码。类似于Codex它可以作为HAR中某个智能体如planner或architect的LLM后端。简而言之HAR站在一个更宏观的层面它不直接生成代码而是组织那些能生成代码、运行测试、撰写文档的智能体们有序工作。2. 环境准备与项目初始化要运行HAR你需要一个能够运行Python的环境并准备好LLM的API访问权限。以下步骤将引导你完成基础环境的搭建。2.1 基础环境要求确保你的系统满足以下条件Python: 版本 3.8 或更高。这是运行HAR框架本身所必需的。包管理工具:pip或poetry。本文使用pip。LLM API密钥: 你需要至少一个大型语言模型的API访问权限。HAR支持多种提供商例如OpenAI (GPT-4, GPT-3.5)Anthropic (Claude)智谱AI (GLM)本地模型 (通过Ollama、LM Studio等)代码编辑器: VS Code 是推荐选择因为它有丰富的AI插件生态如Continue便于与HAR工作流中的智能体配合调试。2.2 安装HARHAR可以通过PyPI安装。建议在独立的虚拟环境中进行以避免依赖冲突。# 创建并激活一个Python虚拟环境以venv为例 python -m venv har-env # 在Windows上激活 har-env\Scripts\activate # 在macOS/Linux上激活 source har-env/bin/activate # 安装HAR核心包 pip install har安装完成后可以通过以下命令验证安装是否成功并查看基本帮助信息har --help2.3 配置LLM API密钥HAR需要通过环境变量或配置文件来获取LLM的访问凭证。最安全的方式是使用环境变量。对于OpenAI# 在终端中设置环境变量临时 export OPENAI_API_KEYyour-openai-api-key-here # 在Windows CMD中 set OPENAI_API_KEYyour-openai-api-key-here # 在Windows PowerShell中 $env:OPENAI_API_KEYyour-openai-api-key-here对于智谱AIexport ZHIPUAI_API_KEYyour-zhipuai-api-key-here注意将API密钥直接写在命令行历史或脚本中可能存在安全风险。对于生产环境应使用密钥管理服务或安全的配置注入方式。在本地学习时可以考虑将环境变量写入shell配置文件如~/.bashrc或~/.zshrc但需确保文件权限安全。2.4 初始化你的第一个HAR项目创建一个新的目录作为你的项目空间并在此目录下初始化HAR所需的基本结构。mkdir my-first-har-workflow cd my-first-har-workflowHAR项目通常包含以下核心文件workflow.yaml或workflow.py: 工作流定义文件。agents/目录: 存放自定义智能体的配置或代码。tools/目录: 存放自定义工具的代码。.env文件: 可选用于存储环境变量但需注意不要提交到版本控制。我们首先创建一个最简单的workflow.yaml来验证环境。3. 构建一个多智能体REST API开发工作流我们将创建一个具体的工作流目标是自动生成一个简单的用户管理REST API服务使用FastAPI框架并包含基础测试。这个工作流将涉及三个智能体设计者、开发者和测试者。3.1 定义工作流YAML文件在项目根目录创建user_api_workflow.yaml文件。# user_api_workflow.yaml name: 用户管理API生成工作流 description: 一个由多智能体协作生成FastAPI用户管理服务代码的工作流。 # 定义参与本工作流的智能体 agents: designer: role: 系统架构师 # 指定该智能体使用的LLM模型配置 llm: provider: openai # 使用OpenAI model: gpt-4 # 指定模型为GPT-4 # 智能体可以使用的工具集这里使用HAR内置的文件操作工具 tools: - type: filesystem developer: role: 后端工程师 llm: provider: openai model: gpt-4 tools: - type: filesystem - type: shell # 增加shell工具用于可能需要的包安装命令 tester: role: 测试工程师 llm: provider: openai model: gpt-3.5-turbo # 测试任务相对简单可使用成本更低的模型 tools: - type: filesystem # 定义工作流的执行步骤 steps: - name: 需求分析与设计 agent: designer action: type: prompt # 动作类型执行一个提示词任务 prompt: | 你是一位经验丰富的系统架构师。请为“用户管理”功能设计一个简单的REST API。 要求 1. 使用Python的FastAPI框架。 2. 包含以下端点创建用户、获取用户列表、根据ID获取单个用户、更新用户、删除用户。 3. 用户模型至少包含id (整数, 主键), username (字符串), email (字符串)。 4. 数据暂时使用内存中的列表存储即可无需连接真实数据库。 5. 请将设计思路和API端点规划写到一个Markdown文件中。 请生成一个名为 design.md 的文件包含你的设计文档。 outputs: - path: ./design.md # 指定输出文件路径 - name: 实现核心代码 agent: developer # depends_on 定义了步骤间的依赖关系此步骤需在“需求分析与设计”完成后执行 depends_on: [需求分析与设计] action: type: prompt prompt: | 你是一位专业的Python后端工程师。请根据 design.md 文件中的设计实现完整的FastAPI应用代码。 要求 1. 创建主应用文件 main.py。 2. 实现所有设计好的端点。 3. 代码结构清晰包含必要的导入和注释。 4. 在 main.py 同目录下创建一个 requirements.txt 文件列出项目依赖如fastapi, uvicorn。 请开始实现。 outputs: - path: ./main.py - path: ./requirements.txt - name: 生成单元测试 agent: tester depends_on: [实现核心代码] action: type: prompt prompt: | 你是一位测试工程师。请为 main.py 中的FastAPI用户管理API编写Pytest单元测试。 要求 1. 创建测试文件 test_main.py。 2. 为每个API端点创建、列表、详情、更新、删除编写至少一个测试用例。 3. 使用FastAPI的 TestClient。 4. 确保测试能够独立运行。 请生成测试代码。 outputs: - path: ./test_main.py - name: 验证与总结 agent: developer depends_on: [生成单元测试] action: type: prompt prompt: | 请检查当前目录下生成的所有代码文件main.py, test_main.py, requirements.txt。 1. 尝试模拟安装依赖pip install -r requirements.txt如果shell工具可用。 2. 尝试运行测试pytest test_main.py -v并捕获输出。 3. 将检查结果和测试运行摘要写到一个名为 verification.log 的文件中。 4. 如果发现任何明显错误如语法错误、导入缺失请在日志中说明。 outputs: - path: ./verification.log3.2 关键配置与参数详解这个YAML文件定义了整个工作流的蓝图有几个关键部分需要理解Agents (智能体):role: 定义了智能体的角色这个角色描述会影响LLM的行为模式。llm.provider/model: 指定了驱动该智能体的“大脑”。你可以为不同复杂度的任务分配不同能力的模型以优化成本。tools: 赋予了智能体与外界交互的能力。filesystem工具允许读写文件shell工具允许执行命令行指令。这是智能体能“动手”操作项目文件的基础。Steps (步骤):depends_on: 这是实现工作流编排的关键。它创建了一个有向无环图DAG确保“设计”完成后才“开发”“开发”完成后才“测试”。HAR引擎会解析这些依赖并决定执行顺序。action.type: “prompt”: 这是目前最常见的动作类型即给智能体一个指令Prompt。Prompt的质量直接决定输出结果的质量。好的Prompt应清晰、具体、包含约束条件。outputs: 指定本步骤预期产生的文件。HAR会监控这些文件是否被创建或修改并将其作为步骤完成的标志之一同时文件内容会成为后续步骤的上下文的一部分。上下文传递: 注意在“实现核心代码”步骤的Prompt中我们提到了“根据design.md文件”。HAR引擎会自动将上游步骤“需求分析与设计”的输出文件design.md的路径或内容摘要作为上下文提供给当前步骤的智能体。这是智能体间协作的基础。3.3 运行工作流在终端中确保你位于项目目录my-first-har-workflow下并且已经设置了OPENAI_API_KEY环境变量。然后执行以下命令har run ./user_api_workflow.yamlHAR引擎会开始执行工作流。你将在终端看到详细的日志输出包括正在执行哪个步骤。调用哪个智能体。智能体思考和执行的过程如果日志级别设置得足够详细。每个步骤的执行状态成功、失败。执行完成后检查你的项目目录应该会看到生成的文件my-first-har-workflow/ ├── user_api_workflow.yaml ├── design.md # 设计文档 ├── main.py # FastAPI 应用代码 ├── requirements.txt # 依赖列表 ├── test_main.py # 单元测试 └── verification.log # 验证日志3.4 验证生成结果检查设计文档打开design.md查看架构师智能体是否给出了合理的API设计。检查核心代码打开main.py查看代码结构是否清晰端点是否完整。一个可能生成的main.py示例如下# main.py - 由HAR智能体生成 from fastapi import FastAPI, HTTPException from pydantic import BaseModel from typing import List, Optional app FastAPI(titleUser Management API) # 内存中临时存储 users_db [] current_id 1 class UserCreate(BaseModel): username: str email: str class UserResponse(UserCreate): id: int app.post(/users/, response_modelUserResponse, status_code201) def create_user(user: UserCreate): global current_id new_user UserResponse(idcurrent_id, **user.dict()) users_db.append(new_user) current_id 1 return new_user app.get(/users/, response_modelList[UserResponse]) def get_users(): return users_db app.get(/users/{user_id}, response_modelUserResponse) def get_user(user_id: int): for user in users_db: if user.id user_id: return user raise HTTPException(status_code404, detailUser not found) # ... 更新和删除端点的代码运行测试你可以手动运行生成的测试验证代码是否基本可用。pip install -r requirements.txt pytest test_main.py -v查看验证日志打开verification.log看开发者智能体最后一步的检查结果。4. 常见问题排查与优化在实际运行HAR工作流时你可能会遇到一些问题。以下是典型问题的排查路径。4.1 工作流执行失败排查表问题现象可能原因检查方式处理建议执行har run时报错ModuleNotFoundErrorHAR依赖包未正确安装或虚拟环境未激活。运行 pip listgrep har确认har包是否存在。检查终端提示符是否在虚拟环境中。步骤执行失败日志显示Invalid API KeyLLM API密钥未设置或设置错误。运行echo $OPENAI_API_KEY(或对应变量) 检查是否为空或错误。确认环境变量名称正确并重新设置有效的API密钥。确保在运行har run的同一终端会话中已导出变量。智能体“卡住”或长时间无响应Prompt指令不清晰导致LLM陷入循环或网络超时。查看HAR的详细日志 (har run -v)。检查Prompt是否要求了模糊或开放式的任务。优化Prompt使其目标明确、有明确的终止条件如“生成一个文件”。检查网络连接和LLM服务状态。生成的文件内容不符合预期或质量差1. 使用的LLM模型能力不足。2. Prompt描述不够具体。3. 智能体角色定义不清晰。对比生成的代码和设计文档。检查Prompt中是否包含了足够的约束和示例。1. 为关键步骤如架构设计、核心开发升级到更强的模型如GPT-4。2. 细化Prompt提供更具体的输入输出格式要求。3. 在agent.role中赋予更专业的角色描述。后续步骤无法读取前序步骤生成的文件文件路径在outputs中指定错误或文件未被成功创建。检查工作流YAML中outputs.path的路径是否准确。确认前序步骤日志显示文件已创建。使用相对路径时确保其相对于工作流运行目录。可以在Prompt中明确指示智能体“将输出保存到./xxx文件”。依赖步骤未执行depends_on字段配置错误可能存在循环依赖。检查YAML中各个步骤的name和depends_on的值是否完全匹配包括大小写和空格。确保depends_on中引用的步骤名称与对应步骤的name字段完全一致。绘制简单的步骤依赖图进行检查。4.2 提升工作流质量的实践迭代优化PromptPrompt工程是多智能体工作流成功的关键。不要期望一次写出完美的Prompt。根据首次运行结果不断调整Prompt的清晰度、具体度和约束条件。分而治之细化步骤如果一个步骤的Prompt过于复杂智能体可能无法很好执行。将其拆分为多个更小、更专注的步骤由同一个或不同的智能体完成。例如将“实现核心代码”拆分为“创建数据模型”、“实现CRUD端点”、“添加异常处理”等。利用自定义工具HAR允许你编写Python代码来创建自定义工具。如果你的智能体需要与特定API、数据库或内部系统交互自定义工具是必不可少的。例如可以创建一个git工具让智能体提交代码或创建一个docker工具来构建镜像。引入人工审核节点并非所有步骤都需要全自动。可以在关键节点如设计评审、代码合并前设置需要人工干预的步骤。HAR支持暂停工作流并等待外部输入。管理成本和时长使用GPT-4等高级模型成本较高。在工作流设计时根据任务难度合理分配模型。简单的文档生成、格式化任务可以使用GPT-3.5-turbo核心逻辑设计则使用GPT-4。同时为步骤设置超时限制避免因意外循环导致巨额费用。5. 进阶自定义智能体与工具当基础工作流跑通后你可以通过自定义智能体和工具来扩展HAR的能力使其更贴合你的团队和项目规范。5.1 创建自定义智能体配置你可以将智能体的配置特别是复杂的Prompt模板提取到独立的YAML文件中实现复用。在项目下创建agents/目录并新建senior_backend_agent.yaml。# agents/senior_backend_agent.yaml role: 高级后端工程师精通FastAPI与SQLAlchemy llm: provider: openai model: gpt-4 temperature: 0.2 # 降低随机性使输出更确定 max_tokens: 4000 system_prompt: | 你是一位严谨的高级后端工程师擅长使用FastAPI和SQLAlchemy ORM构建可维护的RESTful服务。 你遵循PEP 8代码规范注重错误处理、日志记录和API文档使用OpenAPI。 在生成代码时你会优先考虑性能、安全性和可测试性。 tools: - type: filesystem - type: shell然后在工作流YAML中引用这个自定义智能体# 在workflow.yaml的agents部分 agents: senior_dev: # 使用 !include 指令引用外部配置 config: !include ./agents/senior_backend_agent.yaml5.2 开发自定义工具假设你需要一个智能体能运行特定的代码质量检查工具如black格式化、ruff检查。你可以创建一个Python工具。在项目下创建tools/目录和code_quality_tool.py。# tools/code_quality_tool.py from har.tools.base import BaseTool from typing import Dict, Any import subprocess import os class CodeQualityTool(BaseTool): name code_quality description 运行代码质量检查black格式化ruff lint def run(self, file_path: str, action: str check) - Dict[str, Any]: 运行代码质量工具。 Args: file_path: 要检查的文件路径。 action: ‘check‘ 仅检查’format‘ 执行格式化。 if not os.path.exists(file_path): return {success: False, error: f文件不存在: {file_path}} results {} # 运行 black if action format: cmd [black, file_path] else: cmd [black, --check, file_path] try: result subprocess.run(cmd, capture_outputTrue, textTrue, timeout30) results[black] { success: result.returncode 0, stdout: result.stdout, stderr: result.stderr } except Exception as e: results[black] {success: False, error: str(e)} # 类似地添加 ruff 检查... # ... return {success: all(r[success] for r in results.values()), details: results}在工作流YAML中注册并使用这个工具。# 在workflow.yaml顶部附近声明自定义工具路径 tool_definitions: - module: tools.code_quality_tool class_name: CodeQualityTool agents: quality_agent: role: 质量保障工程师 llm: {...} tools: - type: filesystem - type: code_quality # 使用自定义工具通过自定义工具你可以将团队内部的任何脚本、流程或标准封装起来让AI智能体代表你去执行极大地扩展了自动化边界。HAR将多智能体协作从理论概念转化为可实践的工程框架。它要求开发者从“编写每一行代码”转变为“设计高效的协作流程和定义清晰的智能体职责”。成功的HAR应用不在于追求全自动而在于找到人机协作的最佳平衡点让AI智能体可靠地处理那些模式固定、定义明确的子任务从而让开发者能更专注于创造性的架构设计和复杂问题求解。从本文的简单示例开始尝试将你日常开发中的重复性任务如生成样板代码、编写基础测试、更新接口文档改造成HAR工作流逐步构建属于你自己团队的AI赋能开发流水线。
![【Bug已解决】[modular] ensure branch-specific input defaults 解决方案](http://pic.xiahunao.cn/yaotu/【Bug已解决】[modular] ensure branch-specific input defaults 解决方案)
