> ## Documentation Index
> Fetch the complete documentation index at: https://docs-omnicoreagent.omnirexfloralabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subagents

> Dynamic and explicit task delegation inside OmniCoreAgent

# Subagents

OmniCoreAgent supports subagents as part of the core harness. A lead agent can
spawn focused workers dynamically with `spawn_subagents`, or you can attach
explicit subagents when you want a fixed team. Workers can execute any assigned
task their tools support: research, coding, review, data work, writing,
verification, or operational actions.

## 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

Enable dynamic subagents directly on OmniCoreAgent:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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},
    },
)
```

Workspace files are available by default, and `enable_subagents` also keeps
them enabled for worker output. Dynamic workers are expected to save output with
`write_file`, and the lead agent reads those paths with `read_file` before
synthesizing.

### `spawn_subagents`

`spawn_subagents` accepts one JSON array. Use one item for one worker, or many
items for parallel workers.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "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"
  }
]
```

Spawned workers inherit the parent's model, MCP tools, user local tools,
workspace files, context management, and tool offloading. They do not inherit
the lead agent's `spawn_subagents` tool, which keeps delegation controlled by
the lead agent.

***

## Explicit Subagents

Use explicit subagents when the team is known upfront and each child agent has a
stable role or custom tool set.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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],
)
```

When a parent agent has explicit subagents, it is given tools to communicate
with them:

| Tool             | Action                                                         |
| ---------------- | -------------------------------------------------------------- |
| `call_sub_agent` | Send a specific task to a child agent and wait for the result. |

***

## 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.