Parallelize work with subagents

Any agent becomes a manager by listing other agents in its subagents. You run it like any agent: one session, one result. Behind it, the manager splits the task, runs each piece as an isolated child session in parallel, may spawn follow-ups to fill gaps or verify findings, and merges the results. It pays off on parallel work: collecting data from many sources, pairing a fast text-mode searcher with a visual subagent for pages that need real clicks, or having one subagent verify another.

Build a manager

Create the subagents, then reference them by name from the manager so each stays reusable and inspectable (inline agent objects also work for one-offs).

Write each subagent description as a capability statement (“Use for…”): the manager routes on it, the same way an agent routes on a skill.
A manager that only delegates sends environments: []. Give it one only if it should also act on a surface itself.

API=https://agp.eu.hcompany.ai/api/v2
AUTH="Authorization: Bearer $HAI_API_KEY"

curl -X POST $API/agents -H "$AUTH" -H "Content-Type: application/json" -d '{
  "name": "fast-searcher",
  "description": "Searches the web quickly in text mode. Use for broad lookups.",
  "model": "holo4-35b-a3b",
  "environments": [{"id": "search-browser", "kind": "web", "mode": {"type": "text"}, "start_url": "https://www.bing.com"}]
}'
curl -X POST $API/agents -H "$AUTH" -H "Content-Type: application/json" -d '{
  "name": "visual-verifier",
  "description": "Visually inspects a page. Use to confirm a fact or read content behind interactions.",
  "environments": ["h/browser"]
}'
curl -X POST $API/agents -H "$AUTH" -H "Content-Type: application/json" -d '{
  "name": "research-orchestrator",
  "description": "Splits research across subagents and merges one sourced report.",
  "environments": [],
  "subagents": ["fast-searcher", "visual-verifier"]
}'

# Run it like any agent; read latest_answer once the session is terminal
SESSION_ID=$(curl -sX POST $API/sessions -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"agent": "research-orchestrator", "messages": "Compare the starting price of the latest Apple, Google, and Samsung flagship phones, with source URLs."}' \
  | jq -r .id)
curl -s "$API/sessions/$SESSION_ID" -H "$AUTH" | jq -r .latest_answer

from hai_agents import Client

client = Client()

client.agents.create_agent(
    name="fast-searcher",
    description="Searches the web quickly in text mode. Use for broad lookups.",
    model="holo4-35b-a3b",
    environments=[{"id": "search-browser", "kind": "web", "mode": {"type": "text"}, "start_url": "https://www.bing.com"}],
)
client.agents.create_agent(
    name="visual-verifier",
    description="Visually inspects a page. Use to confirm a fact or read content behind interactions.",
    environments=["h/browser"],
)
client.agents.create_agent(
    name="research-orchestrator",
    description="Splits research across subagents and merges one sourced report.",
    environments=[],
    subagents=["fast-searcher", "visual-verifier"],
)

result = client.run_session(
    agent="research-orchestrator",
    messages="Compare the starting price of the latest Apple, Google, and Samsung flagship phones, with source URLs.",
)
print(result.answer)

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();

await client.agents.createAgent({
  name: "fast-searcher",
  description: "Searches the web quickly in text mode. Use for broad lookups.",
  model: "holo4-35b-a3b",
  environments: [{ id: "search-browser", kind: "web", mode: { type: "text" }, startUrl: "https://www.bing.com" }],
});
await client.agents.createAgent({
  name: "visual-verifier",
  description: "Visually inspects a page. Use to confirm a fact or read content behind interactions.",
  environments: ["h/browser"],
});
await client.agents.createAgent({
  name: "research-orchestrator",
  description: "Splits research across subagents and merges one sourced report.",
  environments: [],
  subagents: ["fast-searcher", "visual-verifier"],
});

const result = await client.runSession({
  agent: "research-orchestrator",
  messages: "Compare the starting price of the latest Apple, Google, and Samsung flagship phones, with source URLs.",
});
console.log(result.answer);

From the CLI, run an existing manager with hai run --agent research-orchestrator "...". Over raw HTTP, long-poll changes until the session is terminal before reading latest_answer.

What a subagent sees

Rule	Consequence
No access to the end user: it can’t ask you questions or message you.	Give it a self-contained task. Only the manager surfaces anything.
The manager gets only its final answer, not its scrollback or observations.	A good subagent answer carries its own data, source URLs, and caveats.
It can delegate further: listing its own `subagents` makes it a manager.	Nesting is capped at 16 levels. The API rejects a deeper chain or a cycle with `422`. Stay well below it: each level multiplies sessions and cost.

Observe and control the tree

The manager’s status lists its children in subagent_session_ids. Retrieve or watch any of them like a normal session.
List children with GET /sessions?parent_session_id=..., or tag a whole run with group_id and list it with GET /sessions?group_id=....
Force an answer on the manager cascades: in-flight subagents get about 30s to wrap up, partial results fold into the manager’s answer, and anything unfinished is cancelled. Cancelling the manager stops its subagents too, with no grace window.
Child sessions never queue: at your concurrency limit, a child create fails with 429.

Get started

Concepts

Browser and desktop

Integrations

Guides

Operate

Parallelize work with subagents

Build a manager

What a subagent sees

Observe and control the tree

​Build a manager

​What a subagent sees

​Observe and control the tree

Build a manager

What a subagent sees

Observe and control the tree