1. 项目概述当Hy3遇上WorkBuddy最近在AI智能体Agent的圈子里一个组合开始被频繁提及Hy3 WorkBuddy。不少开发者尝试后给出的评价是“效果惊艳”甚至有人称之为“国产顶级Agent”的潜力配方。这让我这个老码农也来了兴趣决定亲自上手从环境搭建到提示词调优完整地走一遍这个流程看看它到底是不是名副其实。简单来说这个组合的核心思路是利用Hy3这个强大的开源大语言模型作为“大脑”负责理解、规划和决策而WorkBuddy则作为一套功能丰富的“工具箱”和“执行框架”为Hy3提供调用外部API、处理文件、管理记忆和状态的能力。两者结合目标就是打造一个能真正理解复杂指令、自主拆解任务、并调用合适工具去执行的智能助理。它适合那些已经厌倦了简单问答式AI希望构建能够处理多步骤、跨平台实际任务的开发者、产品经理或技术爱好者。比如让它“帮我分析一下上周的销售数据做成图表然后总结要点发邮件给团队”它就能自己规划步骤依次调用数据分析、图表生成和邮件发送等功能。接下来我会把我从零开始搭建、调试到最终跑通一个实用Agent的全过程包括踩过的坑和总结出的高效提示词毫无保留地分享出来。你会发现打造一个“聪明”的Agent关键不仅在于模型本身更在于如何为它设计一套清晰的“行为准则”和“工具使用说明书”。2. 核心组件深度解析为什么是它们在动手之前我们必须先吃透手里的“武器”。Hy3和WorkBuddy各自扮演什么角色它们的优势在哪理解了这些后续的配置和调优才能有的放矢。2.1 Hy3模型为何选择它作为“大脑”Hy3并非一个单一的模型而是一个模型系列通常指代性能较强、适合作为智能体核心的版本例如DeepSeek-V3或相关变体。选择它是基于几个非常实际的考量第一强大的推理与规划能力。Agent的核心是“思考”即根据用户目标拆解出子任务并规划执行路径。Hy3系列模型在数学推理、代码生成和逻辑链条理解上表现突出这恰恰是任务规划Planning环节最需要的能力。相比一些更侧重于对话流畅度的模型Hy3在遇到“请先查询天气如果下雨就提醒我带伞并预约出租车如果晴天则制定一份公园散步路线”这类复杂指令时表现出更好的步骤分解准确性。第二对长上下文的支持。一个实用的Agent需要记忆对话历史、工具调用结果和自身的状态。Hy3模型通常支持128K甚至更长的上下文窗口。这意味着我们可以把复杂的系统提示词即Agent的“人格设定”和“操作手册”、多轮对话历史、以及多个工具的输出结果都塞进上下文而不用担心早期信息被遗忘。这是实现连贯、长期对话助理的基础。第三优秀的指令遵循Instruction Following能力。这可能是最关键的一点。我们需要模型严格地按照我们设定的格式比如必须用特定的JSON结构来调用工具来输出。Hy3在训练中对指令的遵循度较高减少了“模型自由发挥、不按套路出牌”的情况这对于需要稳定对接工具的自动化流程至关重要。第四开源与可及性。作为国产开源模型的优秀代表其获取和使用成本相对友好社区活跃遇到问题也容易找到讨论和解决方案。这对于我们进行实验和开发来说减少了前期障碍。注意模型领域迭代极快“Hy3”作为一个非正式称呼可能指向不同时期的具体模型。在实践时建议关注DeepSeek官方发布的最新版本并查阅其技术报告确认其在工具调用Function Calling和指令遵循方面的量化评估结果。2.2 WorkBuddy框架智能体的“手和脚”如果说Hy3是大脑那么WorkBuddy就是让大脑想法得以实现的身体。它是一个AI智能体开发框架核心解决了Agent领域的几个经典难题1. 工具抽象与管理WorkBuddy将各种能力搜索、计算、读写文件、调用API封装成统一的“工具”Tool。开发者可以像搭积木一样将自己需要的工具注册到框架中。框架负责向模型描述这些工具的功能、输入参数并接收模型的调用请求转换为实际的代码执行。2. 状态与记忆管理Agent在运行中会有状态例如当前正在执行的任务步骤和记忆之前的对话和结果。WorkBuddy提供了会话Session和记忆Memory模块来管理这些信息确保Agent在多轮交互中保持上下文感知。3. 执行流程控制这是WorkBuddy的精华所在。它实现了ReActReasoning Acting等经典Agent执行循环。简单说这个循环是“思考分析当前状况和任务- 决定是调用工具还是直接回答用户- 执行调用工具并获取结果- 观察将结果纳入思考”如此循环直到任务完成。WorkBuddy帮我们固化了这个循环逻辑我们只需要关心提供什么工具以及如何引导模型思考。4. 易于扩展与集成它的架构通常设计得比较清晰允许开发者很方便地添加自定义工具。无论是连接内部业务系统还是接入一个新的第三方API都可以通过编写一个符合规范的Python类来实现。WorkBuddy与类似框架如LangChain, AutoGen的对比WorkBuddy的一个特点是可能更强调“开箱即用”和对国产模型生态的友好集成。它的设计可能更贴近国内开发者的使用习惯文档和示例也以中文为主降低了学习门槛。而LangChain生态更庞大组件更多但复杂度也更高。选择WorkBuddy意味着在构建专注于任务执行、且希望快速上手的Agent时可能会更轻快、直接。3. 环境搭建与基础配置实战理论说得再多不如动手跑通。这一部分我会带你一步步搭建起Hy3 WorkBuddy的运行环境并完成一个最基础的“Hello Agent”示例。3.1 准备工作与依赖安装首先确保你的开发环境是Python 3.9以上。我强烈建议使用虚拟环境来管理依赖避免包冲突。# 创建并激活虚拟环境以venv为例 python -m venv hy3_workbuddy_env source hy3_workbuddy_env/bin/activate # Linux/macOS # hy3_workbuddy_env\Scripts\activate # Windows # 安装核心依赖 pip install -U pip接下来安装WorkBuddy框架。由于WorkBuddy可能是一个相对较新的项目最可靠的方式是从其官方Git仓库安装。# 假设WorkBuddy的仓库地址请以官方文档为准 # pip install githttps://github.com/workbuddy-team/workbuddy.git # 或者如果它已上传至PyPI # pip install workbuddy为了对接Hy3模型我们需要安装对应的SDK。这里以DeepSeek为例pip install openai # DeepSeek的API通常兼容OpenAI SDK格式实操心得在安装这类较新的框架时最常遇到的问题是依赖冲突。如果安装失败先别急着折腾仔细看错误信息。很多时候是因为某个依赖包的版本要求太新或太旧。可以尝试先单独安装框架声明的主要依赖如fastapi,pydantic等的常见稳定版本再安装框架本身。查阅项目的requirements.txt或pyproject.toml文件是解决问题的捷径。3.2 获取并配置模型API密钥你需要一个Hy3模型如DeepSeek的API访问权限。前往对应平台的官网注册账号并获取API Key。创建一个名为.env的文件来管理你的密钥避免硬编码在代码中# .env 文件 DEEPSEEK_API_KEYyour_deepseek_api_key_here DEEPSEEK_API_BASEhttps://api.deepseek.com # 以DeepSeek官方地址为例在Python代码中使用python-dotenv来加载配置pip install python-dotenv# config.py import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 DEEPSEEK_API_KEY os.getenv(DEEPSEEK_API_KEY) DEEPSEEK_API_BASE os.getenv(DEEPSEEK_API_BASE, https://api.deepseek.com)3.3 编写第一个智能体让AI做道数学题现在我们来创建一个最简单的Agent它只使用一个内置工具——计算器。这个例子能帮你理解WorkBuddy最核心的工作流程。# simple_agent.py import asyncio from workbuddy import Agent, Runner # 假设这是导入方式具体以官方文档为准 from workbuddy.tools import CalculatorTool from openai import OpenAI # 1. 配置模型客户端 client OpenAI( api_keyDEEPSEEK_API_KEY, base_urlDEEPSEEK_API_BASE /v1, # 适配OpenAI格式的端点 ) # 2. 创建工具实例 calculator CalculatorTool() # 3. 定义系统提示词Agent的“人格”和“指令” system_prompt 你是一个专业的数学助手。你的任务是帮助用户解决数学问题。 你必须遵循以下规则 1. 仔细分析用户的问题。 2. 如果需要计算你必须使用calculator工具。 3. 使用工具后将工具返回的结果整合到你的回答中用清晰的语言向用户解释。 4. 如果用户的问题不需要计算请直接回答。 记住不要尝试自己心算一定要使用工具 # 4. 创建Agent agent Agent( nameMathBot, system_promptsystem_prompt, model_clientclient, # 传入配置好的客户端 model_namedeepseek-chat, # 指定模型名称 tools[calculator], # 赋予Agent可用的工具 ) # 5. 创建运行器并执行 async def main(): runner Runner(agentagent) # 用户提问一个复杂计算 user_query “请计算 (15的平方根加上28) 再乘以 3.14 等于多少结果保留两位小数。” print(f用户: {user_query}) async for chunk in runner.run_stream(user_query): # 这里会流式输出Agent的“思考过程”和最终回答 if hasattr(chunk, content) and chunk.content: print(chunk.content, end, flushTrue) print() # 换行 if __name__ __main__: asyncio.run(main())运行这个脚本你会看到Agent的输出可能类似这样用户: 请计算 (15的平方根加上28) 再乘以 3.14 等于多少结果保留两位小数。 思考用户需要一个复合计算。我需要先计算15的平方根加上28再乘以3.14。我应该使用计算器工具。 行动调用calculator工具计算 sqrt(15)。 工具调用过程... 观察sqrt(15) 的结果约为 3.872983346207417。 思考现在需要将结果加上283.872983346207417 28。 行动调用calculator工具计算 3.872983346207417 28。 工具调用过程... 观察和为 31.872983346207417。 思考最后将这个和乘以3.14。 行动调用calculator工具计算 31.872983346207417 * 3.14。 工具调用过程... 观察乘积为 100.08016970709128。 思考现在需要保留两位小数。 行动调用calculator工具对 100.08016970709128 进行四舍五入到两位小数。 工具调用过程... 观察四舍五入后结果为 100.08。 最终回答根据计算(√15 28) × 3.14 的结果约为 100.08。计算过程是√15 ≈ 3.873加上28得31.873再乘以3.14得到100.08保留两位小数。这个过程清晰地展示了ReAct循环思考 - 行动调用工具- 观察 - 再思考。虽然只是一个计算器但你已经创建了一个能自主使用工具完成任务的智能体。注意事项初次运行你可能会遇到导入错误ModuleNotFoundError: No module named workbuddy。这通常意味着WorkBuddy的包名或安装方式与示例假设不同。请务必以该项目的官方GitHub仓库或文档的快速开始Quick Start指南为准。上面的代码是一个基于常见Agent框架模式的示意你需要根据WorkBuddy的实际API进行调整。4. 构建多功能智能体提示词设计与工具集成一个只会算数的Agent显然不够看。我们的目标是打造一个“顶级助手”这意味着它需要掌握多种技能。这部分的重点有两个一是设计一个强大、严谨的系统提示词这是Agent的“灵魂”二是集成更多实用的工具。4.1 系统提示词工程定义Agent的行为准则系统提示词是引导模型行为最关键的部分。一个糟糕的提示词会让强大的模型表现得像个傻瓜。下面我分享一个经过多次迭代、相对通用的“强指令遵循型”提示词模板你可以在此基础上修改。advanced_system_prompt # 角色与核心指令 你是WorkBuddy一个全能型AI工作助理。你的核心驱动力是**准确理解用户目标并高效、可靠地完成它**。 ## 通用行为准则 1. **绝对诚实**知道就说知道不知道就承认不知道绝不自作聪明编造信息。 2. **分步思考**对于复杂任务必须在内心或输出中展示你的思考链Chain-of-Thought。先理解再规划后执行。 3. **主动确认**当用户指令模糊、存在歧义或可能产生重大影响时如删除文件、发送邮件必须主动向用户澄清确认直到完全明确。 4. **结果导向**你的最终输出必须是针对用户问题的、完整的、可直接使用的答案或成果而非中间过程。 ## 工具使用规范 你被赋予了以下工具{tool_list}。使用工具是你完成任务的主要方式。 1. **必要性判断**只有当任务需要你获取外部信息、执行计算、操作文件或系统时才调用工具。纯知识性、推理性或聊天性任务请直接运用你的知识回答。 2. **精准调用**调用工具时必须严格遵循每个工具定义的参数格式和类型。仔细检查你提供的参数值是否合理。 3. **结果整合**获得工具返回结果后你必须分析该结果并将其**自然、流畅地整合**到你对用户的最终回复中。不要直接抛出原始的、未处理的工具输出。 4. **序列与依赖**如果任务需要多个工具且步骤间有依赖关系如先搜索再总结请按逻辑顺序依次调用。你可以规划多个步骤但一次只执行一个工具调用。 ## 输出格式要求 你的所有响应都必须采用以下JSON格式 json { “thoughts”: { “reasoning”: “你当前的思考过程分析用户意图和下一步计划。, “plan”: [“步骤1...”, “步骤2...”], “criticism”: “对当前想法潜在问题的自我审视。, “speak”: “你打算对用户说的下一句话用于流式输出时的自然语言反馈” }, “action”: { “name”: “要调用的工具名称如无需调用则为 null, “args”: {“arg1”: “value1”, ...} // 工具参数如无需调用则为 {} } }重要这是你与框架的通信协议必须严格遵守。框架会解析你的action字段来调用工具并将工具结果反馈给你开启下一轮循环。对话管理记忆你可以访问之前的对话历史。请利用历史来理解上下文避免重复提问。状态如果你正在执行一个多步骤任务请在思考中明确当前进度。现在开始工作。你的目标是成为用户最得力的伙伴。 这个提示词做了几件关键事 1. **明确角色和核心目标**定下基调。 2. **制定行为准则**确保Agent可靠、安全。 3. **严格规范工具使用**这是避免Agent乱用或不用工具的关键。 4. **强制结构化输出**通过JSON格式牢牢控制模型的输出使其易于被程序解析。这是实现稳定自动化交互的基石。 5. **管理对话**让Agent有“记忆”。 **实操心得** 提示词中的 {tool_list} 是一个占位符。在实际程序中应该在创建Agent前用程序自动将已注册的工具名称和描述填充进去。这样Agent就能动态知道它有什么工具可用。很多框架会帮你自动完成这一步。 ### 4.2 集成实用工具搜索、文件与网络 让我们为Agent装备更多“武器”。这里以集成一个网页搜索工具和一个文件读取工具为例。 首先你需要注册相关服务的API如Serper或SearXNG用于搜索。 python # advanced_agent.py import asyncio import json from pathlib import Path from workbuddy import Agent, Runner from workbuddy.tools import BaseTool # 假设BaseTool是基类 from openai import OpenAI import aiohttp # 用于异步HTTP请求 import os from dotenv import load_dotenv load_dotenv() # --- 1. 自定义工具网页搜索工具 --- class WebSearchTool(BaseTool): name “web_search” description “在互联网上搜索实时信息。当你需要获取最新新闻、事实核查、或未知领域信息时使用此工具。” parameters { “type”: “object”, “properties”: { “query”: { “type”: “string”, “description”: “要搜索的关键词或问题尽量简洁明确。” } }, “required”: [“query”] } async def run(self, query: str): 执行搜索 api_key os.getenv(“SERPER_API_KEY”) # 假设使用Serper.dev url “https://google.serper.dev/search” headers { ‘X-API-KEY’: api_key, ‘Content-Type’: ‘application/json’ } payload json.dumps({“q”: query}) async with aiohttp.ClientSession() as session: async with session.post(url, headersheaders, datapayload) as response: if response.status 200: data await response.json() # 简化处理只返回前几条结果的摘要 snippets [item.get(‘snippet’, ‘’) for item in data.get(‘organic’, [])[:3]] return f“搜索 ‘{query}’ 的结果摘要\n” “\n”.join([f“{i1}. {s}” for i, s in enumerate(snippets)]) else: return f“搜索失败状态码{response.status}” # --- 2. 自定义工具文件读取工具 --- class ReadFileTool(BaseTool): name “read_file” description “读取本地文本文件的内容。用于分析代码、日志、文档等。” parameters { “type”: “object”, “properties”: { “file_path”: { “type”: “string”, “description”: “要读取的文件的绝对路径或相对于当前工作目录的路径。” } }, “required”: [“file_path”] } async def run(self, file_path: str): 读取文件内容 path Path(file_path) if not path.exists(): return f“错误文件 ‘{file_path}’ 不存在。” if not path.is_file(): return f“错误’{file_path}’ 不是一个文件。” try: # 注意这里简单处理只读文本。对于大文件可能需要分块读取。 content path.read_text(encoding‘utf-8’) return f“文件 ‘{file_path}’ 的内容如下\n\n{content[:2000]}...\n\n(显示前2000字符)” except Exception as e: return f“读取文件时出错{str(e)}” # --- 3. 配置与运行 --- client OpenAI(api_keyos.getenv(“DEEPSEEK_API_KEY”), base_urlos.getenv(“DEEPSEEK_API_BASE”) “/v1”) # 创建工具实例 search_tool WebSearchTool() read_tool ReadFileTool() # 可以继续添加更多工具如 CalculatorTool() # 动态生成工具列表描述 tool_descriptions “\n”.join([f“- **{tool.name}**: {tool.description}” for tool in [search_tool, read_tool]]) final_system_prompt advanced_system_prompt.format(tool_listtool_descriptions) # 创建高级Agent advanced_agent Agent( name“WorkBuddyPro”, system_promptfinal_system_prompt, model_clientclient, model_name“deepseek-chat”, tools[search_tool, read_tool], ) async def run_advanced_agent(): runner Runner(agentadvanced_agent) # 示例对话 queries [ “今天科技圈有什么重要新闻吗”, “请帮我读一下当前目录下的 ‘README.md’ 文件并总结它的主要内容。” ] for query in queries: print(f“\n{*50}”) print(f“用户: {query}”) print(f“{*50}”) full_response “” async for chunk in runner.run_stream(query): # 在实际框架中chunk可能是包含thoughts和action的复杂对象 # 这里简化处理假设能直接获取文本内容 if hasattr(chunk, ‘content’): print(chunk.content, end‘’, flushTrue) full_response chunk.content elif isinstance(chunk, dict): # 如果是结构化数据 # 可以解析并漂亮地打印 thoughts if ‘thoughts’ in chunk: print(f“\n[思考] {chunk[‘thoughts’].get(‘reasoning’, ‘’)}”) if ‘action’ in chunk and chunk[‘action’].get(‘name’): print(f“\n[行动] 调用工具: {chunk[‘action’][‘name’]} 参数: {chunk[‘action’][‘args’]}”) print() # 这里可以保存对话历史等 if __name__ “__main__”: asyncio.run(run_advanced_agent())通过这样的集成你的Agent就具备了获取实时信息和读取本地文件的能力。你可以继续添加更多工具比如发送邮件的EmailTool、查询数据库的DBQueryTool、执行Shell命令的CommandTool需极其谨慎注意安全等等。5. 高级技巧与避坑指南走到这一步一个基础的多功能Agent已经搭建完成。但要让它变得“顶级”和“可靠”还需要一些高级技巧并避开常见的陷阱。5.1 优化提示词以提升工具调用准确性即使有了好的提示词模板模型有时仍会“叛逆”——不调用工具或者调用时参数错误。以下是一些微调技巧少样本示例Few-Shot在系统提示词中直接给出1-2个工具调用的完美示例。这比单纯描述规则有效得多。示例 用户 “北京现在的天气怎么样” 你的思考内部用户需要实时天气信息我需要使用搜索工具。 你的输出必须遵守的JSON格式 { “thoughts”: { “reasoning”: “用户询问北京实时天气这是一个需要最新外部信息的问题我应该使用web_search工具。”, “plan”: [“步骤1使用web_search搜索‘北京 当前 天气’。”], “speak”: “我来为您查询一下北京的实时天气。” }, “action”: { “name”: “web_search”, “args”: {“query”: “北京 当前 天气 实时”} } }强化格式强调在提示词中用非常醒目的方式强调输出格式比如用json ...包裹并加上“必须”、“严格”等词语。指定思考框架明确要求模型按照“理解问题 - 检查是否需要工具 - 选择正确工具 - 确认参数 - 执行”的流程进行内部思考并将这个流程体现在thoughts.reasoning中。温度Temperature参数在调用模型API时将温度参数设置为较低的值如0.1或0.2。较低的温度会使模型的输出更加确定性和可预测更倾向于遵循指令和既定格式减少“创造性”的胡乱发挥。5.2 处理复杂任务与状态管理当用户提出“帮我制定一份本周五从上海到北京的出差计划包括航班、酒店和会议安排建议”这样的复杂任务时Agent需要拆解任务、维护状态当前在规划哪个部分、并可能进行多轮交互。WorkBuddy框架通常会提供会话Session或线程Thread的概念来管理状态。你需要持久化会话将每次运行的对话历史、工具调用结果保存到数据库或文件中下次可以从上次中断的地方继续。任务分解提示在系统提示词中强化Agent的任务分解能力。例如加入“对于涉及多个子目标的复杂请求你必须先制定一个清晰的计划Plan并将计划写入thoughts.plan字段。然后一步一步地执行计划中的每个项目。”子目标管理在Agent的思考中让它明确跟踪当前正在处理的子目标。例如在thoughts中可以添加“current_subgoal”: “正在查询周五上午上海到北京的航班”。一个简化实现思路是在运行器Runner外层包裹一个状态管理循环async def handle_complex_task(user_goal, agent, session_id): # 1. 加载或创建会话状态 session_state load_session(session_id) or {“goal”: user_goal, “subtasks”: [], “current_step”: 0} # 2. 如果这是新任务让Agent先做规划 if not session_state[“subtasks”]: planning_prompt f“请将以下复杂任务分解为具体的子任务步骤{user_goal}。请只输出一个JSON数组每个元素是一个子任务描述。” # 调用一次Agent获取规划这里可能需要一个特定的“规划模式”提示词 plan await agent.generate_plan(planning_prompt) session_state[“subtasks”] plan save_session(session_id, session_state) # 3. 循环执行子任务 while session_state[“current_step”] len(session_state[“subtasks”]): current_task session_state[“subtasks”][session_state[“current_step”]] prompt f“我们正在处理总目标 ‘{user_goal}’。当前子任务步骤 ({session_state[‘current_step’]1}/{len(session_state[‘subtasks’])}) 是{current_task}。请专注完成此步骤。” # 使用Agent执行当前子任务... result await runner.run(prompt) # ... 处理结果更新状态 session_state[“current_step”] 1 save_session(session_id, session_state) return “所有子任务已完成。”5.3 常见问题排查与性能调优在实际运行中你肯定会遇到各种问题。这里列一个速查表问题现象可能原因解决方案Agent完全不调用工具1. 系统提示词未强调工具使用。2. 工具描述不清模型不理解何时用。3. 模型温度过高自由发挥。1. 强化提示词加入Few-Shot示例。2. 优化工具描述明确使用场景。3. 降低温度参数如设为0.1。工具调用参数错误1. 模型未理解参数格式。2. 参数描述模糊。1. 在Few-Shot示例中展示正确参数格式。2. 在工具描述中为每个参数提供清晰示例。Agent陷入循环或无关动作1. 任务规划不清晰Agent“迷路”。2. 工具返回结果未满足预期导致重复尝试。1. 引入更明确的任务分解和状态跟踪。2. 优化工具函数确保返回清晰、结构化的结果。在提示词中要求Agent分析工具结果判断是否成功。响应速度慢1. 模型API调用延迟高。2. 工具本身是慢IO操作如网络请求。3. 上下文过长模型处理慢。1. 考虑模型推理的优化版本或本地部署。2. 为慢工具设置超时或使用异步并发。3. 定期总结或清理对话历史压缩上下文。上下文溢出Token超限对话历史工具结果提示词超过模型上下文窗口。1. 使用框架的记忆摘要功能将长历史压缩成摘要。2. 只保留最近N轮对话。3. 对工具返回的大结果进行提取摘要后再喂给模型。性能调优的一个关键点控制上下文长度。每次调用模型你发送的“消息列表”包含系统提示、历史对话、工具结果、最新用户问题的总Token数不能超过限制。你需要一个策略来管理历史滑动窗口只保留最近10轮对话。关键记忆提取让模型自己总结之前对话的“要点”只把要点放入上下文。工具结果摘要对于工具返回的冗长内容如搜索到的10篇文章先让一个快速的文本摘要模型或让大模型自己提取关键信息再放入主Agent的上下文。6. 完整提示词示例与项目展望最后我将分享一个整合了上述所有技巧的、相对完整的系统提示词示例。你可以以此作为蓝本根据自己Agent的专属工具集进行修改。complete_system_prompt # 身份与使命 你是WorkBuddy Pro用户的终极数字工作伙伴。你的唯一目标是**理解指令制定完美计划并精准执行**。 ## 核心原则 - **安全第一**绝不执行任何可能破坏系统、泄露隐私或产生有害内容的操作。如有疑虑立即停止并询问用户。 - **分步推进**像顶尖项目经理一样思考定义目标 - 拆解任务 - 评估资源工具- 执行 - 交付。 - **极致透明**通过你的“思考”字段让我随时了解你的决策逻辑。这能建立信任。 - **结果可用**你的最终交付物必须是完整、整洁、可直接采纳的答案或文件。 ## 工具库与使用宪法 你拥有以下工具它们是你的超能力 {tool_list_detailed} **工具使用铁律** 1. **先判断后调用**问自己“不用工具我能可靠完成吗”若答案是否定的则必须调用工具。 2. **一次一事**每个响应周期只执行一个工具调用。规划可以有多步但行动只迈一步。 3. **参数精确**调用工具前在脑中模拟参数是否有效。例如file_path必须是一个存在的路径字符串。 4. **消化结果**工具返回的是“原料”你的工作是将其烹饪成“佳肴”。整合、解释、关联到用户问题。 ## 通信协议必须严格遵守 你的每个响应都必须是纯粹的JSON对象格式如下 json { “thoughts”: { “reasoning”: “详细阐述你对当前情况的分析、对用户真实意图的揣测、以及选择当前行动的逻辑。这是最重要的部分。, “plan”: [“下一步做什么”, “再下一步做什么”], “speak”: “以自然、友好的口吻对用户说的话用于即时反馈。” }, “action”: { “name”: “工具名字符串或 null”, “args”: {“参数名”: “参数值”} // 必须严格匹配工具定义 } }框架将根据你的action来驱动世界。speak部分会实时显示给用户。复杂任务处理框架遇到宏大目标时如“策划一场发布会”按此流程澄清与用户确认模糊需求预算、时间、风格等。蓝图在plan中列出所有关键阶段和子任务。迭代一次完成一个子任务并在thoughts中更新进度“已完成A正在B接下来是C”。汇总所有子任务完成后交付一份整合的最终报告。示例请深刻理解其模式用户“我想知道特斯拉最新的财报情况并和比亚迪对比一下。” { “thoughts”: { “reasoning”: “用户需求包含两个部分1) 获取特斯拉最新财报信息2) 与比亚迪进行对比。这两者都需要最新、准确的公开数据我必须使用web_search工具。我应该先搜索特斯拉财报再搜索比亚迪的近期财务数据最后在脑海中或下一步进行对比分析。”, “plan”: [“步骤1搜索‘Tesla Q1 2024 earnings report key figures’。”, “步骤2搜索‘BYD 2024 financial results comparison’。”, “步骤3基于搜索结果整理对比要点并回复用户。”], “speak”: “我来帮您查找特斯拉和比亚迪的最新财务信息并进行对比。” }, “action”: { “name”: “web_search”, “args”: {“query”: “Tesla Q1 2024 earnings report revenue net income”} } }现在请开始你的表演。记住你的价值在于将想法转化为行动。 将这个强大的提示词与精心设计的工具集搜索、文件、计算、API连接等结合再辅以稳健的状态管理你的Hy3 WorkBuddy Agent就能处理相当复杂的现实任务了。 **项目展望与扩展方向** 1. **工具生态扩展**这是最直接的增强。考虑集成日历管理、邮件发送、代码仓库操作Git、项目管理软件如Jira、飞书接口、数据分析库Pandas等。让Agent真正融入你的工作流。 2. **多智能体协作**可以创建多个具有不同专长的Agent一个负责研究一个负责写作一个负责校对让它们通过WorkBuddy框架或消息队列进行协作共同完成一个超大任务。 3. **长期记忆与个性化**为Agent添加向量数据库让它能记住每次交互的要点学习用户的偏好变得越来越“懂你”。 4. **前端交互界面**构建一个Web或聊天应用界面让非技术用户也能方便地与你的Agent交互。 Hy3提供了强大的“脑力”WorkBuddy提供了灵活的“肢体”而你的提示词工程和工具设计则赋予了它独特的“灵魂”和“技能”。这个组合的潜力取决于你如何定义和塑造它。从我实际的搭建体验来看这条路是通的而且效果确实令人兴奋。剩下的就是发挥你的想象力去创造那个独一无二的数字助手了。 基于Hy3与WorkBuddy构建智能体：从环境搭建到提示词调优实战
1. 项目概述当Hy3遇上WorkBuddy最近在AI智能体Agent的圈子里一个组合开始被频繁提及Hy3 WorkBuddy。不少开发者尝试后给出的评价是“效果惊艳”甚至有人称之为“国产顶级Agent”的潜力配方。这让我这个老码农也来了兴趣决定亲自上手从环境搭建到提示词调优完整地走一遍这个流程看看它到底是不是名副其实。简单来说这个组合的核心思路是利用Hy3这个强大的开源大语言模型作为“大脑”负责理解、规划和决策而WorkBuddy则作为一套功能丰富的“工具箱”和“执行框架”为Hy3提供调用外部API、处理文件、管理记忆和状态的能力。两者结合目标就是打造一个能真正理解复杂指令、自主拆解任务、并调用合适工具去执行的智能助理。它适合那些已经厌倦了简单问答式AI希望构建能够处理多步骤、跨平台实际任务的开发者、产品经理或技术爱好者。比如让它“帮我分析一下上周的销售数据做成图表然后总结要点发邮件给团队”它就能自己规划步骤依次调用数据分析、图表生成和邮件发送等功能。接下来我会把我从零开始搭建、调试到最终跑通一个实用Agent的全过程包括踩过的坑和总结出的高效提示词毫无保留地分享出来。你会发现打造一个“聪明”的Agent关键不仅在于模型本身更在于如何为它设计一套清晰的“行为准则”和“工具使用说明书”。2. 核心组件深度解析为什么是它们在动手之前我们必须先吃透手里的“武器”。Hy3和WorkBuddy各自扮演什么角色它们的优势在哪理解了这些后续的配置和调优才能有的放矢。2.1 Hy3模型为何选择它作为“大脑”Hy3并非一个单一的模型而是一个模型系列通常指代性能较强、适合作为智能体核心的版本例如DeepSeek-V3或相关变体。选择它是基于几个非常实际的考量第一强大的推理与规划能力。Agent的核心是“思考”即根据用户目标拆解出子任务并规划执行路径。Hy3系列模型在数学推理、代码生成和逻辑链条理解上表现突出这恰恰是任务规划Planning环节最需要的能力。相比一些更侧重于对话流畅度的模型Hy3在遇到“请先查询天气如果下雨就提醒我带伞并预约出租车如果晴天则制定一份公园散步路线”这类复杂指令时表现出更好的步骤分解准确性。第二对长上下文的支持。一个实用的Agent需要记忆对话历史、工具调用结果和自身的状态。Hy3模型通常支持128K甚至更长的上下文窗口。这意味着我们可以把复杂的系统提示词即Agent的“人格设定”和“操作手册”、多轮对话历史、以及多个工具的输出结果都塞进上下文而不用担心早期信息被遗忘。这是实现连贯、长期对话助理的基础。第三优秀的指令遵循Instruction Following能力。这可能是最关键的一点。我们需要模型严格地按照我们设定的格式比如必须用特定的JSON结构来调用工具来输出。Hy3在训练中对指令的遵循度较高减少了“模型自由发挥、不按套路出牌”的情况这对于需要稳定对接工具的自动化流程至关重要。第四开源与可及性。作为国产开源模型的优秀代表其获取和使用成本相对友好社区活跃遇到问题也容易找到讨论和解决方案。这对于我们进行实验和开发来说减少了前期障碍。注意模型领域迭代极快“Hy3”作为一个非正式称呼可能指向不同时期的具体模型。在实践时建议关注DeepSeek官方发布的最新版本并查阅其技术报告确认其在工具调用Function Calling和指令遵循方面的量化评估结果。2.2 WorkBuddy框架智能体的“手和脚”如果说Hy3是大脑那么WorkBuddy就是让大脑想法得以实现的身体。它是一个AI智能体开发框架核心解决了Agent领域的几个经典难题1. 工具抽象与管理WorkBuddy将各种能力搜索、计算、读写文件、调用API封装成统一的“工具”Tool。开发者可以像搭积木一样将自己需要的工具注册到框架中。框架负责向模型描述这些工具的功能、输入参数并接收模型的调用请求转换为实际的代码执行。2. 状态与记忆管理Agent在运行中会有状态例如当前正在执行的任务步骤和记忆之前的对话和结果。WorkBuddy提供了会话Session和记忆Memory模块来管理这些信息确保Agent在多轮交互中保持上下文感知。3. 执行流程控制这是WorkBuddy的精华所在。它实现了ReActReasoning Acting等经典Agent执行循环。简单说这个循环是“思考分析当前状况和任务- 决定是调用工具还是直接回答用户- 执行调用工具并获取结果- 观察将结果纳入思考”如此循环直到任务完成。WorkBuddy帮我们固化了这个循环逻辑我们只需要关心提供什么工具以及如何引导模型思考。4. 易于扩展与集成它的架构通常设计得比较清晰允许开发者很方便地添加自定义工具。无论是连接内部业务系统还是接入一个新的第三方API都可以通过编写一个符合规范的Python类来实现。WorkBuddy与类似框架如LangChain, AutoGen的对比WorkBuddy的一个特点是可能更强调“开箱即用”和对国产模型生态的友好集成。它的设计可能更贴近国内开发者的使用习惯文档和示例也以中文为主降低了学习门槛。而LangChain生态更庞大组件更多但复杂度也更高。选择WorkBuddy意味着在构建专注于任务执行、且希望快速上手的Agent时可能会更轻快、直接。3. 环境搭建与基础配置实战理论说得再多不如动手跑通。这一部分我会带你一步步搭建起Hy3 WorkBuddy的运行环境并完成一个最基础的“Hello Agent”示例。3.1 准备工作与依赖安装首先确保你的开发环境是Python 3.9以上。我强烈建议使用虚拟环境来管理依赖避免包冲突。# 创建并激活虚拟环境以venv为例 python -m venv hy3_workbuddy_env source hy3_workbuddy_env/bin/activate # Linux/macOS # hy3_workbuddy_env\Scripts\activate # Windows # 安装核心依赖 pip install -U pip接下来安装WorkBuddy框架。由于WorkBuddy可能是一个相对较新的项目最可靠的方式是从其官方Git仓库安装。# 假设WorkBuddy的仓库地址请以官方文档为准 # pip install githttps://github.com/workbuddy-team/workbuddy.git # 或者如果它已上传至PyPI # pip install workbuddy为了对接Hy3模型我们需要安装对应的SDK。这里以DeepSeek为例pip install openai # DeepSeek的API通常兼容OpenAI SDK格式实操心得在安装这类较新的框架时最常遇到的问题是依赖冲突。如果安装失败先别急着折腾仔细看错误信息。很多时候是因为某个依赖包的版本要求太新或太旧。可以尝试先单独安装框架声明的主要依赖如fastapi,pydantic等的常见稳定版本再安装框架本身。查阅项目的requirements.txt或pyproject.toml文件是解决问题的捷径。3.2 获取并配置模型API密钥你需要一个Hy3模型如DeepSeek的API访问权限。前往对应平台的官网注册账号并获取API Key。创建一个名为.env的文件来管理你的密钥避免硬编码在代码中# .env 文件 DEEPSEEK_API_KEYyour_deepseek_api_key_here DEEPSEEK_API_BASEhttps://api.deepseek.com # 以DeepSeek官方地址为例在Python代码中使用python-dotenv来加载配置pip install python-dotenv# config.py import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 DEEPSEEK_API_KEY os.getenv(DEEPSEEK_API_KEY) DEEPSEEK_API_BASE os.getenv(DEEPSEEK_API_BASE, https://api.deepseek.com)3.3 编写第一个智能体让AI做道数学题现在我们来创建一个最简单的Agent它只使用一个内置工具——计算器。这个例子能帮你理解WorkBuddy最核心的工作流程。# simple_agent.py import asyncio from workbuddy import Agent, Runner # 假设这是导入方式具体以官方文档为准 from workbuddy.tools import CalculatorTool from openai import OpenAI # 1. 配置模型客户端 client OpenAI( api_keyDEEPSEEK_API_KEY, base_urlDEEPSEEK_API_BASE /v1, # 适配OpenAI格式的端点 ) # 2. 创建工具实例 calculator CalculatorTool() # 3. 定义系统提示词Agent的“人格”和“指令” system_prompt 你是一个专业的数学助手。你的任务是帮助用户解决数学问题。 你必须遵循以下规则 1. 仔细分析用户的问题。 2. 如果需要计算你必须使用calculator工具。 3. 使用工具后将工具返回的结果整合到你的回答中用清晰的语言向用户解释。 4. 如果用户的问题不需要计算请直接回答。 记住不要尝试自己心算一定要使用工具 # 4. 创建Agent agent Agent( nameMathBot, system_promptsystem_prompt, model_clientclient, # 传入配置好的客户端 model_namedeepseek-chat, # 指定模型名称 tools[calculator], # 赋予Agent可用的工具 ) # 5. 创建运行器并执行 async def main(): runner Runner(agentagent) # 用户提问一个复杂计算 user_query “请计算 (15的平方根加上28) 再乘以 3.14 等于多少结果保留两位小数。” print(f用户: {user_query}) async for chunk in runner.run_stream(user_query): # 这里会流式输出Agent的“思考过程”和最终回答 if hasattr(chunk, content) and chunk.content: print(chunk.content, end, flushTrue) print() # 换行 if __name__ __main__: asyncio.run(main())运行这个脚本你会看到Agent的输出可能类似这样用户: 请计算 (15的平方根加上28) 再乘以 3.14 等于多少结果保留两位小数。 思考用户需要一个复合计算。我需要先计算15的平方根加上28再乘以3.14。我应该使用计算器工具。 行动调用calculator工具计算 sqrt(15)。 工具调用过程... 观察sqrt(15) 的结果约为 3.872983346207417。 思考现在需要将结果加上283.872983346207417 28。 行动调用calculator工具计算 3.872983346207417 28。 工具调用过程... 观察和为 31.872983346207417。 思考最后将这个和乘以3.14。 行动调用calculator工具计算 31.872983346207417 * 3.14。 工具调用过程... 观察乘积为 100.08016970709128。 思考现在需要保留两位小数。 行动调用calculator工具对 100.08016970709128 进行四舍五入到两位小数。 工具调用过程... 观察四舍五入后结果为 100.08。 最终回答根据计算(√15 28) × 3.14 的结果约为 100.08。计算过程是√15 ≈ 3.873加上28得31.873再乘以3.14得到100.08保留两位小数。这个过程清晰地展示了ReAct循环思考 - 行动调用工具- 观察 - 再思考。虽然只是一个计算器但你已经创建了一个能自主使用工具完成任务的智能体。注意事项初次运行你可能会遇到导入错误ModuleNotFoundError: No module named workbuddy。这通常意味着WorkBuddy的包名或安装方式与示例假设不同。请务必以该项目的官方GitHub仓库或文档的快速开始Quick Start指南为准。上面的代码是一个基于常见Agent框架模式的示意你需要根据WorkBuddy的实际API进行调整。4. 构建多功能智能体提示词设计与工具集成一个只会算数的Agent显然不够看。我们的目标是打造一个“顶级助手”这意味着它需要掌握多种技能。这部分的重点有两个一是设计一个强大、严谨的系统提示词这是Agent的“灵魂”二是集成更多实用的工具。4.1 系统提示词工程定义Agent的行为准则系统提示词是引导模型行为最关键的部分。一个糟糕的提示词会让强大的模型表现得像个傻瓜。下面我分享一个经过多次迭代、相对通用的“强指令遵循型”提示词模板你可以在此基础上修改。advanced_system_prompt # 角色与核心指令 你是WorkBuddy一个全能型AI工作助理。你的核心驱动力是**准确理解用户目标并高效、可靠地完成它**。 ## 通用行为准则 1. **绝对诚实**知道就说知道不知道就承认不知道绝不自作聪明编造信息。 2. **分步思考**对于复杂任务必须在内心或输出中展示你的思考链Chain-of-Thought。先理解再规划后执行。 3. **主动确认**当用户指令模糊、存在歧义或可能产生重大影响时如删除文件、发送邮件必须主动向用户澄清确认直到完全明确。 4. **结果导向**你的最终输出必须是针对用户问题的、完整的、可直接使用的答案或成果而非中间过程。 ## 工具使用规范 你被赋予了以下工具{tool_list}。使用工具是你完成任务的主要方式。 1. **必要性判断**只有当任务需要你获取外部信息、执行计算、操作文件或系统时才调用工具。纯知识性、推理性或聊天性任务请直接运用你的知识回答。 2. **精准调用**调用工具时必须严格遵循每个工具定义的参数格式和类型。仔细检查你提供的参数值是否合理。 3. **结果整合**获得工具返回结果后你必须分析该结果并将其**自然、流畅地整合**到你对用户的最终回复中。不要直接抛出原始的、未处理的工具输出。 4. **序列与依赖**如果任务需要多个工具且步骤间有依赖关系如先搜索再总结请按逻辑顺序依次调用。你可以规划多个步骤但一次只执行一个工具调用。 ## 输出格式要求 你的所有响应都必须采用以下JSON格式 json { “thoughts”: { “reasoning”: “你当前的思考过程分析用户意图和下一步计划。, “plan”: [“步骤1...”, “步骤2...”], “criticism”: “对当前想法潜在问题的自我审视。, “speak”: “你打算对用户说的下一句话用于流式输出时的自然语言反馈” }, “action”: { “name”: “要调用的工具名称如无需调用则为 null, “args”: {“arg1”: “value1”, ...} // 工具参数如无需调用则为 {} } }重要这是你与框架的通信协议必须严格遵守。框架会解析你的action字段来调用工具并将工具结果反馈给你开启下一轮循环。对话管理记忆你可以访问之前的对话历史。请利用历史来理解上下文避免重复提问。状态如果你正在执行一个多步骤任务请在思考中明确当前进度。现在开始工作。你的目标是成为用户最得力的伙伴。 这个提示词做了几件关键事 1. **明确角色和核心目标**定下基调。 2. **制定行为准则**确保Agent可靠、安全。 3. **严格规范工具使用**这是避免Agent乱用或不用工具的关键。 4. **强制结构化输出**通过JSON格式牢牢控制模型的输出使其易于被程序解析。这是实现稳定自动化交互的基石。 5. **管理对话**让Agent有“记忆”。 **实操心得** 提示词中的 {tool_list} 是一个占位符。在实际程序中应该在创建Agent前用程序自动将已注册的工具名称和描述填充进去。这样Agent就能动态知道它有什么工具可用。很多框架会帮你自动完成这一步。 ### 4.2 集成实用工具搜索、文件与网络 让我们为Agent装备更多“武器”。这里以集成一个网页搜索工具和一个文件读取工具为例。 首先你需要注册相关服务的API如Serper或SearXNG用于搜索。 python # advanced_agent.py import asyncio import json from pathlib import Path from workbuddy import Agent, Runner from workbuddy.tools import BaseTool # 假设BaseTool是基类 from openai import OpenAI import aiohttp # 用于异步HTTP请求 import os from dotenv import load_dotenv load_dotenv() # --- 1. 自定义工具网页搜索工具 --- class WebSearchTool(BaseTool): name “web_search” description “在互联网上搜索实时信息。当你需要获取最新新闻、事实核查、或未知领域信息时使用此工具。” parameters { “type”: “object”, “properties”: { “query”: { “type”: “string”, “description”: “要搜索的关键词或问题尽量简洁明确。” } }, “required”: [“query”] } async def run(self, query: str): 执行搜索 api_key os.getenv(“SERPER_API_KEY”) # 假设使用Serper.dev url “https://google.serper.dev/search” headers { ‘X-API-KEY’: api_key, ‘Content-Type’: ‘application/json’ } payload json.dumps({“q”: query}) async with aiohttp.ClientSession() as session: async with session.post(url, headersheaders, datapayload) as response: if response.status 200: data await response.json() # 简化处理只返回前几条结果的摘要 snippets [item.get(‘snippet’, ‘’) for item in data.get(‘organic’, [])[:3]] return f“搜索 ‘{query}’ 的结果摘要\n” “\n”.join([f“{i1}. {s}” for i, s in enumerate(snippets)]) else: return f“搜索失败状态码{response.status}” # --- 2. 自定义工具文件读取工具 --- class ReadFileTool(BaseTool): name “read_file” description “读取本地文本文件的内容。用于分析代码、日志、文档等。” parameters { “type”: “object”, “properties”: { “file_path”: { “type”: “string”, “description”: “要读取的文件的绝对路径或相对于当前工作目录的路径。” } }, “required”: [“file_path”] } async def run(self, file_path: str): 读取文件内容 path Path(file_path) if not path.exists(): return f“错误文件 ‘{file_path}’ 不存在。” if not path.is_file(): return f“错误’{file_path}’ 不是一个文件。” try: # 注意这里简单处理只读文本。对于大文件可能需要分块读取。 content path.read_text(encoding‘utf-8’) return f“文件 ‘{file_path}’ 的内容如下\n\n{content[:2000]}...\n\n(显示前2000字符)” except Exception as e: return f“读取文件时出错{str(e)}” # --- 3. 配置与运行 --- client OpenAI(api_keyos.getenv(“DEEPSEEK_API_KEY”), base_urlos.getenv(“DEEPSEEK_API_BASE”) “/v1”) # 创建工具实例 search_tool WebSearchTool() read_tool ReadFileTool() # 可以继续添加更多工具如 CalculatorTool() # 动态生成工具列表描述 tool_descriptions “\n”.join([f“- **{tool.name}**: {tool.description}” for tool in [search_tool, read_tool]]) final_system_prompt advanced_system_prompt.format(tool_listtool_descriptions) # 创建高级Agent advanced_agent Agent( name“WorkBuddyPro”, system_promptfinal_system_prompt, model_clientclient, model_name“deepseek-chat”, tools[search_tool, read_tool], ) async def run_advanced_agent(): runner Runner(agentadvanced_agent) # 示例对话 queries [ “今天科技圈有什么重要新闻吗”, “请帮我读一下当前目录下的 ‘README.md’ 文件并总结它的主要内容。” ] for query in queries: print(f“\n{*50}”) print(f“用户: {query}”) print(f“{*50}”) full_response “” async for chunk in runner.run_stream(query): # 在实际框架中chunk可能是包含thoughts和action的复杂对象 # 这里简化处理假设能直接获取文本内容 if hasattr(chunk, ‘content’): print(chunk.content, end‘’, flushTrue) full_response chunk.content elif isinstance(chunk, dict): # 如果是结构化数据 # 可以解析并漂亮地打印 thoughts if ‘thoughts’ in chunk: print(f“\n[思考] {chunk[‘thoughts’].get(‘reasoning’, ‘’)}”) if ‘action’ in chunk and chunk[‘action’].get(‘name’): print(f“\n[行动] 调用工具: {chunk[‘action’][‘name’]} 参数: {chunk[‘action’][‘args’]}”) print() # 这里可以保存对话历史等 if __name__ “__main__”: asyncio.run(run_advanced_agent())通过这样的集成你的Agent就具备了获取实时信息和读取本地文件的能力。你可以继续添加更多工具比如发送邮件的EmailTool、查询数据库的DBQueryTool、执行Shell命令的CommandTool需极其谨慎注意安全等等。5. 高级技巧与避坑指南走到这一步一个基础的多功能Agent已经搭建完成。但要让它变得“顶级”和“可靠”还需要一些高级技巧并避开常见的陷阱。5.1 优化提示词以提升工具调用准确性即使有了好的提示词模板模型有时仍会“叛逆”——不调用工具或者调用时参数错误。以下是一些微调技巧少样本示例Few-Shot在系统提示词中直接给出1-2个工具调用的完美示例。这比单纯描述规则有效得多。示例 用户 “北京现在的天气怎么样” 你的思考内部用户需要实时天气信息我需要使用搜索工具。 你的输出必须遵守的JSON格式 { “thoughts”: { “reasoning”: “用户询问北京实时天气这是一个需要最新外部信息的问题我应该使用web_search工具。”, “plan”: [“步骤1使用web_search搜索‘北京 当前 天气’。”], “speak”: “我来为您查询一下北京的实时天气。” }, “action”: { “name”: “web_search”, “args”: {“query”: “北京 当前 天气 实时”} } }强化格式强调在提示词中用非常醒目的方式强调输出格式比如用json ...包裹并加上“必须”、“严格”等词语。指定思考框架明确要求模型按照“理解问题 - 检查是否需要工具 - 选择正确工具 - 确认参数 - 执行”的流程进行内部思考并将这个流程体现在thoughts.reasoning中。温度Temperature参数在调用模型API时将温度参数设置为较低的值如0.1或0.2。较低的温度会使模型的输出更加确定性和可预测更倾向于遵循指令和既定格式减少“创造性”的胡乱发挥。5.2 处理复杂任务与状态管理当用户提出“帮我制定一份本周五从上海到北京的出差计划包括航班、酒店和会议安排建议”这样的复杂任务时Agent需要拆解任务、维护状态当前在规划哪个部分、并可能进行多轮交互。WorkBuddy框架通常会提供会话Session或线程Thread的概念来管理状态。你需要持久化会话将每次运行的对话历史、工具调用结果保存到数据库或文件中下次可以从上次中断的地方继续。任务分解提示在系统提示词中强化Agent的任务分解能力。例如加入“对于涉及多个子目标的复杂请求你必须先制定一个清晰的计划Plan并将计划写入thoughts.plan字段。然后一步一步地执行计划中的每个项目。”子目标管理在Agent的思考中让它明确跟踪当前正在处理的子目标。例如在thoughts中可以添加“current_subgoal”: “正在查询周五上午上海到北京的航班”。一个简化实现思路是在运行器Runner外层包裹一个状态管理循环async def handle_complex_task(user_goal, agent, session_id): # 1. 加载或创建会话状态 session_state load_session(session_id) or {“goal”: user_goal, “subtasks”: [], “current_step”: 0} # 2. 如果这是新任务让Agent先做规划 if not session_state[“subtasks”]: planning_prompt f“请将以下复杂任务分解为具体的子任务步骤{user_goal}。请只输出一个JSON数组每个元素是一个子任务描述。” # 调用一次Agent获取规划这里可能需要一个特定的“规划模式”提示词 plan await agent.generate_plan(planning_prompt) session_state[“subtasks”] plan save_session(session_id, session_state) # 3. 循环执行子任务 while session_state[“current_step”] len(session_state[“subtasks”]): current_task session_state[“subtasks”][session_state[“current_step”]] prompt f“我们正在处理总目标 ‘{user_goal}’。当前子任务步骤 ({session_state[‘current_step’]1}/{len(session_state[‘subtasks’])}) 是{current_task}。请专注完成此步骤。” # 使用Agent执行当前子任务... result await runner.run(prompt) # ... 处理结果更新状态 session_state[“current_step”] 1 save_session(session_id, session_state) return “所有子任务已完成。”5.3 常见问题排查与性能调优在实际运行中你肯定会遇到各种问题。这里列一个速查表问题现象可能原因解决方案Agent完全不调用工具1. 系统提示词未强调工具使用。2. 工具描述不清模型不理解何时用。3. 模型温度过高自由发挥。1. 强化提示词加入Few-Shot示例。2. 优化工具描述明确使用场景。3. 降低温度参数如设为0.1。工具调用参数错误1. 模型未理解参数格式。2. 参数描述模糊。1. 在Few-Shot示例中展示正确参数格式。2. 在工具描述中为每个参数提供清晰示例。Agent陷入循环或无关动作1. 任务规划不清晰Agent“迷路”。2. 工具返回结果未满足预期导致重复尝试。1. 引入更明确的任务分解和状态跟踪。2. 优化工具函数确保返回清晰、结构化的结果。在提示词中要求Agent分析工具结果判断是否成功。响应速度慢1. 模型API调用延迟高。2. 工具本身是慢IO操作如网络请求。3. 上下文过长模型处理慢。1. 考虑模型推理的优化版本或本地部署。2. 为慢工具设置超时或使用异步并发。3. 定期总结或清理对话历史压缩上下文。上下文溢出Token超限对话历史工具结果提示词超过模型上下文窗口。1. 使用框架的记忆摘要功能将长历史压缩成摘要。2. 只保留最近N轮对话。3. 对工具返回的大结果进行提取摘要后再喂给模型。性能调优的一个关键点控制上下文长度。每次调用模型你发送的“消息列表”包含系统提示、历史对话、工具结果、最新用户问题的总Token数不能超过限制。你需要一个策略来管理历史滑动窗口只保留最近10轮对话。关键记忆提取让模型自己总结之前对话的“要点”只把要点放入上下文。工具结果摘要对于工具返回的冗长内容如搜索到的10篇文章先让一个快速的文本摘要模型或让大模型自己提取关键信息再放入主Agent的上下文。6. 完整提示词示例与项目展望最后我将分享一个整合了上述所有技巧的、相对完整的系统提示词示例。你可以以此作为蓝本根据自己Agent的专属工具集进行修改。complete_system_prompt # 身份与使命 你是WorkBuddy Pro用户的终极数字工作伙伴。你的唯一目标是**理解指令制定完美计划并精准执行**。 ## 核心原则 - **安全第一**绝不执行任何可能破坏系统、泄露隐私或产生有害内容的操作。如有疑虑立即停止并询问用户。 - **分步推进**像顶尖项目经理一样思考定义目标 - 拆解任务 - 评估资源工具- 执行 - 交付。 - **极致透明**通过你的“思考”字段让我随时了解你的决策逻辑。这能建立信任。 - **结果可用**你的最终交付物必须是完整、整洁、可直接采纳的答案或文件。 ## 工具库与使用宪法 你拥有以下工具它们是你的超能力 {tool_list_detailed} **工具使用铁律** 1. **先判断后调用**问自己“不用工具我能可靠完成吗”若答案是否定的则必须调用工具。 2. **一次一事**每个响应周期只执行一个工具调用。规划可以有多步但行动只迈一步。 3. **参数精确**调用工具前在脑中模拟参数是否有效。例如file_path必须是一个存在的路径字符串。 4. **消化结果**工具返回的是“原料”你的工作是将其烹饪成“佳肴”。整合、解释、关联到用户问题。 ## 通信协议必须严格遵守 你的每个响应都必须是纯粹的JSON对象格式如下 json { “thoughts”: { “reasoning”: “详细阐述你对当前情况的分析、对用户真实意图的揣测、以及选择当前行动的逻辑。这是最重要的部分。, “plan”: [“下一步做什么”, “再下一步做什么”], “speak”: “以自然、友好的口吻对用户说的话用于即时反馈。” }, “action”: { “name”: “工具名字符串或 null”, “args”: {“参数名”: “参数值”} // 必须严格匹配工具定义 } }框架将根据你的action来驱动世界。speak部分会实时显示给用户。复杂任务处理框架遇到宏大目标时如“策划一场发布会”按此流程澄清与用户确认模糊需求预算、时间、风格等。蓝图在plan中列出所有关键阶段和子任务。迭代一次完成一个子任务并在thoughts中更新进度“已完成A正在B接下来是C”。汇总所有子任务完成后交付一份整合的最终报告。示例请深刻理解其模式用户“我想知道特斯拉最新的财报情况并和比亚迪对比一下。” { “thoughts”: { “reasoning”: “用户需求包含两个部分1) 获取特斯拉最新财报信息2) 与比亚迪进行对比。这两者都需要最新、准确的公开数据我必须使用web_search工具。我应该先搜索特斯拉财报再搜索比亚迪的近期财务数据最后在脑海中或下一步进行对比分析。”, “plan”: [“步骤1搜索‘Tesla Q1 2024 earnings report key figures’。”, “步骤2搜索‘BYD 2024 financial results comparison’。”, “步骤3基于搜索结果整理对比要点并回复用户。”], “speak”: “我来帮您查找特斯拉和比亚迪的最新财务信息并进行对比。” }, “action”: { “name”: “web_search”, “args”: {“query”: “Tesla Q1 2024 earnings report revenue net income”} } }现在请开始你的表演。记住你的价值在于将想法转化为行动。 将这个强大的提示词与精心设计的工具集搜索、文件、计算、API连接等结合再辅以稳健的状态管理你的Hy3 WorkBuddy Agent就能处理相当复杂的现实任务了。 **项目展望与扩展方向** 1. **工具生态扩展**这是最直接的增强。考虑集成日历管理、邮件发送、代码仓库操作Git、项目管理软件如Jira、飞书接口、数据分析库Pandas等。让Agent真正融入你的工作流。 2. **多智能体协作**可以创建多个具有不同专长的Agent一个负责研究一个负责写作一个负责校对让它们通过WorkBuddy框架或消息队列进行协作共同完成一个超大任务。 3. **长期记忆与个性化**为Agent添加向量数据库让它能记住每次交互的要点学习用户的偏好变得越来越“懂你”。 4. **前端交互界面**构建一个Web或聊天应用界面让非技术用户也能方便地与你的Agent交互。 Hy3提供了强大的“脑力”WorkBuddy提供了灵活的“肢体”而你的提示词工程和工具设计则赋予了它独特的“灵魂”和“技能”。这个组合的潜力取决于你如何定义和塑造它。从我实际的搭建体验来看这条路是通的而且效果确实令人兴奋。剩下的就是发挥你的想象力去创造那个独一无二的数字助手了。