Skip to main content
Sub-agents are agents that a master agent can invoke as tools. This enables hierarchical delegation — a master orchestrator routes tasks to specialists.

​
Defining a Sub-Agent

from framework.agents import SubAgent
from framework.decorators import sub_agent

@sub_agent(
    name="EmailsAgent",
    description="Handles email composition, replies, and management",
    master_agents=["MainAgent"],
    system_prompt=EMAILS_PROMPT,
    llm_config={"model": "openai/gpt-4o", "temperature": 0.7},
)
class EmailsAgent(SubAgent):
    pass
The master_agents parameter controls which agents can delegate to this sub-agent.

​
How Delegation Works

  1. The master agent’s LLM decides to delegate and “calls” the sub-agent (it appears as a tool)
  2. A new ExecutionContext is created with a child call_id
  3. The sub-agent runs its own execution loop with its own tools and prompt
  4. The sub-agent’s response is returned to the master agent
  5. The master agent incorporates the result and continues

​
Streaming During Delegation

When verbose=True, the client sees events from both the master and sub-agent: 
Event(START, agent="MainAgent")
  Event(DELTA, agent="MainAgent", delta="Let me check your emails...")
  Event(START, agent="EmailsAgent")
    Event(DELTA, agent="EmailsAgent", delta="Found 3 unread emails...")
  Event(END, agent="EmailsAgent")
  Event(DELTA, agent="MainAgent", delta="You have 3 unread emails...")
Event(END, agent="MainAgent")

​
Registering via API

Sub-agents can also be registered dynamically: 
POST /agents/{master_agent_id}/sub-agents
{
  "sub_agent_id": "EmailsAgent"
}