# How the behavior_adjustment Tool Modifies Agent Behaviour in Agent Zero

> Discover how the behavior_adjustment tool programmatically updates Agent Zero agent rules using LLM merging for instructions and adjustments, persisting changes to behaviour.md.

- Repository: [Agent Zero/agent-zero](https://github.com/agent0ai/agent-zero)
- Tags: deep-dive
- Published: 2026-02-23

---

**The `behavior_adjustment` tool programmatically updates an Agent’s markdown-based behaviour rules by merging user-supplied adjustments with existing instructions using an LLM, then persisting the result to [`behaviour.md`](https://github.com/agent0ai/agent-zero/blob/main/behaviour.md).**

The `behavior_adjustment` tool in the **agent0ai/agent-zero** repository enables dynamic, runtime modification of how an Agent responds to tasks. By treating behaviour rules as version-controlled markdown documents, the tool allows both users and automated processes to refine agent capabilities without restarting the system.

## How the Tool Works

The tool is implemented as the `UpdateBehaviour` class in [`python/tools/behaviour_adjustment.py`](https://github.com/agent0ai/agent-zero/blob/main/python/tools/behaviour_adjustment.py). It orchestrates a five-stage pipeline that ensures behavioural changes remain consistent, deduplicated, and properly formatted.

### Entry Point and Execution

When invoked, the asynchronous `execute` method receives an **adjustments** string containing the desired rule changes. The method normalizes this input and delegates the heavy lifting to the internal `update_behaviour` helper function. According to the source code in [`python/tools/behaviour_adjustment.py`](https://github.com/agent0ai/agent-zero/blob/main/python/tools/behaviour_adjustment.py), this separation keeps the public API clean while allowing complex file operations to run asynchronously.

### Gathering Current Behaviour State

Before merging new instructions, the tool must establish a baseline. The `update_behaviour` function first loads the system prompt that defines the merging task from [`prompts/behaviour.merge.sys.md`](https://github.com/agent0ai/agent-zero/blob/main/prompts/behaviour.merge.sys.md). It then attempts to read the Agent’s custom rules from [`behaviour.md`](https://github.com/agent0ai/agent-zero/blob/main/behaviour.md) in the working directory. 

If no custom file exists, the tool gracefully falls back to the default behaviour template stored in [`prompts/agent.system.behaviour_default.md`](https://github.com/agent0ai/agent-zero/blob/main/prompts/agent.system.behaviour_default.md), wrapping it with the generic formatter from [`prompts/agent.system.behaviour.md`](https://github.com/agent0ai/agent-zero/blob/main/prompts/agent.system.behaviour.md). This ensures the merge process always operates on a complete, well-formed rule set.

### LLM-Powered Rule Merging

With current rules loaded, the tool constructs a merge prompt using the template in [`prompts/behaviour.merge.msg.md`](https://github.com/agent0ai/agent-zero/blob/main/prompts/behaviour.merge.msg.md). This message includes:
- The existing markdown ruleset
- The new adjustments provided by the user
- Instructions to deduplicate and condense content

The populated prompt is sent to the Agent’s utility LLM via `agent.call_utility_model`. The LLM returns a **merged markdown ruleset** that incorporates the new constraints while maintaining coherent structure and removing redundancies, exactly as specified by the system prompt.

### Persisting Updates

Once the LLM generates the revised rules, the tool writes the content back to [`behaviour.md`](https://github.com/agent0ai/agent-zero/blob/main/behaviour.md) using `files.write_file`. This overwrites the previous configuration atomically, ensuring the Agent immediately begins operating under the new constraints. The execution log is updated to reflect the successful modification, and the `execute` method returns a `Response` object containing the [`behaviour.updated.md`](https://github.com/agent0ai/agent-zero/blob/main/behaviour.updated.md) confirmation prompt, signalling to the orchestration layer that the adjustment succeeded without interrupting the message loop.

## Code Examples

### JSON Tool Invocation

When the Agent’s planning layer selects the behaviour adjustment tool, it structures the call as follows:

```json
{
    "thoughts": [
        "User wants the agent to stop answering questions about politics."
    ],
    "headline": "Adjusting agent behavior per user request",
    "tool_name": "behaviour_adjustment",
    "tool_args": {
        "adjustments": "remove any political content from responses"
    }
}

```

### Python Direct Usage

For internal automation or testing, instantiate the tool directly in Python:

```python
from python.tools.behaviour_adjustment import UpdateBehaviour

tool = UpdateBehaviour(agent=my_agent, log=my_log)
await tool.execute(adjustments="remove any political content from responses")

```

### Resulting Behaviour File

After execution, the [`behaviour.md`](https://github.com/agent0ai/agent-zero/blob/main/behaviour.md) file reflects the merged constraints:

```markdown

## Allowed Topics

* General knowledge
* Technical assistance

## Disallowed Topics

* Politics

```

## Key Files and Templates

The `behavior_adjustment` tool relies on a specific prompt architecture located in the `prompts/` directory:

- **[`python/tools/behaviour_adjustment.py`](https://github.com/agent0ai/agent-zero/blob/main/python/tools/behaviour_adjustment.py)** – Core implementation containing the `UpdateBehaviour` class and `update_behaviour` helper
- **[`prompts/behaviour.merge.sys.md`](https://github.com/agent0ai/agent-zero/blob/main/prompts/behaviour.merge.sys.md)** – System prompt defining the merge task and deduplication requirements
- **[`prompts/behaviour.merge.msg.md`](https://github.com/agent0ai/agent-zero/blob/main/prompts/behaviour.merge.msg.md)** – User message template for requesting the LLM merge operation
- **[`prompts/agent.system.tool.behaviour.md`](https://github.com/agent0ai/agent-zero/blob/main/prompts/agent.system.tool.behaviour.md)** – Tool description used by the Agent’s planner to recognize when behaviour adjustment is appropriate
- **[`prompts/agent.system.behaviour_default.md`](https://github.com/agent0ai/agent-zero/blob/main/prompts/agent.system.behaviour_default.md)** – Fallback ruleset used when no custom [`behaviour.md`](https://github.com/agent0ai/agent-zero/blob/main/behaviour.md) exists
- **[`prompts/agent.system.behaviour.md`](https://github.com/agent0ai/agent-zero/blob/main/prompts/agent.system.behaviour.md)** – Generic wrapper template applied to finalize formatting

## Summary

- The **`behavior_adjustment` tool** (class `UpdateBehaviour`) enables runtime modification of Agent behaviour rules stored in markdown format.
- It **merges user adjustments** with existing rules by prompting a utility LLM, ensuring content remains deduplicated and concise.
- The tool **reads from** [`behaviour.md`](https://github.com/agent0ai/agent-zero/blob/main/behaviour.md) (or defaults) and **writes back** to the same file via `files.write_file`.
- Execution follows a structured pipeline: **state gathering → LLM merging → atomic persistence → confirmation response**.
- All merge logic is governed by specialized system prompts in the `prompts/` directory, making the process transparent and version-controllable.

## Frequently Asked Questions

### What does the behavior_adjustment tool do in Agent Zero?

The tool modifies the markdown-based behaviour rules that constrain how an Agent responds to tasks. It accepts plain-text adjustment instructions, merges them with the current rule set using an LLM to ensure coherence, and writes the updated configuration to [`behaviour.md`](https://github.com/agent0ai/agent-zero/blob/main/behaviour.md) so the Agent immediately follows the new guidelines.

### How does the tool prevent duplicate or conflicting rules?

During the merge phase, the tool sends both the existing rules and new adjustments to a utility LLM with a system prompt ([`behaviour.merge.sys.md`](https://github.com/agent0ai/agent-zero/blob/main/behaviour.merge.sys.md)) that explicitly instructs the model to deduplicate content and resolve conflicts. This automated reasoning step ensures the final [`behaviour.md`](https://github.com/agent0ai/agent-zero/blob/main/behaviour.md) remains internally consistent and concise.

### What happens if no custom behaviour.md file exists?

If the Agent has not yet created a custom rule file, the tool automatically falls back to loading [`prompts/agent.system.behaviour_default.md`](https://github.com/agent0ai/agent-zero/blob/main/prompts/agent.system.behaviour_default.md), wraps it with the generic formatter from [`prompts/agent.system.behaviour.md`](https://github.com/agent0ai/agent-zero/blob/main/prompts/agent.system.behaviour.md), and uses that as the baseline for merging. This guarantees the adjustment process always succeeds, even for newly initialized Agents.

### Can developers invoke the behavior_adjustment tool programmatically?

Yes. Developers can import the `UpdateBehaviour` class directly from [`python/tools/behaviour_adjustment.py`](https://github.com/agent0ai/agent-zero/blob/main/python/tools/behaviour_adjustment.py), instantiate it with an Agent and log object, and call `await tool.execute(adjustments="...")`. This is useful for automated testing, scripted behaviour updates, or integrating dynamic rule changes into custom orchestration workflows.