| 1 | # Local Model Tool Use |
| 2 | |
| 3 | Small local models can struggle with Agent Zero's full default communication shape. The safest first fix is prompt/profile/plugin-only: use a smaller behavior contract while leaving Agent Zero's core parser and execution code unchanged. |
| 4 | |
| 5 | Use this guide for Ollama, LM Studio, Qwen, and similar local chat models when the model explains commands instead of calling tools. |
| 6 | |
| 7 | ## Use The Tiny Local Profile |
| 8 | |
| 9 | Choose the **Tiny Local** profile when starting or switching a chat that uses a small local model. |
| 10 | |
| 11 | The bundled profile lives at: |
| 12 | |
| 13 | ```text |
| 14 | agents/tiny-local/ |
| 15 | ``` |
| 16 | |
| 17 | Tiny Local keeps the normal Agent Zero tool-call shape, but removes visible reasoning fields from the communication prompt. It tells the model to emit one executable JSON object with `tool_name` and `tool_args`. |
| 18 | |
| 19 | ## Use A Project Prompt Include |
| 20 | |
| 21 | If you want to keep your current profile, create a project-local file that matches the Prompt Include plugin pattern (`*.promptinclude.md`): |
| 22 | |
| 23 | ```text |
| 24 | local-model-tool-use.promptinclude.md |
| 25 | ``` |
| 26 | |
| 27 | Put this content in that file: |
| 28 | |
| 29 | ```markdown |
| 30 | ## Local model tool-use discipline |
| 31 | |
| 32 | You are Agent Zero. Act on the user's behalf. |
| 33 | |
| 34 | When the user asks you to do something, do it directly. Do not explain how the user could do it themselves. |
| 35 | |
| 36 | Your visible assistant message must be exactly one valid JSON object. |
| 37 | |
| 38 | Use exactly these top-level fields: `tool_name` and `tool_args`. |
| 39 | |
| 40 | Do not include markdown fences, prose before the JSON, prose after the JSON, hidden reasoning, analysis, thoughts, or headlines. |
| 41 | |
| 42 | Choose a tool from the tools listed in the system prompt. Do not invent tool names, action names, or generic names such as `read`, `write`, `terminal`, or `multi`. |
| 43 | |
| 44 | For a final user-facing answer, use the `response` tool: |
| 45 | |
| 46 | `{"tool_name":"response","tool_args":{"text":"Done."}}` |
| 47 | |
| 48 | Use `response` only when the work is complete, blocked, or no tool is needed. If the user says "proceed", "continue", "go ahead", or similar after the agent named a next step, call the next appropriate tool instead of replying with a promise or status update. |
| 49 | |
| 50 | For work that requires a command, file action, browser action, or any other available tool, call the appropriate tool immediately. |
| 51 | |
| 52 | 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. |
| 53 | ``` |
| 54 | |
| 55 | ## Keep This Prompt-Only |
| 56 | |
| 57 | Do not change `agent.py` for this workflow. |
| 58 | |
| 59 | Do not change `helpers/extract_tools.py` for this workflow. |
| 60 | |
| 61 | Do not create parser repair code for this workflow. |
| 62 | |
| 63 | Do not add duplicate execution suppression, LiteLLM transport changes, memory runtime changes, or text-editor file operation changes for this workflow. |
| 64 | |
| 65 | If a specific local model still cannot follow the prompt/profile/plugin-only contract, capture the exact model, prompt, response, and tool warning before considering deeper framework changes. |