
Agent Zero Tiny Local 配置文件深度解析为小型本地模型定制的行动优先提示词契约【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读Agent Zero 框架内置了名为Tiny Local的 Agent Profile专门用于驱动 Ollama、LM Studio、Qwen 等小型本地聊天模型。由于参数量小、指令遵循能力有限这类模型在默认 Agent 配置下容易只说不做——反复输出解释、状态承诺或可见推理文本而不是真正调用工具。Tiny Local 通过一套纯提示词prompt-only的极简 JSON 工具调用契约把行动优先action-first行为固化到系统提示词层面同时与框架核心执行逻辑完全隔离。读完本文你将掌握 Tiny Local 配置的完整文件结构、每个提示词文件的所有权边界、其本地契约的设计取舍以及如何通过测试与命令验证该配置的正确性。一、Tiny Local 配置的定位与设计目标Tiny Local 是 Agent Zero 中随仓库分发的 Agent Profile 之一。其元数据定义在 agent.yaml 中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.md 中的 Purpose 声明可以看出它的定位有两点核心**拥有Own**随仓库捆绑的 Tiny Local 配置服务对象是小型/本地聊天模型将本地模型的行为约束完全保持在提示词层面与框架核心执行逻辑隔离Keep local-model behavior prompt-only and isolated from core framework execution。这意味着 Tiny Local 不是通过修改 Python 执行代码来修补本地模型而是把全部纠偏手段收敛在提示词文本中。这种设计让框架核心保持单一、可维护同时让每个 Profile 可以独立演进其行为契约。二、文件结构与所有权边界Tiny Local 的配置由 1 个元数据文件、1 个契约文件组和 7 个提示词文件组成。其所有权划分在 AGENTS.md 的 Ownership 一节中有严格声明文件所有权职责agent.yaml配置元数据负责 Profile 的发现discovery与切换profile switchingprompts/agent.system.main.communication.md本地模型的通信契约communication contractprompts/agent.system.main.solving.md本地模型的问题求解契约并压制继承自默认 Profile 的可见推理visible reasoning要求prompts/fw.msg_repeat.md当框架拒绝重复的助手消息时Tiny Local 专属的恢复指令prompts/agent.system.tools.md工具列表包装器以及工具列表之后的最终输出形态提醒prompts/agent.system.tool.*.md 等Tiny Local 专属的工具示例规避继承示例中携带的推理字段与重复写入行为这种一文件一职责的划分与测试test_tiny_local_profile_is_discoverable相互印证测试通过 helpers/subagents.py 中的get_all_agents_list()扫描所有 Agent 根目录断言profiles[tiny-local] Tiny Local见 tests/test_default_prompt_budget.py。从源码结构看Profile 的发现机制会按usr/projects/、usr/agents、plugins/、默认目录的优先级合并同名 Profile因此 Tiny Local 也可以被用户或项目级配置覆盖。三、本地契约Local Contracts详解这是 AGENTS.md 中最核心的技术约束共 6 条逐条展开如下。3.1 保留 Agent Zero 标准工具调用形态tool_nametool_argsTiny Local 不发明新的工具协议而是严格继承框架的 JSON 工具调用形态。在 prompts/agent.system.main.communication.md 中明确要求Your visible assistant message must be exactly one valid JSON object. Use exactly these top-level fields:tool_nameandtool_args.即每次助手可见消息必须恰好是一个合法 JSON 对象且只能包含这两个顶层字段。这一约束也同步写入了 prompts/agent.system.tools.mdEvery tool request must be exactly one JSON object with only these top-level fields: - tool_name - tool_args3.2 不引入任何运行时修补runtime patchingAGENTS.md 明确禁止在此配置中添加四类运行时行为parser repair解析器修复duplicate suppression runtime重复消息抑制运行时model transport模型传输层text-editor runtime behavior文本编辑器运行时行为。换言之重复消息的处理、JSON 容错等能力一律不允许下沉到 Python 运行时只能通过 Profile 提示词收紧。这保证了核心执行路径不被本地模型兼容性污染也让测试可以纯文本断言 Profile 行为。3.3 重复消息处理只通过 Profile 提示词收紧当模型重复发送同一条 JSON 工具请求时框架会注入 prompts/fw.msg_repeat.md 的恢复指令。其核心要求是必须做出不同的动作而不是原样重发。指令给出了 6 个可执行的替代方向工作未完成 → 为下一步调用真实工具之前的 JSON 用了response但仍有工作 → 替换为下一个真实工具调用文件写入/补丁已成功 → 读取该文件或用观察到的结果作答命令已运行 → 检查其输出或运行不同的下一步命令用户只说proceed/continue→ 用下一个真实工具调用继续无不同动作可行 → 用response简短报告阻塞原因。通信契约中同样强调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.收到格式错误/重复/纯推理警告时立即输出修正后的 JSON 工具请求不要解释警告。3.4 提示词保持短小适配小模型Keep prompt text short enough for small local models to follow 是 Tiny Local 的硬性约束。小参数模型的上下文窗口与指令遵循能力有限因此 Tiny Local 的各提示词文件刻意精简——例如code_exe工具说明只有约 20 行response工具说明不足 15 行fw.msg_repeat.md也压缩到 11 行。相比默认 Profile 的庞大提示词表面Tiny Local 的目标是足够小模型能逐字遵守。3.5 续接词proceed/continue 执行指令而非状态回复这是行动优先配置中最反直觉、也最关键的一条契约。AGENTS.md 规定Treat continuation requests such asproceedorcontinueas commands to execute the next unfinished step, not as prompts for another status response.通信契约中给出了触发词清单proceed、continue、go ahead、do it、excellent proceed 等。一旦模型已声明下一步但尚未完成用户说出这些词时模型必须立即调用下一个合适的工具而不是回复我将开始…我会继续…这类承诺性文本。求解契约 prompts/agent.system.main.solving.md 用更严格的措辞重申Continuation words such as proceed, continue, go ahead, do it, and excellent proceed mean execute the next unfinished step. 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.3.6 禁止用户专属信息AGENTS.md 要求配置内不得包含用户特定的提供商名称、API 密钥、本地路径或密钥secrets。这是可移植性的底线——Tiny Local 提示词可以被任何用户、任何本地模型直接复用而不会泄露环境信息。四、行动优先的提示词体系从通信到求解到工具4.1 通信契约一条只说 JSON的硬约束prompts/agent.system.main.communication.md 是整个配置的入口定义了模型与框架之间唯一的交互协议直接以用户名义行动Act on the users behalf不要解释用户如何自己操作可见消息必须是一个合法 JSON 对象禁止 markdown 围栏fences、JSON 前后的散文、隐藏推理、分析、思考或标题只能选择系统提示词中列出的工具禁止发明read、write、terminal、multi等泛化名称面向用户的最终答复统一走response工具且仅在工作完成、受阻、或用户仅确认已完成工作时使用。它给出的最终答复形态示例为{tool_name:response,tool_args:{text:Answer briefly.}}同时该文件末尾通过{{ include agent.system.main.communication_additions.md }}引入了全局通信补充说明见 prompts/agent.system.main.communication_additions.md其中定义了[PROTOCOL]/[EXTRAS]消息标记、工具名必须逐字复制含behaviour_adjustment这类拼写以及§§include(abs_path)替换机制等通用协议。4.2 求解契约压制继承的可见推理要求prompts/agent.system.main.solving.md 承担双重职责一是定义行动优先的问题求解流程二是显式压制从默认 Profile 继承下来的thoughts思考、headline标题、分析、计划等可见推理字段。测试对此有精确断言explain each step in thoughts not in solving_prompt。该文件规定的工作流是简单问题 → 直接用response工具回答需要 shell、文件、浏览器等能力 → 立即选择列表中的合适工具每轮保持一个工具调用除非parallel工具确实有用先检查输出再决定下一个调用绝不从超时输出或仍在运行的命令推断成功工具结果成功后不重复相同的工具调用收到重复消息警告后不重复相同的状态回复或工具请求而是选择下一个不同的可执行动作或报告阻塞完成时用response给出简短结果。4.3 工具包装器与 Tiny Local 输出规则prompts/agent.system.tools.md 在{{tools}}占位符位置注入实际工具列表并在末尾追加 Tiny Local Output RuleSome inherited tool examples may showthoughtsorheadline. Ignore that shape for this profile. Do not includethoughts,headline, analysis, markdown fences, or prose outside the JSON object.这条规则是继承抑制机制的关键默认 Profile 的工具示例往往带thoughts/headline字段Tiny Local 明确宣布忽略这些继承形态。这也是测试test_tiny_local_profile_prompt_is_action_first_json_contract中断言headline not in code_prompt等三条的依据。4.4 三个典型工具的 Tiny Local 专属示例配置文件提供了三个工具的本地化示例均不带推理字段code_execution_toolagent.system.tool.code_exe.md运行终端、Python 或 Node.js 命令。参数包括runtimeterminal/python/nodejs/output、code、session默认0、resettrue/false。其规则强调用runtimeoutput轮询运行中的任务会话卡死时以相同sessionresettrue重调统计文件数优先find而非ls以处理隐藏文件与类型过滤。{tool_name:code_execution_tool,tool_args:{runtime:terminal,session:0,reset:false,code:ls -1 /tmp | wc -l}}responseagent.system.tool.response.md仅用于任务完成、受阻或无需工具时。明确禁止在存在未完成下一步的情况下用它回应proceed/continue类请求。{tool_name:response,tool_args:{text:There are 24 files in /tmp.}}text_editoragent.system.tool.text_editor.md读写或修补 Markdown 与纯文本文件。action支持read/write/patchopen_in_canvas仅在用户明确要求打开 Canvas/Editor 时置true写入或修补成功后不要重复同一调用。示例使用了/a0/usr/workdir/TODO.md这一典型 workdir 路径{tool_name:text_editor,tool_args:{action:write,path:/a0/usr/workdir/TODO.md,content:# TODO\n- [ ] First item\n,open_in_canvas:true}}五、验证方式渲染与回归测试AGENTS.md 的 Verification 一节给出了两条可执行的验证路径渲染系统提示词在修改通信提示词之后重新渲染tiny-local的完整系统提示词人工核对最终文本形态运行回归测试执行pytest tests/test_default_prompt_budget.py。该测试文件是 Tiny Local 行为契约的机器可读版本核心断言包括test_tiny_local_profile_prompt_is_action_first_json_contract逐条断言通信契约中的关键语句如 You are Agent Zero. Act on the users behalf.、Use exactly these top-level fields:tool_nameandtool_args.、求解契约中的续接词规则、重复消息恢复指令以及所有工具示例中不含headlinetest_tiny_local_profile_is_discoverable断言 Profile 可通过get_all_agents_list()发现且 label 为 Tiny Localtest_rendered_profiles_strip_json_fences以tiny-local等 5 个 Profile 为参数断言渲染后的系统提示词中不含~~~json与json围栏渲染阶段会通过files.remove_code_fences移除 JSON 围栏见 helpers/files.pytest_default_agent0_prompt_budget_and_guardrails验证默认 Profile 提示词预算约 10000 token 以内间接保障各 Profile 提示词膨胀可控。测试还通过_build_system_text(profile, renderedTrue)走AgentContextprepare_prompt的完整渲染管线见 tests/test_default_prompt_budget.py意味着这些断言验证的是模板经过{{include}}展开、{{tools}}注入后的真实系统提示词而非原始模板文本。六、维护与扩展指南AGENTS.md 的 Work Guidance 明确了后续维护该 Profile 时应遵循的两条原则提示词优先少建文件收紧行为时优先调整现有提示词的措辞而不是新建文件唯一例外是替换继承的工具示例以适配本地模型例如为某个工具提供 Tiny Local 专属的无推理示例版本保持通用性配置必须持续适用于 Ollama、LM Studio、Qwen 及其他同类本地模型不要引入特定提供商的专有行为。结合 Ownership 一节还可以看出每个提示词文件的所有者是明确的通信契约归agent.system.main.communication.md求解契约归agent.system.main.solving.md重复消息恢复归fw.msg_repeat.md工具包装与输出形态归agent.system.tools.md与agent.system.tool.*.md。修改某一类行为时应当只在对应文件内改动保持所有权边界清晰。七、总结Tiny Local 是 Agent Zero 面向小型本地模型场景的一套最小可行行动契约它以tool_nametool_args的单一 JSON 形态统一了工具调用协议通过续接词即执行指令消灭了状态式空回复通过显式压制继承推理字段解决了小模型提示词预算与格式漂移问题并通过纯提示词、零运行时修补的隔离原则保证了框架核心的稳定性。其所有权划分、本地契约、验证测试构成了一个完整、可回归、可移植的 Agent Profile 工程范本——如果你正在用 Ollama 或 LM Studio 驱动 Agent Zero并遇到模型总在解释而不动手的问题Tiny Local 就是开箱即用的答案。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考