Invocation Methods

Every time one agent dispatches another, Distri resolves an invocation: a small set of dials that decide how the child runs, what it can see, and how its result comes back. The LLM-facing invoke_agent tool hard-codes safe defaults for all of them, so the model never has to think about it. This page is for when you're orchestrating agents yourself and want to know what those dials are.

The dials

Join controls how the caller waits for results.

Value	Behavior
single	One dispatch, one result. The caller blocks and gets it back.
all	Fan out to several targets, wait for all, collect the results.
detached	Fire and forget: the child runs independently and the caller moves on.

Context scope is what history the child starts with.

Value	Behavior
independent	A fresh history. Whatever the child needs is in its prompt.
inherited	A copy of the parent's context at dispatch time.
shared	The same live context as the parent.

Executor hint is where the child runs (auto lets the runtime pick the runner from the agent's constraints and the caller's environment; other hints pin it to a specific executor).

Tool policy is which tools the child gets. inherit passes the parent's external tools down; other policies scope or restrict them.

What invoke_agent picks

The single-tool path is deliberately opinionated. invoke_agent always uses:

• Join single: one call, one result (fan out with multiple tool calls).
• Context scope independent: the child starts fresh.
• Executor hint auto: the runtime chooses the runner.
• Tool policy inherit: the child can use the parent's external tools.

For anything beyond that (detached background children, shared context, waiting on many results), an agent uses the supervisor tools (wait_task, get_task_result, cancel_task) rather than more knobs on the dispatch itself.

Related

• Sub-Tasks: the tool that puts these to work.
• Deep Agents: orchestration patterns built on invocations.