​

Subagents

​

Why Use Sub-Agents?

• Modular Design: Build and test small, expert agents individually before integrating them.
• Improved Accuracy: Specialized agents (e.g., a “Math Expert” or “Code Auditor”) are less likely to hallucinate in their specific domain.
• Tool Management: Avoid cluttering a single agent’s prompt with hundreds of tools. Instead, give each sub-agent only the tools it needs.
• Parallel Work: Use one spawn_subagents call with multiple specs when independent tasks can run at the same time.
• Workspace Continuity: Dynamic subagents write output to workspace files, so outputs survive context compression and tool offloading.

​

Dynamic Subagents

from omnicoreagent import OmniCoreAgent

agent = OmniCoreAgent(
    name="task_manager",
    system_instruction="You coordinate complex work and synthesize outputs.",
    model_config={"provider": "openai", "model": "gpt-4o"},
    agent_config={
        "enable_subagents": True,
        "context_management": {"enabled": True},
        "tool_offload": {"enabled": True},
    },
)

​

spawn_subagents

[
  {
    "name": "api",
    "role": "API reviewer",
    "task": "Review API error handling and write concrete risks.",
    "output_path": "/workspace/product_audit/subagent_api/output.md"
  },
  {
    "name": "tests",
    "role": "Test reviewer",
    "task": "Review coverage gaps and write recommended test cases.",
    "output_path": "/workspace/product_audit/subagent_tests/output.md"
  }
]

​

Explicit Subagents

research_agent = OmniCoreAgent(
    name="researcher",
    system_instruction="You specialize in web research and summarization.",
    model_config={"provider": "openai", "model": "gpt-4o"},
)

code_agent = OmniCoreAgent(
    name="coder",
    system_instruction="You are an expert Python developer.",
    model_config={"provider": "openai", "model": "gpt-4o"},
)

parent_agent = OmniCoreAgent(
    name="manager",
    system_instruction="You manage a team of specialists.",
    model_config={"provider": "openai", "model": "gpt-4o"},
    sub_agents=[research_agent, code_agent],
)

​

Example Workflow

1. User Query: “Research the latest AI news and write a Python script for a news aggregator.”
2. Manager (Parent): Recognizes this requires research and coding.
3. Manager: Calls spawn_subagents with research and coding workers, or calls explicit child agents.
4. Researcher (Sub): Performs web search, returns summaries.
5. Manager: Receives summaries, then calls code_agent with “Write a Python aggregator using this data: [summaries]”.
6. Coder (Sub): Writes the code, returns it.
7. Manager: Synthesizes the final response to the user.

​

Best Practices

• Use One Spawn Call: When tasks are independent, put every worker spec in one spawn_subagents array so they run in parallel.
• Write to Workspace Files: Give each worker a clear output_path under /workspace/{task_name}/....
• Read Before Synthesis: After workers finish, read every output path before producing the final answer.
• Explicit Instructions: For fixed subagents, briefly describe each subagent’s expertise in the parent instruction.
• Limit Depth: While hierarchical agents are powerful, avoid nesting agents too deep (e.g., Parent -> Child -> Grandchild) to prevent excessive latency and token usage.
• Keep Workers Focused: Do not give one worker the whole task. Give it a bounded role and output contract.