十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Agent Zero Tiny Local 通信契约:为小型本地模型设计的 Action-First 单 JSON 工具调用协议

Agent Zero Tiny Local 通信契约:为小型本地模型设计的 Action-First 单 JSON 工具调用协议 Agent Zero Tiny Local 通信契约为小型本地模型设计的 Action-First 单 JSON 工具调用协议【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读本文围绕 Agent Zero 开源框架内置的tiny-localAgent Profileagents/tiny-local/agent.yaml展开深入解析其通信契约文档 agents/tiny-local/prompts/agent.system.main.communication.md。该契约针对 Ollama、LM Studio、Qwen 等小型本地模型倾向于解释动作而不调用工具的通病将 Agent 的每条可见回复强制收敛为恰好一个合法 JSON 对象仅含tool_name与tool_args两个顶层字段并定义了续接词语义、重复消息恢复等运行规则。读完本文你将掌握 Tiny Local 契约的完整条款、它在系统提示System Prompt中的组装方式、配套的工具示例与恢复提示以及框架测试如何固化这一行为契约。一、Tiny Local Profile 的定位为什么需要一份最小工具调用契约在 Agent Zero 中Agent Profile 通过 agents/ 目录下的agent.yaml元数据title、description、context向框架声明自身用途由 helpers/subagents.py 扫描并按agents/profile/约定加载对应提示文件。默认场景agent0/defaultProfile允许模型在回复中携带thoughts思维链、headline标题等字段但对于参数量小、指令遵循能力有限的本地模型字段越多越容易跑偏——模型可能会把精力花在写思考过程上而不是真正发起工具调用。Tiny Local Profile 正是为此设计的title: Tiny Local description: Action-first profile for small local models that need a minimal tool-call contract. context: Use this agent when running small local chat models through Ollama, LM Studio, or similar providers and the model tends to explain actions instead of calling tools.从 agents/tiny-local/AGENTS.md 的 Ownership 声明可以看出该 Profile 采用纯提示词策略约束本地模型不引入任何解析器修复、重复抑制运行时或专用模型传输层同时明确要求提示文本足够短以便小模型能够跟随。其核心文件分工为prompts/agent.system.main.communication.md本地模型通信契约本文主体prompts/agent.system.main.solving.md问题求解契约抑制继承自默认 Profile 的可见推理要求prompts/agent.system.tools.md工具清单包装与输出形状提醒prompts/agent.system.tool.*.md各工具的 Tiny Local 版示例去除thoughts/headline字段prompts/fw.msg_repeat.md框架判定重复消息时的恢复指令。二、通信契约核心条款逐条解析agents/tiny-local/prompts/agent.system.main.communication.md 全文虽短却是一条高度精确的机器可解析协议。下面逐条展开其含义与设计动机。2.1 身份与行动准则You are Agent Zero. Act on the users behalf. When the user asks you to do something, do it directly. Do not explain how the user could do it themselves.身份锚定明确模型扮演 Agent Zero代表用户执行任务而非聊天助手。Action-First用户提出请求后必须直接执行禁止教用户自己怎么做式的回复。这是解决本地模型解释替代行动问题的第一道防线。与之配套的 agents/tiny-local/prompts/agent.system.main.solving.md 进一步规定需要 shell 命令、文件、浏览器等能力时立即选择合适的已列工具每轮只调用一个工具除非parallel工具被列出且确实有用检查输出后再决定下一步绝不允许把超时输出或仍在运行的命令当作成功。2.2 单 JSON 输出契约核心Your visible assistant message must be exactly one valid JSON object. Use exactly these top-level fields: tool_name and tool_args. Do not include markdown fences, prose before the JSON, prose after the JSON, hidden reasoning, analysis, thoughts, or headlines.这是整个契约的基石无论模型内心如何推理其可见输出必须且只能是{tool_name:response,tool_args:{text:Answer briefly.}}三条硬性约束缺一不可恰好一个 JSON 对象不允许输出两个对象、数组或拼接文本仅两个顶层字段tool_name工具标识与tool_args参数字典显式剔除thoughts、headline、分析、计划等默认 Profile 常见字段零杂讯不允许 markdown 围栏 或 ~~~、JSON 前后的散文、隐藏推理或标题。对比默认 Profile 的通信提示prompts/agent.system.main.communication.md允许thoughts、headline、tool_name、tool_args四字段Tiny Local 将字段裁剪到只剩动作正是为了让参数量有限的模型把全部输出预算花在正确的工具调用上。2.3 工具选择约束Choose a tool from the tools listed in this system prompt. Do not invent tool names, action names, or generic names such as read, write, terminal, or multi.工具名必须来自系统提示中列出的工具清单由 agents/tiny-local/prompts/agent.system.tools.md 通过{{tools}}占位符注入。动作名不是工具名严禁发明multi、read、write、terminal等通用批量名称工具名是字面 API 标识需逐字复制包括behaviour_adjustment这类特殊拼写见 prompts/agent.system.main.communication_additions.md。这一约束在测试 tests/test_default_prompt_budget.py 中也被断言为系统提示的固定组成部分。2.4 response 工具的使用边界For a final user-facing answer, use the response tool. Use response only when the work is complete, blocked, or the user is only acknowledging completed work.response是面向用户的最终答复工具仅在三种情况下可用任务已完成、任务被阻塞、用户仅在对已完成的工作表示确认。Tiny Local 版工具示例agents/tiny-local/prompts/agent.system.tool.response.md给出了参数说明tool_args中仅需text简洁的最终答复文本并强调不要用本工具回应 proceed/continue/go ahead 等续接请求。2.5 续接词语义proceed 就是立即执行下一步If the user says proceed, continue, go ahead, do it, excellent proceed, or similar after you named a next step or there is unfinished work, do not answer with a promise or status update. Call the next appropriate tool.当模型在上一轮已经点名了下一步骤、而任务尚未完成时用户说proceed/continue/go ahead/do it/excellent proceed等等同于继续执行而不是汇报一下进度。模型必须立即调用下一个合适的工具而不是承诺我将开始或发送状态更新。该规则在 agents/tiny-local/prompts/agent.system.main.solving.md 中被复述并强化Do not respond by saying you will begin, continue, start, proceed, or investigate. Use a real tool call unless the task is already complete or blocked.2.6 畸形 / 重复消息的恢复规则If the framework warns that your prior message was malformed, repeated, or reasoning-only, output a corrected JSON tool request immediately without explaining the warning. When the warning says you sent the same message again, do not resend the same JSON. Change the tool, action, arguments, or final answer so the next message is meaningfully different.畸形/仅推理警告立即输出修正后的 JSON 工具请求不解释、不道歉。重复消息警告绝不能原样重发同一 JSON必须改变工具、动作、参数或最终答复使下一条消息有意义地不同。配套的恢复提示 agents/tiny-local/prompts/fw.msg_repeat.md 提供了具体操作清单若工作未完成则调用下一个真实工具若之前误用response则替换为真实工具调用若文件写入已成功则改为读取该文件或用观察到的结果答复若命令已运行则检查其输出或运行不同的下一条命令若确实无其他动作可选才用response简短报告阻塞原因。三、契约的组装include 机制与提示文件层级Tiny Local 通信契约通过框架的{{ include ... }}模板机制与全局提示组装在一起。其调用链如下系统手册 prompts/agent.system.main.md 依次 includerole、specifics、environment、communication、solving、tips等片段对于tiny-localProfilecommunication片段被 agents/tiny-local/prompts/agent.system.main.communication.md 覆盖即本文主体该文件末尾的{{ include agent.system.main.communication_additions.md }}再追加全局附加条款消息类型标注、§§替换语法等该附加文件位于 prompts/agent.system.main.communication_additions.md工具清单由 agents/tiny-local/prompts/agent.system.tools.md 包裹其{{tools}}占位符在运行时被替换为实际可用工具列表并在末尾重申 Tiny Local Output Rule忽略继承示例中可能出现的thoughts/headline禁止在 JSON 对象之外输出任何内容。测试 tests/test_default_prompt_budget.py 对组装后的系统提示做了逐条断言例如必须包含 Your visible assistant message must be exactly one valid JSON object.、Use exactly these top-level fields:tool_nameandtool_args.、Do not explain what command the user could run manually.、以及 ## Tiny Local Output Rule同时断言通信/工具/恢复各片段中不得出现~~~json围栏与thoughts/headline字段——从测试层面把单 JSON、无杂讯契约固化下来。此外test_tiny_local_profile_is_discoverable验证tiny-local会以 Tiny Local 标签出现在 helpers/subagents.py 的 Profile 扫描结果中可被正常切换使用。四、Tiny Local 契约下的工具调用实战示例通信契约的价值最终体现在可被小模型稳定复现的工具调用格式上。下面展示 Tiny Local 各工具示例文件中的标准调用形态均为单行 JSON无围栏、无前后缀。4.1 执行命令 / 脚本code_execution_toolagents/tiny-local/prompts/agent.system.tool.code_exe.md 定义了tool_args参数runtimeterminal、python、nodejs或output、code命令或脚本、session终端会话 ID默认0、reset运行前是否结束会话true/false。示例{tool_name:code_execution_tool,tool_args:{runtime:terminal,session:0,reset:false,code:ls -1 /tmp | wc -l}}{tool_name:code_execution_tool,tool_args:{runtime:python,session:0,reset:false,code:import os\nprint(os.getcwd())}}{tool_name:code_execution_tool,tool_args:{runtime:output,session:0}}配套规则包括用runtimeoutput轮询运行中的任务用input处理交互式终端提示会话卡住时以相同session并带resettrue再次调用不得从超时输出或仍在运行的命令声称成功统计文件时优先find而非ls。4.2 读写文件text_editoragents/tiny-local/prompts/agent.system.tool.text_editor.md 定义了actionread/write/patch、path绝对路径、contentwrite时的完整内容、open_in_canvas用户明确要求用 Canvas/Editor 打开 Markdown 时置true。示例{tool_name:text_editor,tool_args:{action:write,path:/a0/usr/workdir/TODO.md,content:# TODO\n- [ ] First item\n,open_in_canvas:true}}{tool_name:text_editor,tool_args:{action:read,path:/a0/usr/workdir/TODO.md}}{tool_name:text_editor,tool_args:{action:patch,path:/a0/usr/workdir/TODO.md,old_text:- [ ] First item,new_text:- [x] First item}}规则强调写入或 patch 成功后不得重复同一工具调用除非需要不同动作否则应改用response。4.3 最终答复response{tool_name:response,tool_args:{text:There are 24 files in /tmp.}}仅当任务完成、被阻塞或无需工具时使用text保持简洁。五、消息协议与替换语法的附加条款通信契约末尾 include 的附加条款 prompts/agent.system.main.communication_additions.md 补充了框架消息语义帮助小模型正确解读上下文用户消息可能包含上级指令、工具结果与框架注释工具调用的闭合}视为回合结束信号模型须立即终止生成以(voice)开头的消息转录可能不完美以[PROTOCOL]开头的消息是必须遵守的指令以[EXTRAS]结尾的消息只是上下文而非新指令工具名是字面 API ID必须逐字复制如behaviour_adjustment可在tool_args内使用替换语法§§name(params)与§§include(abs_path)优先用include复用已有文件内容而非重写长文本。六、验证与回归测试如何锁定通信契约Tiny Local 契约并非文档写了就行tests/test_default_prompt_budget.py 用三类测试从外部锁定其行为组装验证test_tiny_local_profile_prompt_is_action_first_json_contract渲染tiny-local系统提示后逐条断言身份句、单 JSON 契约、tool_name/tool_args字段约束、response使用边界、续接词规则、恢复规则与 Tiny Local Output Rule 全部在场负向约束断言各 Tiny Local 提示片段不含~~~json围栏、不含thoughts/headline字段、不含默认 Profile 的可见推理要求从源头防止字段回潮可发现性test_tiny_local_profile_is_discoverable确保tiny-local以 Tiny Local 标签出现在 helpers/subagents.py 的 Profile 清单中且test_rendered_profiles_strip_json_fences覆盖了tiny-local在内的五个 Profile 渲染后均无 JSON 围栏残留。此外agents/tiny-local/AGENTS.md 明确要求修改通信提示后必须重新渲染tiny-local系统提示并运行pytest tests/test_default_prompt_budget.py做提示与 Profile 回归。这保证了提示即代码、契约可测试。七、使用前提与限制适用模型tiny-local面向 Ollama、LM Studio、Qwen 及同类小型本地模型若你使用的模型能力较强默认 Profileagent0允许thoughts/headline的富格式输出功能面更完整。纯提示词方案从 agents/tiny-local/AGENTS.md 可知该 Profile 不引入解析器修复、重复抑制运行时或文本编辑器运行时行为重复消息处理仅通过 Profile 提示收紧——因此最终效果仍取决于所选本地模型的指令遵循能力。运行时组装工具清单由{{tools}}占位符在运行时注入实际可用工具以 agents/tiny-local/prompts/agent.system.tools.md 渲染结果为准确认。结语Tiny Local 通信契约是 Agent Zero 应对小模型 工具调用这一现实难题的极简工程方案以恰好一个 JSON、仅tool_nametool_args为轴心配合续接词执行语义、重复消息恢复规则与测试固化把不确定的模型输出收敛为稳定的动作流。对希望用本地小模型驱动 Agent Zero 的开发者而言理解 agents/tiny-local/prompts/agent.system.main.communication.md 这份契约就等于掌握了该 Profile 全部行为规则的源头。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表