🌳 AgenTree

Appearance

Return to top
On this page

Agent Hierarchy

Core Concept

Unlike traditional AI frameworks where you predefine agent roles, AgenTree agents create their own specialized children on-demand based on task analysis.

How Hierarchy Works

1. Task Analysis

The parent agent analyzes its task and determines what subtasks are needed.

2. Child Creation

For each subtask, the agent creates a specialized child with:

  • Custom role and specific task
  • Relevant tools for the subtask
  • Context passed from parent
  • Own ability to create children

3. Execution Tree

Children execute independently and can create their own children, forming a tree structure.

Example Hierarchy

typescript
const agent = new Agent({
  name: "product-launcher",
  task: "Launch a new product: research market, create strategy, and prepare materials",
  tools: [webSearchTool, writeFileTool],
  maxDepth: 4
});

This creates the following hierarchy:

🎯 Product Launcher (depth 0)
├── 📊 Market Research Agent (depth 1)
│   ├── 🔍 Competitor Analysis Agent (depth 2)
│   ├── 📈 Trend Analysis Agent (depth 2)
│   └── 💰 Pricing Research Agent (depth 2)
├── 📋 Strategy Planning Agent (depth 1)
│   ├── 🎨 Marketing Strategy Agent (depth 2)
│   ├── 📅 Timeline Planning Agent (depth 2)
│   └── 💼 Resource Planning Agent (depth 2)
└── 📝 Material Creation Agent (depth 1)
    ├── 📄 Documentation Agent (depth 2)
    ├── 🎨 Visual Assets Agent (depth 2)
    └── 📊 Presentation Agent (depth 2)

Child Agent Creation

Parent Perspective

The parent uses the createAgent tool (automatically available):

typescript
// This happens inside the LLM's reasoning
{
  "name": "createAgent",
  "arguments": {
    "name": "market-researcher",
    "task": "Research current market conditions for our product category",
    "context": ["./product-specs.md", "Focus on competitors and pricing"],
    "tools": ["web_search", "readFile"]
  }
}

Child Perspective

The child agent is created with:

typescript
// Automatically generated by parent
const childAgent = new Agent({
  name: "market-researcher",
  task: "Research current market conditions for our product category",
  context: ["./product-specs.md", "Focus on competitors and pricing"],
  tools: ["web_search", "readFile"], // Tool names resolved from registry
  parentId: "parent-agent-id",
  depth: 1,
  maxDepth: 4,
  config: inheritedConfig
});

Depth Control

Maximum Depth

Set maximum hierarchy depth to prevent infinite recursion:

typescript
const agent = new Agent({
  name: "complex-task",
  task: "Very complex multi-step task",
  maxDepth: 3, // Agents can create children up to depth 2
  config: { /* ... */ }
});

Depth Behavior

  • Depth 0: Root agent (your main agent)
  • Depth 1: Children of root agent
  • Depth 2: Grandchildren
  • Max Depth: Agents at max depth cannot create children

Tool Inheritance

Tool Registry

Tools are registered globally for child access:

typescript
import { ToolRegistry } from 'agentree';

// Custom tools get auto-registered when passed to agents
const myTool = tool({ /* ... */ });

const agent = new Agent({
  tools: [myTool], // Automatically registered
  // ...
});

// Children can access by name
// Parent creates child with: tools: ["myTool"]

Default Tools

All agents have access to:

  • createAgent: Create child agents
  • stopAgent: Return results
  • Built-in tools: readFile, writeFile, etc.

Communication Pattern

Top-Down (Parent → Child)

  • Task assignment: Specific subtask description
  • Context sharing: Relevant files, URLs, data
  • Tool provision: Specific tools for the subtask
  • Configuration: Inherited LLM settings

Bottom-Up (Child → Parent)

  • Result return: Child execution results
  • Status updates: Success/failure information
  • Error propagation: Errors bubble up to parent

Monitoring Hierarchy

Track Child Creation

typescript
agent.on('childCreated', (data) => {
  console.log(`👶 ${data.parentName} created ${data.childName}`);
  console.log(`   Task: ${data.childTask}`);
});

Hierarchical Logging

typescript
agent.on('agentCompleted', (data) => {
  const indent = '  '.repeat(data.depth);
  console.log(`${indent}✅ ${data.name} (${data.executionTime}ms)`);
});

Best Practices

1. Appropriate Depth

  • Simple tasks: maxDepth 1-2
  • Complex workflows: maxDepth 3-4
  • Very complex projects: maxDepth 5+ (with caution)

2. Tool Design

  • Specialized tools: Better than generic ones
  • Context-aware: Tools that understand their domain
  • Error handling: Robust tool implementations

3. Task Decomposition

  • Clear boundaries: Each subtask should be well-defined
  • Minimal dependencies: Reduce inter-child communication
  • Logical grouping: Related subtasks under same parent

Output Structure

The hierarchy is reflected in the output folder structure:

.agentree/
└── product-launcher-2025-07-02/
    ├── agent-report.md
    ├── market-research-agent/
    │   ├── agent-report.md
    │   ├── competitor-analysis/
    │   │   └── agent-report.md
    │   └── trend-analysis/
    │       └── agent-report.md
    └── strategy-planning-agent/
        ├── agent-report.md
        └── marketing-strategy/
            └── agent-report.md

Next Steps