个人开发者零基础接入开放平台构建Agent应用完整实战指南

前阵子我发了一个“打算把日常那些重复性事务交给AI处理”的动态，评论区不少朋友问：个人开发者到底能不能不依赖团队，自己从一个开放平台接到一个真正能用的Agent应用？花了一周时间，我把WorkBuddy开放平台从注册、建应用、调接口、加工具、定义Skill到发布上线完整走了一遍，中间踩了不少坑，也攒了不少可以直接复用的经验。这篇文章就把这条从零到Agent应用的完整接入路径写清楚，适合想独立搞Agent开发的个人开发者，也适合已经在用WorkBuddy工作台但想进一步做自定义能力的用户。我尽量把每个环节为什么这么做讲明白，而不是只丢几个截图。

1. 接入前的准备：账号、应用与本地开发环境

个人开发者最容易犯的毛病，是拿到API文档就开始对着接口狂调，结果搞了半天连平台的基础概念都没对齐。WorkBuddy这套体系里，Skill、Agent、自定义指令、工具这些词背后对应的是不同的能力层级，不理解清楚，后面做设计一定会乱。

1.1 先搞清楚WorkBuddy开放平台的几个核心概念

WorkBuddy本身是一个面向办公场景的AI工作台，普通用户通过网页版、桌面客户端或者Linux环境下的客户端就能使用AI助手完成写文档、整理信息、执行任务这些事。而开放平台是把这套能力开放出来，让开发者把自己的数据源、业务流程接到Agent里。

我先说三组容易混淆的东西，这也是我在前期看资料时最纠结的地方。

第一组是WorkBuddy和CodeBuddy的区别。CodeBuddy主要面向编程场景，帮你写代码、修Bug、做代码审查；WorkBuddy更偏日常办公和业务流程自动化，比如让AI帮你查事项、整理会议纪要、生成周报。这个定位差异决定了后面你接入时选择的场景方向：如果目标是写代码，那应该去研究CodeBuddy的编程能力；如果是把工作流自动化，WorkBuddy才是对的那个平台。

第二组是Skill和Agent的区别。Agent是一个具备自主执行能力的“智能体”，它能理解用户意图、调用工具、组织回复，本质上是一个完整应用；Skill则是一个可复用的“技能包”，它包含指令、工具定义和使用示例，是Agent的能力模块。可以这么理解：Agent是厨师，Skill是他掌握的菜谱，菜谱可以单独整理、分享给别人，但真正做菜的动作发生在Agent里。

第三组是自定义指令和Skill的关系。自定义指令更像是在工作台里对AI行为做一次临时约束，比如“以后用三段式写周报”，它调整的是对话风格；Skill则是结构化程度更高的能力封装，器里既有指令又有工具调用逻辑，还能在开放平台里发布和复用。

明白了这些基础概念，接入的时候就不会把“加一个工具”和“做一个Agent”混为一谈。

1.2 注册账号、实名认证与创建应用的4个步骤

账号和应用的创建流程比较标准，但中间有几个细节操作不对会卡住很久。

第一步是注册WorkBuddy账号，登录后在设置里找到开放平台入口，进入开发者后台时系统会引导你完成个人实名认证。这里要注意，个人开发者认证和企业开发者认证的权限范围不一样，个人认证虽然能用大部分能力，但某些涉及高并发、大配额的能力会受限，我先用个人身份走通全流程，量大的场景之后再申请升级。

第二步是创建应用。开发者后台有一个“创建应用”按钮，填应用名称、应用描述、所属分类。这里有个值得注意的坑：应用名称一旦确定，后续发布Skill、配置回调地址时都会绑定显示，建议想清楚再填，我一开始随便填了个“测试应用”，后面跟正式应用放在一起特别容易混淆，建议直接用项目代号命名。

第三步是获取AppID和AppSecret。AppID是公开的应用标识，AppSecret是签名密钥，相当于账号密码。平台只在你创建成功的这一次显示完整AppSecret，要立即保存到本地密码管理器里，我当时没复制，重新生成密钥又让一些已配置的网关注册信息全部失效，白白折腾了半小时。

第四步是配置回调地址和权限范围。如果你要做的是被动响应型Agent，只需要配置一个回调地址，用于接收平台推送的事件；如果要主动调用API，还要在权限管理里勾选对应的接口权限。回调地址的要求是必须是HTTPS，并且不能用IP地址直连。这一步很多人忽略，等到联调时才发现本地用HTTP根本收不到推送。

注意：AppSecret等同于账号的完全控制权，只能保存在服务端环境变量或密钥管理工具里，任何情况下都不能写进前端代码或提交到Git仓库。我在本地开发时用.env文件管理，并把这个文件加进了.gitignore。

1.3 本地环境准备：Python、密钥管理与调试工具

我习惯用Python做Agent接口联调，主要原因是第三方库生态好，处理JSON数据方便，写异步任务也不费劲。如果你更熟悉Node.js，思路一样，只是代码实现不同。

本地环境我建议准备三样东西。

第一是Python 3.9以上版本，安装requests和python-dotenv两个库。requests负责HTTP请求，python-dotenv负责把密钥从.env文件加载到环境变量。很多人直接把密钥硬编码在代码里，这是非常危险的习惯，尤其是后面你可能要把代码发布到公开仓库当示例。

第二是一个API调试工具。Postman当然可以，但我在调试Agent接口时更喜欢用VS Code的REST Client插件，原因很简单：REST Client可以用一个.http文件保存多个请求，而且支持写注释记录每个请求的用途，改起来比在Postman里点来点去快得多。你完全可以按自己的习惯来，但一定要有一个能保存请求历史的工具，因为Agent接口的调试经常要在同样请求参数下反复试。

第三是统一的项目目录结构。我建了一个最小可用的骨架：

workbuddy-agent/ ├── .env ├── config.py ├── main.py ├── tools/ │ ├── __init__.py │ └── query_todos.py └── logs/

config.py统一读配置，main.py放主流程，tools目录放工具函数，logs目录存请求日志。项目初期规模不大，保持这个结构足够清晰，等后面接更多工具时再按域拆模块。

本地环境准备好之后，下一步不是急着写代码，而是先想清楚这个Agent到底做什么。这一步想不明白，后面的实现全是白费劲。

2. Agent应用设计：先把场景想明白再写代码

我在上一轮试过做一个“全能助手型”Agent，什么都想让它干，结果它什么都干不精。Agent应用和传统软件最大的区别是：传统软件的逻辑是写死的，而Agent有自主决策空间，如果场景边界不清晰，它的自主性就会变成不确定性，回答经常“飘”。

2.1 个人开发者适合选什么场景来判断一下

我总结了一套简单的场景筛选标准，帮助判断哪些场景适合放进Agent里：

首先，任务是高频重复的。每天或者每周都要做的事，比如整理待办、归档文件、生成工作周报，这种任务值得让Agent介入。

其次，输入和输出是明确的。至少你要能说得清楚“给什么信息、期望得到什么结果”，比如给一段会议录音文字稿，期望输出会议纪要和行动事项。

再次，规则是可以描述的。Agent在处理时需要有清晰的判断依据，比如“按项目分组汇总”比“帮我整理一下”更容易落地。

最后，容错空间要足够。Agent偶尔会出错，如果场景是财务对账、医疗建议这种错一步就麻烦的领域，个人开发者还是先别碰。

拿我做的第一个WorkBuddy Agent来举例，我选的是“待办事项查询与整理”。输入是用户一句自然语言，比如“查看今天还有哪些没完成的事情”，输出是对应状态的待办列表，规则简单，出错也无非是显示不准确，不会造成实质损失。这个场景看似简单，但刚好能把Agent最核心的几项能力——意图理解、工具调用、结果回填——完整走一遍。

如果你还没想到做什么，我还有一个更保守的建议：做一个把任意文本转换成结构化摘要的Agent。输入一段文字，输出几个固定维度，比如时间、项目、负责人、下一步动作。这个场景对工具依赖少，可以先熟悉平台的Prompt和消息接口，再慢慢加工具。

2.2 把需求拆成Agent可执行的任务链路

设计Agent的过程，其实是把一句话需求翻译成一条可执行的任务链路。我常用的类比是点外卖：你说“来一份牛肉面”，这里面包含意图识别（知道你要吃的）、依赖查询（附近有没有卖牛肉面的店）、组合决策（选哪家）和结果确认（告诉你多少钱、多久能到）。Agent的工作模式就是这种链路，只是环节更抽象。

我在设计“待办事项查询与整理”Agent时，画出来的任务链路长这样：

用户输入待办相关的问题，进入Agent后先做意图识别，这一步由大模型完成，目的是判断用户是想查询、新增、修改还是删除待办。接着是参数抽取，从自然语言里提取关键信息，比如状态、时间范围、事项关键词。然后是工具调度，根据参数决定调用哪个本地工具函数。最后是结果组织，把工具返回的JSON数据转成自然语言回复。

你可能会问，大模型不是已经能理解自然语言了吗，为什么还要抽参数再调工具？这就是Agent和普通聊天的差异。如果直接让模型根据对话内容去查询数据库，模型会因为缺乏数据库权限和SQL能力而胡编乱造；正确的做法是让它把用户意图翻译成一个结构化的工具调用请求，由我们的代码来真正执行。这样代码的可靠性就保留住了，模型只负责“翻译”。

任务链路里还有一个重要部分，就是定义失败分支。传统程序有if-else，Agent也需要。我在设计里至少定义了三条失败路径：一是Agent无法理解用户意图时，它要主动说“我没理解，请换个说法”，而不是硬答；二是工具调用失败时，比如本地待办服务出错了，Agent要如实说明错误，而不是编造一份结果；三是参数缺少时，Agent要反问用户补充信息，比如用户只说“查一下待办”，没指定状态，就应该默认查全部，而不是强行猜一个状态。

把这四条分支写清楚，Agent的行为才算可控。

2.3 方案选型：裸API、官方SDK还是Agent框架

动手之前还有一个绕不开的选型问题，就是用什么方式接入。现在提到Agent开发，大家第一反应是上某个Agent框架，但我个人的建议是，个人开发者第一次接触WorkBuddy开放平台，先别急着上框架。

裸API直连是最底层但最清晰的路径。你直接调用开放平台的会话、消息和工具接口，自己管理上下文和调用状态。好处是整个数据流都在你掌控里，模型返回的每一个字段你都能看懂；坏处是写代码多一些，比如会话管理、错误重试都要自己做。

官方SDK帮你封装了鉴权、会话这些基础能力，开发速度快，但我在实际使用时发现，一旦遇到SDK处理不了的情况，比如自定义的超时策略、特殊的工具回传格式，你反而得去翻SDK源码，理解成本并不低。

通用Agent框架适合做复杂的多Agent协作，但代价是要先花时间理解框架的抽象概念，比如角色、记忆、规划器等。对这些概念不熟悉的话，调试时会觉得一切都在黑盒里。

我的建议是分阶段走。第一版用裸API直连方式，把消息流转和工具调用跑通，这个阶段重点在于理解Agent的执行逻辑；第二版再把重复代码收敛成自己的工具类，把回调、错误处理统一；等多场景需求出现了，再去考虑更重的框架。别一上来就给项目加一堆抽象，个人项目的第一目标是跑通。

3. 编码实战：从首个API调用到完整Agent应用

方案定了就开始写代码。这部分是整篇文章里最需要对照着实操的部分，我按我自己开发的推进顺序分成了几步，每一步都保留了我实际上会用的代码和日志。

3.1 第一步：获取访问令牌并跑通第一次对话

开放平台API的鉴权通常分两步：先用AppID和AppSecret申请AccessToken，再拿着Token访问业务接口。我封了一个config.py统一管理环境变量。

# config.py import os from dotenv import load_dotenv load_dotenv() APP_ID = os.getenv("WORKBUDDY_APP_ID") APP_SECRET = os.getenv("WORKBUDDY_APP_SECRET") BASE_URL = os.getenv("WORKBUDDY_BASE_URL", "https://openapi.workbuddy.ai")

然后在main.py里写获取Token和创建会话的逻辑。Token一般有时效性，为了演示我把流程写在同一个脚本里，实际项目里建议把Token缓存到内存或Redis里，避免每次都申请。

# main.py import requests import time def get_access_token(): url = f"{BASE_URL}/v1/auth/token" payload = {"app_id": APP_ID, "app_secret": APP_SECRET} resp = requests.post(url, json=payload, timeout=10) resp.raise_for_status() return resp.json()["access_token"] def create_session(token): url = f"{BASE_URL}/v1/agent/sessions" headers = {"Authorization": f"Bearer {token}"} resp = requests.post(url, headers=headers, json={"app_id": APP_ID}, timeout=10) resp.raise_for_status() return resp.json()["session_id"]

接着是发消息并获取Agent回复。这里有两种模式：同步返回和异步回调。同步模式适合单轮问答，发完消息直接拿结果；异步模式适合耗时长的任务，平台会在处理完成后把结果推送到你的回调地址。我第一版用同步模式，实现起来最简单。

def send_message(token, session_id, content): url = f"{BASE_URL}/v1/agent/sessions/{session_id}/messages" headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"} payload = {"role": "user", "content": content, "stream": False} resp = requests.post(url, json=payload, headers=headers, timeout=30) resp.raise_for_status() return resp.json() if __name__ == "__main__": token = get_access_token() session_id = create_session(token) result = send_message(token, session_id, "你好，先认识一下，我叫小林。") print(result)

这里有个经验值得说一下：第一次跑通后，我建议把完整的返回JSON原样保存到logs目录。因为Agent接口的返回结构比普通API复杂，里面通常包含消息ID、会话ID、时间戳、可能还有引用来源和工具调用状态。把这些结构摸清楚，后续调试会顺手很多。

响应解析也有讲究。不要把整个JSON直接塞给下游逻辑，先抽取出真正用到的字段，比如消息内容部分。我记得第一次看到返回结构时一脸懵，后来养成了“先打印、再解析、最后封装”的习惯，效率高很多。

3.2 第二步：给Agent添加一个真实工具，解锁工具调用能力

光是聊天的Agent价值有限，让Agent能真正执行任务才是关键。这一步我给Agent挂上了一个“查询待办事项”的工具。

首先要理解工具调用的协作方式。当用户说“帮我看看今天有哪些没做完”，我们并不把这条问题直接发到数据库去查，而是调用Agent接口时声明一个可用的工具描述。模型根据用户问题，判断需要调用该工具，然后在返回结果里用结构化字段告诉我们“请用这些参数调用query_todos工具”。我们的程序收到这个请求后，执行本地函数，再把执行结果作为一条新消息回传给模型，模型最终生成面向用户的回答。

工具描述用JSON Schema格式定义，我在代码里维护了一个TOOLS列表：

# tools/query_todos.py def query_todos(status: str = "all"): mock_data = [ {"id": 1, "title": "写周报", "status": "done"}, {"id": 2, "title": "提交报销单", "status": "pending"}, {"id": 3, "title": "预约会议室", "status": "pending"}, ] if status == "all": return mock_data return [item for item in mock_data if item["status"] == status]

工具描述里最关键的是description字段。我第一次写的是“查询待办事项”，结果模型经常在该查“已完成”时把所有数据都返回，后来我把描述改成“查询当前用户的待办事项列表，status参数支持all、pending、done三种取值”，模型的选择准确率明显提升。这个细节很值得记住：工具描述本质上是在教模型如何正确使用工具，写清楚取值范围和边界条件，比写一堆华丽的功能介绍有用得多。

在发送消息时，把工具声明放在请求里：

TOOL_QUERY_TODOS = { "name": "query_todos", "description": "查询当前用户的待办事项列表，status参数支持all、pending、done三种取值", "parameters": { "type": "object", "properties": { "status": { "type": "string", "enum": ["all", "pending", "done"], "description": "待办状态筛选条件，默认all" } }, "required": ["status"] } } def send_message_with_tools(token, session_id, content): url = f"{BASE_URL}/v1/agent/sessions/{session_id}/messages" headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"} payload = { "role": "user", "content": content, "tools": [TOOL_QUERY_TODOS] } resp = requests.post(url, json=payload, headers=headers, timeout=30) return resp.json()

当返回结果里出现工具调用请求时，我们需要先解析出工具名和参数，再调用本地函数，然后把结果回传。

def run_agent(): token = get_access_token() session_id = create_session(token) result = send_message_with_tools(token, session_id, "查一下今天还没完成的待办") message = result["message"] if "tool_calls" in message and message["tool_calls"]: for call in message["tool_calls"]: if call["name"] == "query_todos": status = call["arguments"].get("status", "all") tool_result = query_todos(status) # 把工具结果回传给Agent follow_up = { "role": "tool", "name": call["name"], "content": json.dumps(tool_result, ensure_ascii=False), "tool_call_id": call["id"] } final = send_tool_result(token, session_id, follow_up) print(final["message"]["content"])

这里有一个踩坑教训：工具返回的结果必须是JSON字符串，而不是Python对象。我第一次直接把列表传进去，平台解析失败，卡了将近一个小时。

另一个心得是，本地调试工具函数前，先写两个固定的测试用例。我准备了一组老数据，分别测“全部待办”和“仅未完成待办”，这样每次改完代码只要跑一遍测试，就能确认工具函数本身没有回归问题，而不是等到Agent链路调用时才去排查是模型问题还是函数问题。

3.3 第三步：把能力封装成可复用的Skill

工具调用跑通之后，我开始把整套“查询待办-整理待办”的能力封装成Skill。这一步的价值在于，下次我想让Agent处理类似任务时，不需要重新写一遍Prompt和工具注册，直接挂载这个Skill就能用。

WorkBuddy的Skill本质上是一个结构化的配置包，里面包含Skill名称、描述、指令、工具和示例。我用的配置大概长这样：

name: todo_management_skill description: 处理待办事项的查询、新增和完成标记，适合日常工作流场景 instructions: | 1. 当用户表达查询待办意愿时，先识别是否需要指定状态 2. 如果用户没有指定状态，默认查询全部 3. 查询结果按状态分组展示 4. 如果查询结果为空，明确告知用户“当前没有对应状态的待办” tools: - query_todos examples: - input: 看看我今天还剩什么事 output: | 你今天还有2件未完成： - 提交报销单 - 预约会议室

我建议你在定义instructions时，把“用户没说清楚时默认怎么办”这种边界情况都写进去，这和写API参数默认值是一个道理，能有效减少Agent的随意发挥。

Skill在平台后台有两种组织方式，一种是在可视化编辑器里配置，通过表单填写；另一种是上传配置包。我个人更推荐先写成本地配置文件再导入，因为这样Skill内容可以进Git做版本管理。后续迭代时，靠Git记录能知道哪次修改导致了行为变化，比在后台盲改靠谱得多。

3.4 第四步：本地调试与日志记录的三板斧

Agent开发的调试难度比普通接口高，因为中间隔着模型的不确定性。我摸索出三个比较有效的调试习惯。

第一个习惯是所有请求和响应都留完整日志。不只是记录接口状态码，而是把发送给Agent的完整Payload和返回的完整JSON都写到本地日志文件。为啥要这么干？因为Agent的请求是带上下文的，后面每次发送消息都涉及上下文变化，没有完整日志，很难复盘一个Bug是在第几轮对话后出现的。

第二个习惯是打印工具调用的完整链路。每次Agent要调用工具时，把模型生成的工具名、参数、以及工具执行后的返回值都打出来。这样一步错在哪里一目了然：是模型抽错了参数，还是工具函数执行时报的错，还是回传格式问题。

第三个习惯是准备固定的回归测试输入。我建了一个test_inputs.txt文件，存了10条不同风格的测试问题，比如“查待办”“今天还有什么没做完”“把写周报标记成完成”。每次改动代码，就把这10条输入按顺序跑一遍，看结果是否符合预期。模型天然有随机性，不追求每次输出完全一样，但关键行为必须稳定。如果某条输入连续三次行为不一致，那一定是Prompt或工具描述里有歧义，需要改配置而不是碰运气。

4. 发布上线与常见问题排查

本地调通只是第一步。个人开发者把一个WorkBuddy Agent从沙箱环境发布到生产，中间还有一些流程要走，也有一堆实际运行中才会踩到的问题。

4.1 从沙箱到生产：发布流程与上线检查清单

WorkBuddy开放平台会给每个开发应用分配沙箱环境，沙箱环境里的数据和生产环境完全隔离，适合做联调。我在沙箱里把完整链路跑通后，做了一次正式发布，流程大致是四步：

第一步，在生产环境后台重新创建应用配置，重新生成AppSecret。这里有坑：我一开始以为沙箱和生产共用一套应用配置，后来发现两者要分开建，尤其是回调地址和生产环境的差异很容易漏配。

第二步，配置生产环境的服务地址与回调地址。因为生产环境要求回调地址必须是公网可访问的HTTPS地址，本地localhost是收不到推送的，所以我把测试用的Agent服务部署到了一台云服务器上。这个环节建议先把服务跑起来，再配置回调，然后用平台提供的“测试回调”功能验证，等在线成功再发正式请求。

第三步，进行小流量验证。我自己写了一个非常简单的验证脚本，随机挑少量用户请求转发到生产环境，对比响应结果。个人项目也要给自己保留回滚空间：发布前记录上一个稳定版本的配置包，如果新版本在监控期内表现异常，能快速切回去。

第四步，上线后重点盯两个指标：调用量和错误率。开放平台后台能看到按小时的调用趋势，错误率一旦超过5%就要立刻看日志。不用说等到用户找上门，自己的监控要先报警。

4.2 高频问题排查实录与避坑清单

我在接入过程中遇到了不少问题，整理成了下面这个表，都是亲测有效的解决方法。

第一个坑我印象最深。有一次怎么调都是401，折腾半小时发现.env文件里AppSecret复制时多了一个换行符。像这种问题不会报“密钥无效”，而是只返回401，排查时先打印环境变量的repr值，确认没有隐藏字符。

第二个坑是回调地址问题。我一开始以为回调地址只是用来接收事件，不急着配，结果发现Agent的很多异步结果推送都依赖这个地址。这里建议直接用平台自带的回调测试按钮，发送一条测试消息，看自己的服务能否收到，确认通路再继续。

第三个坑关于模型过度发挥。给Agent配好工具后，它不应该在工具范围之外乱说话。比如用户问“今天天气怎么样”，我的Agent明明没有天气工具，它却回答“今天天气晴朗”，这就是幻觉。解决这个问题不能只靠Prompt，更有效的办法是在调度层加一个校验，判断模型的回复是否真的来自工具执行结果。如果不在工具执行链路内，就直接回复“这个能力我还没配置”。

4.3 关于Agent记忆的实现心得

Agent记忆是目前个人开发者最容易被绕进去的点。很多人在第一步就想着给Agent做长期记忆，结果代码复杂度直线上升，效果还不稳定。

我的建议是分清楚短期记忆和长期记忆。短期记忆就是上下文窗口里的对话内容，这部分由平台自动管理，不需要我们操心。个人开发者真正需要设计的是长期记忆——跨会话保留的用户偏好、历史任务结果等。

实现长期记忆不需要复杂的向量数据库，最简单可靠的方法是落盘到SQLite或者JSON文件。我在项目里建了一张user_profile表，存用户ID、关键信息和更新时间。当Agent发现用户给了新的偏好信息时，通过工具函数写入这张表；下次新会话开始时，把这些信息作为系统提示的一部分注入上下文。

这个方法初期够用，但要注意控制注入信息的长度。我记得有一版把用户过去三个月的所有操作都注入，结果上下文被大量无效信息占满，基础对话能力直线下降。后来改成只保留最近10条关键信息，效果明显回升。

4.4 发布后持续迭代的一点建议

Agent上线不等于结束，而是另一个迭代循环的开始。个人开发者没有运营团队，但可以用Log聚合的方式做最基础的线上观测：把线上请求日志按小时做一次摘要统计，看用户的真实问题集中在哪几类，然后针对性优化Skill里的instructions和工具描述。

我目前的做法是每周抽20条线上日志数据，人工标注其中哪些回答令人满意、哪些是失败的。前几周一定会发现一些设计时没想到的边缘Case，比如用户会问“待办里有没有明天截止的”，这本来需要解析截止日期，但我并没有在工具里加上时间筛选逻辑，于是新需求就浮现出来了。把它补充进工具参数，Agent的能力就多了一层。这比闷头写代码有效得多。

另外一个小习惯是给Skill配置版本号。每次修改instructions或工具定义，都在配置包里把版本号加一。这样做的好处是，当你发现某个改动带来了问题，能立刻对比出是不是上个版本的行为更合理，也方便回滚。

5. 几个让我少走弯路的实操习惯

最后这几条是我全程做完后最有价值的沉淀，与其说是技术，不如说是工作习惯。它们帮我省了很多时间，也希望对你有些启发。

第一，配置和代码分离。AppID、AppSecret、BaseURL这些信息全部放环境变量，不要硬编码。这一步看着多此一举，但当项目后来部署到服务器、或者被朋友拿去复现时，你会感谢当时这个决定。

第二，Prompt和Skill配置都纳入版本管理。很多人改Prompt是一次性在后台改完就不管了，但Agent的行为变化往往就是从一个词的变化开始的。把每次修改的diff存在Git里，能帮你定位“到底哪个词导致回答风格变了”。

第三，每次修改只动一个变量。迭代Agent时，最忌讳一次改三个地方，比如同时改了Skill描述、工具说明、系统指令。一旦效果变差，你根本不知道是哪里导致的。我现在的习惯是：一次只改一处，改完跑一遍固定的回归测试，再决定下一步。

第四，给本地测试留一组固定输入。我前面提到的test_inputs.txt，一直被保留着。无论改了配置还是换了新模型版本，我都会先用这组输入跑一遍。它不能保证Agent完美，但能保证核心行为没有明显退步。

第五，发布前至少找三个人试用。我自己测的时候觉得很顺了，但让朋友用的时候，他们第一时间问的是“这个Agent能帮我干什么”，而不是去关心功能细节。这说明我的Skills描述里缺少面向使用者的说明文案。后来我在每个Skill的description里都补上了一句话版本的使用说明，用户的接受度高了很多。这件事让我意识到，Agent应用的用户体验不止在对话框里，也在用户看到它的第一眼。

整个过程走下来，我最深的体会是：Agent开发真正难的不是调大模型接口，而是把一个含糊不清的需求翻译成可执行、可验证、可回退的规则。WorkBuddy开放平台把很多基础设施做好了，剩下的是我们如何定义边界、描述工具、管好上下文。如果你正准备开始尝试，我建议你先选一个特别小、特别具体的场景，走通一遍账号创建到Skill发布的全流程。等你跑通第一个Agent，再回头想多场景、多Agent协同的扩展，会发现之前的每一步都是打了底子的。

下一篇我打算把多个Skill组合成一个复杂工作流的实践写一写，比如“定时抓取信息-自动生成摘要-推送到待办”这样的全自动链路。如果你有想了解的具体环节，欢迎在评论区告诉我。