Subagents¶

Subagents let a profile delegate bounded, isolated work to explicitly declared children. The parent chooses a task; the child runs with its own configuration and returns evidence or a typed result. It is not an implicit ability to spawn any profile or inspect the parent's local variables.

Declare Direct Children¶

> profile: investigator:
    ###
    Inspect supplied test evidence and identify what remains unverified.
    ###
    > adapter: pydantic
    > system: Separate observed results from missing evidence.

> profile: coordinator:
    > adapter: pydantic
    > subagent: investigator
    > max_agents: 3

> use: coordinator
[answer] << Ask investigator to assess: unit tests passed; integration tests were not run. Summarize release uncertainty.
= <answer>

Supply a model through the CLI or Python embedding. The parent sees delegate_task with a child-name argument restricted to investigator. The main program actually invokes the coordinator, but the model still chooses whether to use its tool; configuration alone is not proof of delegation.

Forward profile references are valid. Unknown children and cycles are rejected. For a graph A -> B -> C, A may call B but cannot call C unless A also lists C directly. The first block comment in each profile supplies its description.

Choose an Orchestration Mode¶

The default > workflow: delegate gives the model delegation and supported lifecycle tools. > workflow: dynamic instead gives it run_workflow(code) and exposes the direct children as async functions inside a sandbox.

Use delegate mode for one child result at a time. Use Dynamic Workflows for generated dependencies and fan-out. Both modes preserve the same child boundaries, budgets, and approval ceilings.

Child Isolation¶

A child receives its own profile, not the parent's conversation, local values, or tools. Include the objective, relevant data, constraints, and expected result in task. See Limits, Isolation and Safety.

delegate_task¶

The model-facing arguments are subagent, task, optional final_schema, and background where supported. A successful foreground result contains run_id, subagent, task_summary, and final_result.

A profile's > output: Type supplies the default result schema; an explicit final_schema overrides it. With neither, task_summary carries text and final_result is null. Read Typed Child Results for schemas, validation, and examples.

Budgets and Usage Limits¶

Total descendant starts, concurrent children, depth, per-child usage, and deadlines are separate limits. Failed admitted starts still consume budget. Limits and Safety gives defaults, caps, and the behavior of each boundary.

Foreground and Background¶

Foreground calls wait for a completed result. Background calls return a handle and require later observation. See Foreground and Background Runs for exact tool results, caller wait timeouts, cancellation, and cleanup.

Fail-Closed Observation¶

A background handle is not evidence that work succeeded. Under fail-closed policy, unresolved delegated work prevents the parent from completing as though it had succeeded. Status inspection is not successful result observation. See Observe Before Returning.

Continue a Conversation¶

continue_subagent starts a new run in the same bounded conversation. Only the latest completed run can be continued, by its owning profile. See Continuations and Persistence.

Safety Ceiling¶

Child working directories, sandboxes, and approvals cannot widen inherited host permissions. This is distinct from the child's isolated prompt/tool configuration. See Host Safety Ceilings.

Restart Persistence¶

Persistence can restore completed results and bounded continuation state. Interrupted live requests restore as failures, not resumed provider work. See Continuations and Persistence.

Adapter Support¶

Pydantic AI, LangChain, Claude Agent SDK, Codex App Server, and DSPy support child execution. Background lifecycle requires asynchronous ownership and is not available through DSPy's bridge. Unsupported capabilities fail explicitly; consult the capability matrix.

Reading Path¶

1. Typed Child Results: define what the parent consumes.
2. Foreground and Background Runs: own and observe work.
3. Limits, Isolation and Safety: bound resources and authority.
4. Continuations and Persistence: refine and restore.
5. Dynamic Workflows: compose child calls in code.
6. Python Embedding: configure, inspect, and close a runtime.
7. Reviewed Evidence Workflow: execute the complete path.

The model-facing tools are not a Python kedi.subagent() API. Python callers embed a program through public compilation/context APIs; coordinator internals are not required application APIs.