Delegate work with subagents

A subagent is a child agent exposed to a parent as a tool. The parent model decides whether to delegate and the child returns a result to the parent loop.

Use a workflow when application code already knows the order. Use an application fan-out group when every child must run. Use a handoff when another agent should take ownership of the conversation rather than return a tool result.

Availability and stability

Pattern	TypeScript	Python
Model-directed subagent tools	Stable	Beta
Deterministic agent groups	Stable	Beta
Direct handoffs	Stable	Stable
Child run/replay information	Stable hierarchical run state	Available; advanced helpers remain beta

These are SDK runtime levels. Provider-native multi-agent systems are separate hosted features with their own native contracts and should not be treated as equivalent.

TypeScript subagents

Configure child definitions on the parent. The runtime exposes each child as a tool and records its run under state.childRuns:

import { Agent } from "@zhivex-ai/agents";
import { createOpenAI } from "@zhivex-ai/openai";

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const model = openai("gpt-5.6-terra");

const researcher = new Agent({
  id: "researcher",
  model,
  instructions: "Return concise findings and state uncertainty.",
  maxSteps: 3
});

const coordinator = new Agent({
  id: "coordinator",
  model,
  instructions: "Delegate only when research is required.",
  subagents: [
    {
      name: "research",
      description: "Investigate one bounded question.",
      agent: researcher,
      maxSteps: 3,
      requiresApproval: true
    }
  ],
  maxSteps: 4
});

const result = await coordinator.run({
  prompt: "Assess the migration risk.",
  scope: { tenantId: "acme", userId: "user-7" },
  idempotencyKey: "risk-review-42"
});

When the parent and child use a durable run store, completed child work can be reused after a failed parent checkpoint instead of repeating child tools. A child waiting for approval is promoted into the parent’s pending approvals and resumes through the same child checkpoint.

Python subagents

Python’s native subagent-tool surface is beta. Keep it behind your own orchestration service:

from zhivex_ai import Agent, create_openai, run_agent

provider = create_openai()
researcher = Agent(
    name="researcher",
    model=provider("gpt-5.6-terra"),
    instructions="Return concise findings and state uncertainty.",
)

coordinator = Agent(
    name="coordinator",
    model=provider("gpt-5.6-terra"),
    instructions="Delegate only when research is required.",
    subagents={"research": researcher},
)

result = await run_agent(
    agent=coordinator,
    prompt="Assess the migration risk.",
    idempotency_key="risk-review-42",
)

For a stable sequential transfer in Python, use a local tool that returns handoff_to("specialist", input=...) and register that specialist in Agent.subagents. A handoff changes the active agent; a beta native subagent tool runs a child and returns its output to the parent.

Bound delegation

• Give each child one purpose, a narrow tool allowlist, explicit instructions, and a small maxSteps value.
• Put total model steps, child runs, tool calls, tokens, cost, wall time, and recursion depth under an application policy. A per-child limit is not a total request budget.
• Require human approval for child tools that write, send, pay, deploy, browse private systems, execute code, or cross a trust boundary.
• Pass tenant and user scope from authenticated application state. Parent and child identifiers are trace relationships, not authorization.
• Use a durable store and idempotency keys for effectful runs. Forward the child tool’s cancellation and idempotency context to downstream services.
• Treat child output as untrusted model output. Validate structured results before the parent or application uses them in a side effect.

Preserve observability

Record the parent run id, child run id, delegated task, model, steps, usage, status, tool names, approval decisions, and errors. Redact prompts, tool arguments, tool output, and final text unless the destination is approved for sensitive data.

Do not flatten the hierarchy into one transcript: separate child traces make cost attribution, approval review, replay, and incident diagnosis possible. Continue with observability and evals.

For deterministic orchestration, use workflows. For delegated remote capabilities, see MCP and hosted tools. Apply the full production boundary to every parent and child.