Parallelize work with subagents

Multi-agent is in preview. The API and behavior may change before general availability. Feedback is welcome at support@hcompany.ai.

Any agent becomes a manager by listing other agents in its subagents. At runtime the manager breaks the task into pieces, hands each piece to a subagent, and writes the final answer once it has gathered enough. You launch a manager exactly like any other agent: one session, one answer. The fan-out happens behind it. Each subagent is a full agent with its own environment, model, skills, and instructions, and runs as its own session, isolated from its siblings. The manager runs them in parallel, so breadth that would be sequential for one agent happens at once. Multi-agent is especially efficient for parallelizable tasks: researching a question across many sources at once, pairing a fast text-mode searcher with a visual subagent for pages that need real clicks, or having one subagent verify what another found.

Build a manager

A manager is just an agent whose subagents list names other agents. Create the specialists first, then reference them by name from the manager so each stays reusable and independently inspectable (inline objects also work, for one-offs). Here a research manager delegates to a fast text-mode searcher and a visual verifier.

Create the subagents

Create a fast text-mode searcher for broad lookups and a visual verifier for pages that need real clicks. Write each description as a capability statement (“Use for…”), since the manager routes on it to pick who handles what, the same way an agent routes on a skill.

# Fast text-mode searcher
curl -X POST https://agp.eu.hcompany.ai/api/v2/agents \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fast-searcher",
    "description": "Searches the web quickly in text mode. Use for broad lookups and gathering candidate sources.",
    "model": "holo3-1-35b-a3b",
    "environments": [
      {"id": "search-browser", "kind": "web", "mode": {"type": "text"}, "start_url": "https://www.bing.com"}
    ]
  }'

# Visual verifier
curl -X POST https://agp.eu.hcompany.ai/api/v2/agents \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "visual-verifier",
    "description": "Visually inspects a specific page to confirm a fact or read content behind interactions.",
    "environments": ["h/browser"]
  }'

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 "
        "and gathering candidate sources."
    ),
    model="holo3-1-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 specific page to confirm a fact or read "
        "content behind interactions."
    ),
    environments=["h/browser"],
)

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 and gathering candidate sources.",
  model: "holo3-1-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 specific page to confirm a fact or read content behind interactions.",
  environments: ["h/browser"],
});

Create the manager

Now create the manager and link the subagents by name. A manager that only delegates can omit environments; give it one only if it should also act on a surface itself, as this one does.

curl -X POST https://agp.eu.hcompany.ai/api/v2/agents \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "research-orchestrator",
    "description": "Researches a question across sources and synthesizes a sourced answer.",
    "environments": ["h/browser"],
    "instructions": "Split the question into independent sub-questions, delegate each, then reconcile the findings into one sourced answer.",
    "subagents": ["fast-searcher", "visual-verifier"]
  }'

client.agents.create_agent(
    name="research-orchestrator",
    description="Researches a question across sources and synthesizes a sourced answer.",
    environments=["h/browser"],
    instructions=(
        "Split the question into independent sub-questions, delegate each, "
        "then reconcile the findings into one sourced answer."
    ),
    subagents=["fast-searcher", "visual-verifier"],
)

await client.agents.createAgent({
  name: "research-orchestrator",
  description: "Researches a question across sources and synthesizes a sourced answer.",
  environments: ["h/browser"],
  instructions:
    "Split the question into independent sub-questions, delegate each, " +
    "then reconcile the findings into one sourced answer.",
  subagents: ["fast-searcher", "visual-verifier"],
});

Run a session

Launch a session against the manager exactly like a single agent; the fan-out to subagents happens behind it. Over raw HTTP, create the session and long-poll changes until it reaches a terminal state.

hai run --agent research-orchestrator \
  "Compare the starting price of the latest flagship phone from Apple, Google, and Samsung. Return one line per phone with the price, currency, and the source URL you read it from."

# Create the session and capture its id
SESSION_ID=$(curl -sX POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "research-orchestrator",
    "messages": [
      {"type": "user_message", "message": "Compare the starting price of the latest flagship phone from Apple, Google, and Samsung. Return one line per phone with the price, currency, and the source URL you read it from."}
    ]
  }' | jq -r .id)

# Long-poll until the session reaches a terminal state, then print the answer.
# Advance FROM_INDEX each turn so the server waits for *new* changes instead of replaying old ones.
FROM_INDEX=0
while true; do
  CHANGES=$(curl -s "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/changes?from_index=$FROM_INDEX&wait_for_seconds=25" \
    -H "Authorization: Bearer $HAI_API_KEY")
  [ -z "$CHANGES" ] && continue  # 204 No Content: nothing new yet
  FROM_INDEX=$((FROM_INDEX + $(echo "$CHANGES" | jq '.new_events | length')))
  STATUS=$(echo "$CHANGES" | jq -r .status)
  echo "status: $STATUS"
  case "$STATUS" in
    completed|failed|timed_out|interrupted)
      echo "$CHANGES" | jq -r .answer
      break
      ;;
  esac
done

result = client.run_session(
    agent="research-orchestrator",
    messages="Compare the starting price of the latest flagship phone from Apple, Google, and Samsung. Return one line per phone with the price, currency, and the source URL you read it from.",
)

print(result.status)  # "completed"
print(result.answer)

const result = await client.runSession({
  agent: "research-orchestrator",
  messages:
    "Compare the starting price of the latest flagship phone from Apple, Google, and " +
    "Samsung. Return one line per phone with the price, currency, and the source URL you read it from.",
});

console.log(result.status); // "completed"
console.log(result.answer);

How a run unfolds

The manager spawns subagents as parallel child sessions, waits for their answers, and may spawn follow-ups to fill gaps or verify findings before synthesizing the single final answer your session receives.

What a subagent sees

A subagent works in isolation and is instructed to finish its task on its own:

It has no access to the end user. It cannot ask questions or send messages to you; only the manager surfaces anything. Give it a self-contained task.
The manager receives only the subagent’s final answer, not its scrollback or intermediate observations. A good subagent answer carries its own data, source URLs, and caveats.
It can delegate further. A subagent that lists its own subagents becomes a manager for them, nested up to 16 levels deep; a deeper chain or a cycle is rejected with 422. Keep trees shallow well before that limit, since deep nesting multiplies sessions and cost.

Observe and control the tree

Each subagent is a real session, so the whole tree is inspectable and steerable:

The manager’s status lists its children in subagent_session_ids. Retrieve or watch any of them like a normal session.
Filter children by their parent 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 and the signal cascades: in-flight subagents get a short grace window (about 30s) to wrap up, partial results fold into the manager’s answer, and anything still unfinished is cancelled. Cancelling the manager stops its subagents too, without the grace window.

Get started

Concepts

Browser

Desktop

Integrations

Guides

Platform

Parallelize work with subagents

Build a manager

Create the subagents

Create the manager

Run a session

How a run unfolds

What a subagent sees

Observe and control the tree

​Build a manager

Create the subagents

Create the manager

Run a session

​How a run unfolds

​What a subagent sees

​Observe and control the tree

Build a manager

How a run unfolds

What a subagent sees

Observe and control the tree