# How to Call a Subordinate Agent with the `call_subordinate` Tool in Agent Zero

> Learn to call subordinate agents with Agent Zero's call_subordinate tool. This guide explains how to create child agents, forward messages, and manage responses effectively.

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

---

**The `call_subordinate` tool creates a child agent, forwards a message, executes its monologue, and returns the response while maintaining parent-child hierarchy.**

The `call_subordinate` tool in the [agent0ai/agent-zero](https://github.com/agent0ai/agent-zero) repository enables hierarchical multi-agent workflows by allowing a parent agent to delegate tasks to a subordinate. This implementation leverages a dedicated `Delegation` class that handles agent instantiation, message forwarding, and result propagation across the agent hierarchy.

## Understanding the `call_subordinate` Tool Architecture

The delegation system is distributed across three core components that manage the lifecycle of a subordinate agent.

### Core Components

| Component | Role | Source File |
|-----------|------|-------------|
| **`Delegation` tool** | Concrete implementation of `call_subordinate` that creates or recreates subordinate agents, forwards messages, executes monologues, and returns results. | [`python/tools/call_subordinate.py`](https://github.com/agent0ai/agent-zero/blob/main/python/tools/call_subordinate.py) |
| **`Agent` class** | Central execution engine storing hierarchical relationships (`_superior` / `_subordinate`), providing `hist_add_user_message`, `monologue`, and `_process_chain` for result propagation. | [`agent.py`](https://github.com/agent0ai/agent-zero/blob/main/agent.py) |
| **`Tool` base class** | Abstract base defining the `execute` contract, progress handling, and logging infrastructure. | [`python/helpers/tool.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/tool.py) |

### Hierarchical Data Storage

Each `Agent` instance maintains parent-child relationships through its `data` dictionary using reserved keys:

- **`Agent.DATA_NAME_SUPERIOR`** (`"_superior"`): References the parent agent
- **`Agent.DATA_NAME_SUBORDINATE`** (`"_subordinate"`): References the child agent

These constants are defined in [`agent.py`](https://github.com/agent0ai/agent-zero/blob/main/agent.py) and enable the framework to traverse the agent hierarchy during result propagation.

## How `call_subordinate` Works Step by Step

The `Delegation.execute` method in [`python/tools/call_subordinate.py`](https://github.com/agent0ai/agent-zero/blob/main/python/tools/call_subordinate.py) follows a strict sequence to delegate tasks and retrieve results.

### Step 1: Creating or Resetting the Subordinate Agent

The tool first checks for an existing subordinate or respects a reset request:

```python
if (
    self.agent.get_data(Agent.DATA_NAME_SUBORDINATE) is None
    or str(reset).lower().strip() == "true"
):
    config = initialize_agent()  # Default configuration from initialize.py

    # Optional profile override

    agent_profile = kwargs.get("profile", kwargs.get("agent_profile", ""))
    if agent_profile:
        config.profile = agent_profile
    
    # Instantiate child agent with sequential numbering

    sub = Agent(self.agent.number + 1, config, self.agent.context)
    
    # Establish bidirectional hierarchy

    sub.set_data(Agent.DATA_NAME_SUPERIOR, self.agent)
    self.agent.set_data(Agent.DATA_NAME_SUBORDINATE, sub)

```

The child agent receives the same `AgentContext` as its parent to ensure shared logging, memory, and services remain coherent across the hierarchy.

### Step 2: Sending Messages to the Child Agent

Once the subordinate exists, the tool forwards the user message:

```python
subordinate: Agent = self.agent.get_data(Agent.DATA_NAME_SUBORDINATE)
subordinate.hist_add_user_message(
    UserMessage(message=message, attachments=[])
)

```

The `UserMessage` class (defined in [`agent.py`](https://github.com/agent0ai/agent-zero/blob/main/agent.py)) encapsulates the message content and any attachments, storing the turn in the child's conversation history.

### Step 3: Executing the Subordinate Monologue

The tool triggers the child's autonomous reasoning loop:

```python
result = await subordinate.monologue()

```

The `Agent.monologue()` method executes the full message loop, allowing the subordinate to utilize its own tools, reasoning steps, and external integrations independently of the parent.

### Step 4: Sealing the Topic and Returning Results

After the monologue completes, the child's current topic is sealed to enable memory management:

```python
subordinate.history.new_topic()

```

The tool then constructs the response, adding hints for large outputs:

```python
additional = None
if len(result) >= save_tool_call_file.LEN_MIN:
    hint = self.agent.read_prompt("fw.hint.call_sub.md")
    if hint:
        additional = {"hint": hint}
return Response(message=result, break_loop=False, additional=additional)

```

The `Response` object signals success to the framework, with `break_loop=False` indicating the parent agent should continue its own processing.

### Step 5: Propagating Results Up the Hierarchy

The `Agent._process_chain` method handles recursive result propagation:

```python
msg_template = (
    agent.hist_add_user_message(msg) if user
    else agent.hist_add_tool_result(
        tool_name="call_subordinate", tool_result=msg
    )
)
response = await agent.monologue()
superior = agent.data.get(Agent.DATA_NAME_SUPERIOR, None)
if superior:
    response = await self._process_chain(superior, response, False)

```

This recursive mechanism ensures that in multi-level hierarchies (A → B → C), the final response bubbles back to the original requester.

## Practical Code Examples for Calling Subordinates

### Direct Tool Invocation (Developer API)

To programmatically delegate tasks from a parent agent:

```python
from agent import Agent, initialize_agent
from python.tools.call_subordinate import Delegation

# Initialize the main agent

main_cfg = initialize_agent()
main_agent = Agent(0, main_cfg, None)

# Instantiate the delegation tool

tool = Delegation(
    agent=main_agent,
    name="call_subordinate",
    method=None,
    args={},
    message="",  # Will be set during execution

    loop_data=None,
)

# Execute delegation

response = await tool.execute(message="Summarize the latest news about AI.")
print("Subordinate replied:", response.message)

```

### Automatic Delegation in Chat Sessions

In conversational workflows, the LLM automatically invokes `call_subordinate` when task decomposition is required:

```text
User: "Please draft a short blog post about quantum computing."
LLM (internal thought): "I need a specialized agent to research the topic." 
→ Invokes call_subordinate tool
(Subordinate agent executes research and drafting monologue)
LLM (receives result): "Here is your draft: ..."

```

### Resetting a Subordinate Agent

To clear a subordinate's memory and start fresh, pass the reset parameter:

```python

# Force creation of a new subordinate instance

response = await tool.execute(
    message="Explain blockchain basics.", 
    reset="true"
)

```

## Key Source Files and Implementation Details

| File | Purpose | Key Elements |
|------|---------|--------------|
| [`python/tools/call_subordinate.py`](https://github.com/agent0ai/agent-zero/blob/main/python/tools/call_subordinate.py) | **Delegation tool implementation** | `Delegation` class, `execute()` method, subordinate lifecycle management |
| [`agent.py`](https://github.com/agent0ai/agent-zero/blob/main/agent.py) | **Core agent logic** | `Agent` class, `DATA_NAME_SUPERIOR`, `DATA_NAME_SUBORDINATE`, `monologue()`, `_process_chain()`, `hist_add_user_message()` |
| [`python/helpers/tool.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/tool.py) | **Tool infrastructure** | `Tool` base class, `Response` class, execution contract |
| [`initialize.py`](https://github.com/agent0ai/agent-zero/blob/main/initialize.py) | **Agent initialization** | `initialize_agent()` function, `AgentConfig` setup |
| [`python/extensions/hist_add_tool_result/_90_save_tool_call_file.py`](https://github.com/agent0ai/agent-zero/blob/main/python/extensions/hist_add_tool_result/_90_save_tool_call_file.py) | **Large response handling** | `LEN_MIN` constant, file saving logic for tool outputs |

## Summary

- The **`call_subordinate`** tool enables hierarchical multi-agent delegation through the `Delegation` class in [`python/tools/call_subordinate.py`](https://github.com/agent0ai/agent-zero/blob/main/python/tools/call_subordinate.py).
- Subordinate agents are stored using reserved keys **`_superior`** and **`_subordinate`** in the parent agent's `data` dictionary.
- The tool automatically handles agent instantiation, message forwarding via `hist_add_user_message`, and execution via `monologue()`.
- Results propagate upward through the recursive `_process_chain` method, supporting complex agent chains (A → B → C).
- Large responses trigger automatic hint generation based on the `LEN_MIN` threshold defined in the save tool call file extension.

## Frequently Asked Questions

### What is the difference between a superior and subordinate agent?

A **superior** agent is the parent that initiates delegation, while a **subordinate** is the child agent created to handle specific tasks. The superior stores a reference to the subordinate using the `_subordinate` key in its `data` dictionary, and the subordinate maintains a back-reference to its superior via the `_superior` key. This bidirectional linking enables result propagation and hierarchical chain management.

### How does `call_subordinate` handle long responses?

When a subordinate's response exceeds the `LEN_MIN` threshold defined in [`python/extensions/hist_add_tool_result/_90_save_tool_call_file.py`](https://github.com/agent0ai/agent-zero/blob/main/python/extensions/hist_add_tool_result/_90_save_tool_call_file.py), the tool automatically generates a hint by reading the [`fw.hint.call_sub.md`](https://github.com/agent0ai/agent-zero/blob/main/fw.hint.call_sub.md) prompt file. This hint is attached to the `Response` object as additional metadata, informing the parent agent that the output has been saved to a file and can be accessed there rather than displayed inline.

### Can I chain multiple subordinate calls?

Yes, the architecture supports deep hierarchical chains through the `_process_chain` method in [`agent.py`](https://github.com/agent0ai/agent-zero/blob/main/agent.py). When agent A calls agent B, which then calls agent C, the final result propagates back through each level via recursive calls to `_process_chain`. Each agent in the chain receives the result as a tool result message (via `hist_add_tool_result`) rather than a user message, maintaining proper conversation context throughout the hierarchy.

### How do I reset a subordinate's memory?

Pass the `reset="true"` parameter when invoking the tool to force creation of a new subordinate instance. This clears the existing `_subordinate` reference from the parent agent's data dictionary and instantiates a fresh `Agent` object with the same configuration but empty history. Use this when you need to clear context from previous delegations or start a new task with a clean slate.