How the behavior_adjustment Tool Modifies Agent Behaviour in Agent Zero

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.

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. 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, 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. It then attempts to read the Agent’s custom rules from 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, wrapping it with the generic formatter from 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. 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 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 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:

{
    "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:

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 file reflects the merged constraints:

## 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 – Core implementation containing the UpdateBehaviour class and update_behaviour helper
• prompts/behaviour.merge.sys.md – System prompt defining the merge task and deduplication requirements
• prompts/behaviour.merge.msg.md – User message template for requesting the LLM merge operation
• 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 – Fallback ruleset used when no custom behaviour.md exists
• 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 (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 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) that explicitly instructs the model to deduplicate content and resolve conflicts. This automated reasoning step ensures the final 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, wraps it with the generic formatter from 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}