AI Agent Hierarchy & Delegation: Build Self-Managing Teams

Q: Can I undo a prompt change made by a manager agent?

Yes. Every prompt modification is saved in `prompt_history` with the previous prompt, the new prompt, who changed it, the reason, and the timestamp. You can manually restore any previous version from the agent's configuration.

AI Agent Hierarchy & Delegation: Build Self-Managing Agent Teams

TL;DR: Fleece AI lets you organize agents into hierarchical teams where manager agents delegate tasks to sub-agents, receive structured reports, and auto-improve their team's prompts over time. The system includes delegation depth limits, audit logging, cycle detection, and rate-limited prompt modifications -- built for production safety at scale.

Why Agent Hierarchy Matters

A single AI agent can handle focused tasks well. But real business workflows span multiple domains -- email, data analysis, CRM updates, reporting, calendar management. Asking one agent to do everything leads to bloated prompts, conflicting instructions, and inconsistent results.

Agent hierarchy solves this by mirroring how human teams work:

Specialist agents focus on what they do best (email, data, scheduling)
Manager agents route tasks to the right specialist, synthesize results, and handle escalation
The orchestrator coordinates the entire team from a single chat interface

This architecture scales naturally. Add a new specialist when you need a new capability. Promote an agent to manager when a domain grows complex enough to warrant sub-teams.

The 3-Layer Architecture

Fleece AI's inter-agent communication system has three layers that work together:

Layer 1: Hierarchy Tools (Agent-Level)

Every agent in the hierarchy gets access to four built-in tools:

Tool	Direction	What It Does
delegate_to_sub_agent	Manager to Sub-Agent	Delegates a task to a direct report. The sub-agent executes independently and returns its result. Verified via parentAgentId -- only direct children can be delegated to.
report_to_parent	Sub-Agent to Manager	Sends a structured report (success, partial, failed, needs_attention) to the parent agent. Includes status, content, and metadata.
list_sub_agents	Manager reads team	Lists all direct reports with their type, skills, status, and capabilities. Used to make informed delegation decisions.
update_sub_agent_prompt	Manager modifies Sub-Agent	Auto-modifies a sub-agent's system prompt to improve performance. Rate-limited to 5 updates per day, minimum 20 characters, full history saved for rollback.

These tools are injected automatically based on the agent's position in the hierarchy. A manager agent with three sub-agents sees all four tools. A leaf agent (no children) sees only report_to_parent.

Layer 2: Delegation Tools (Team Chat)

The Team Chat orchestrator adds cross-team coordination tools:

Tool	What It Does
delegate_to_agent	Routes tasks to any agent by ID -- not limited to direct children. Used for cross-team delegation.
broadcast_to_agents	Sends a message to all active agents simultaneously. Used for team-wide instructions ("use formal tone", "prioritize X").
update_agent_prompt	Orchestrator can modify any agent's prompt (5/day rate limit). All changes logged and user notified.
schedule_agent_task	Schedules recurring tasks for agents via natural language (e.g., "every morning at 9am, check support emails").

Layer 3: Agent Messages (Audit Log)

Every delegation, report, prompt update, and broadcast is logged in the agent_messages table:

sender_agent_id and receiver_agent_id for full traceability
type: delegation, report, prompt_update, or broadcast
content: the actual message or task
metadata: JSON with context (duration, status, source, reason)

This gives you a complete audit trail of inter-agent communication. Query it via GET /api/agents/messages to see exactly what happened, when, and between which agents.

Setting Up a Hierarchy

Step 1: Create Specialist Agents

Start with agents focused on specific domains:

Email Agent -- skills: Email Assistant, Email Composer
Data Agent -- skills: Data Analyst, CSV Processor, Report Builder
Calendar Agent -- skills: Calendar Assistant, Meeting Scheduler
Comms Agent -- skills: Slack Integration, Notification Manager

Step 2: Create a Manager Agent

Create an agent with the Team Coordinator and Prompt Engineering skills. These skills give the manager structured methodology for delegation, performance monitoring, and prompt optimization.

Step 3: Build the Hierarchy (Drag & Drop)

Open the Hierarchy view in the Agents dashboard. Drag specialist agents onto the manager agent to establish parent-child relationships. The UI handles:

BFS cycle detection -- prevents circular hierarchies (A manages B manages A)
Auto-role assignment -- agents dropped into the hierarchy automatically get their role set
Collapse/expand sub-trees -- child count badges show team size at a glance
Remove from hierarchy -- resets parentAgentId and role, making the agent independent again

Step 4: Use Team Chat

Open Team Chat to interact with the entire team through the orchestrator. The orchestrator sees all agents, their skills, and the hierarchy structure. It routes tasks intelligently:

@mention a specific agent: @Email Agent draft a follow-up to Sarah
General request: summarize yesterday's support emails and post to Slack -- orchestrator picks the right agent(s)
Multi-agent task: pull Q1 data, analyze trends, and email the report to the team -- orchestrator delegates to Data Agent, then Email Agent sequentially

How Delegation Works Under the Hood

When a manager agent delegates a task:

Verification: The system confirms the target is a direct sub-agent of the delegating manager (checked via parentAgentId and userId)
Depth check: Delegation depth is tracked and capped at 3 levels (A delegates to B delegates to C delegates to D -- stops here) to prevent recursive cost explosion
Logging: A delegation message is written to agent_messages with full metadata
Execution: The sub-agent runs the task independently using its own skills, knowledge, and connected tools
Report back: The result is logged as a report message from sub-agent to manager, with status, duration, and content

The manager receives the result inline and can synthesize it with other sub-agent outputs before responding to the user.

Self-Improving Prompts

One of the most powerful features of the hierarchy is automatic prompt optimization. When a manager agent detects that a sub-agent is underperforming, it can modify that agent's system prompt using update_sub_agent_prompt.

How It Works

Manager identifies a pattern: sub-agent gives incomplete answers, wrong tone, or misses key requirements
Manager uses the Prompt Engineering skill to diagnose the issue and craft an improved prompt
Manager calls update_sub_agent_prompt with the complete new prompt and a reason for the change
The system saves the previous prompt in prompt_history (up to 20 entries) for rollback
The user is notified of the change via the notification bus

Safety Guardrails

Rate limit: 5 prompt updates per day per manager agent
Minimum length: New prompts must be at least 20 characters
Ownership verification: Only direct sub-agents can have prompts modified (verified via parentAgentId)
History cap: Last 20 prompt versions are saved with timestamps, the modifying agent, and the reason
User notification: Every prompt change triggers a notification so the user always knows what happened

Orchestrator Prompt Updates

The Team Chat orchestrator can also update any agent's prompt (not just direct children). This is useful for team-wide improvements: if the orchestrator notices all agents are too verbose, it can update their prompts one by one. Rate-limited to 5 updates per day per user.

Data Connections: Cross-Hierarchy Communication

Not all agent communication follows the parent-child hierarchy. Data connections let agents share outputs with any other agent, regardless of hierarchy position.

Configure data connections in the Hierarchy view by drawing connection lines between agents. When an agent with data connections completes a task, it can use send_data_to_connections to push results to all connected agents.

Use cases:

A Data Agent feeds processed reports to both its manager and an independent Email Agent
A Monitoring Agent pushes alerts to a Slack Agent and a PagerDuty Agent simultaneously
A Research Agent shares findings with multiple department manager agents

Practical Team Configurations

The Operations Team

Operations Manager (Team Coordinator + Prompt Engineering)
  -- Email Agent (Email Assistant + Email Composer)
  -- Slack Agent (Slack Integration + Notification Manager)
  -- Calendar Agent (Calendar Assistant + Meeting Scheduler)
  -- Reporting Agent (Data Analyst + Report Builder)

The Operations Manager receives requests like "prepare for tomorrow's board meeting" and delegates: Calendar Agent checks the schedule, Email Agent drafts reminder emails, Reporting Agent pulls the latest metrics, Slack Agent posts the prep checklist.

The Data Pipeline Team

Data Lead (Team Coordinator + SQL Expert)
  -- Ingestion Agent (CSV Processor + Firecrawl Skills)
  -- Analysis Agent (Data Analyst + Chart Generator)
  -- Report Agent (Report Builder + Email Composer)

Data flows downward: Ingestion Agent collects and cleans data, passes it to Analysis Agent via data connection, who produces visualizations, which Report Agent formats and distributes.

The DevOps Team

DevOps Manager (Team Coordinator + Prompt Engineering)
  -- CI/CD Agent (Git Essentials + Docker Essentials)
  -- Deploy Agent (Vercel + Coding Agent)
  -- Monitor Agent (Browser Use + Notification Manager)

Monitor Agent detects issues, reports to DevOps Manager, who delegates investigation to CI/CD Agent and remediation to Deploy Agent.

Hierarchy + Heartbeat: Autonomous Teams

Combine hierarchy with agent heartbeats for fully autonomous teams. Schedule manager agents to wake up on intervals and proactively check on their team:

Every hour: Manager calls list_sub_agents to check team status
Every morning at 9 AM: Manager delegates daily reporting tasks to sub-agents
Every Friday at 5 PM: Manager synthesizes weekly reports from all sub-agents

Plan limits for scheduled agents: Free = 0, Pro = 5, Business = 25.

Security & Safety

The hierarchy system is hardened for production use:

Protection	Implementation
Delegation depth limit	MAX_DELEGATION_DEPTH = 3 prevents recursive cost explosion
Cross-user isolation	`getSubAgents()` always filters by userId -- no cross-user data leakage
Ownership verification	PATCH `/api/agents/[agentId]` validates parentAgentId belongs to the same user
Cycle detection	BFS `isDescendantOf()` in the hierarchy UI prevents circular chains
Prompt update rate limit	5/day per manager + 5/day per orchestrator user
Prompt history	20 entries saved with timestamps, author, and reason for rollback
User notifications	Every prompt change triggers notification via event bus
Message audit log	All inter-agent communication logged with sender, receiver, type, and metadata

Frequently Asked Questions

How deep can the hierarchy go?

There is no limit on hierarchy depth for the organizational structure. However, delegation depth (one agent delegating to a sub-agent who delegates to another sub-agent) is capped at 3 levels to prevent runaway cost. A manager can delegate to a sub-manager who delegates to a specialist -- but the specialist cannot delegate further in that chain.

Can agents in different hierarchies talk to each other?

Not directly through hierarchy tools. However, data connections allow cross-hierarchy communication, and the Team Chat orchestrator can coordinate between any agents regardless of hierarchy position.

What happens if a sub-agent fails?

The failure is logged as a report message with status "failed" and the error details. The manager agent receives this result and can retry, delegate to a different sub-agent, or escalate to the user. The orchestrator prompt includes instructions to notify manager agents when their sub-agents fail.

Can I undo a prompt change made by a manager agent?

Yes. Every prompt modification is saved in prompt_history with the previous prompt, the new prompt, who changed it, the reason, and the timestamp. You can manually restore any previous version from the agent's configuration.

Does hierarchy work with all AI models?

Yes. Hierarchy tools and inter-agent communication work identically across all models available on Fleece AI -- Gemini 3.1 Flash Lite (free), GPT-5.2 (Pro), GPT-5.4 and Claude Opus 4.6 (Business). Each agent can even use a different model.

AI Agent Skills Guide -- 34 built-in skills + Skill Creator
What Is Fleece AI? -- platform overview
AI Workflow Automation Guide -- scheduled flows
Best Autonomous AI Agents 2026 -- agent landscape
What Is Delegative AI? -- the paradigm behind Fleece AI

Try Fleece AI free -- build your first agent team in under 60 seconds.