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 Profile（agents/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 user's 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-localProfile，communication片段被 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_name"and"tool_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_tool

agents/tiny-local/prompts/agent.system.tool.code_exe.md 定义了tool_args参数：runtime（terminal、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}}

配套规则包括：用runtime=output轮询运行中的任务；用input处理交互式终端提示；会话卡住时以相同session并带reset=true再次调用；不得从超时输出或仍在运行的命令声称成功；统计文件时优先find而非ls。

4.2 读写文件：text_editor

agents/tiny-local/prompts/agent.system.tool.text_editor.md 定义了action（read/write/patch）、path（绝对路径）、content（write时的完整内容）、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 及同类小型本地模型；若你使用的模型能力较强，默认 Profile（agent0）允许thoughts/headline的富格式输出，功能面更完整。
纯提示词方案：从 agents/tiny-local/AGENTS.md 可知，该 Profile 不引入解析器修复、重复抑制运行时或文本编辑器运行时行为，重复消息处理仅通过 Profile 提示收紧——因此最终效果仍取决于所选本地模型的指令遵循能力。
运行时组装：工具清单由{{tools}}占位符在运行时注入，实际可用工具以 agents/tiny-local/prompts/agent.system.tools.md 渲染结果为准确认。

结语

Tiny Local 通信契约是 Agent Zero 应对"小模型 + 工具调用"这一现实难题的极简工程方案：以"恰好一个 JSON、仅tool_name+tool_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），仅供参考

企业官网建设流程全解析