enterprise_ai.subagents

Source: sdks/python/src/enterprise_ai/subagents/__init__.py. Back to the Python SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Class SubagentSpawner

Track spawned children of one run and refuse spawns beyond the limits.

Attributes:

Name	Type	Required	Description
children	list[Any]	yes	Children spawned so far: server answers for spawn, results for spawn_local.
client		yes	Platform client used for remote children, None for local use only.
depth		yes	Depth of the current run, 0 for the root.
max_depth		yes	Deepest level a child may reach.
max_subagents		yes	Maximum number of children of this run.
run_id		yes	Parent run on the server, None for local children.

Constructor SubagentSpawner

SubagentSpawner(client: Any = None, run_id: str | None = None, depth: int = 0, max_depth: int = 1, max_subagents: int = 3) -> None

Spawner of one run with its depth and count limits; no child yet.

Name	Type	Default	Required	Description
client	Any	None	no	Parent client.
run_id	str | None	None	no	Parent run on the server, needed by spawn.
depth	int	0	no	Depth of the current run, 0 for the root (default 0).
max_depth	int	1	no	Deepest level a child may reach (default 1); beyond it PolicyDenied subagent_depth_exceeded is raised.
max_subagents	int	3	no	Maximum number of children of this run (default 3); beyond it BudgetExhausted subagent_limit is raised.

SubagentSpawner.child

child() -> SubagentSpawner

Spawner for a grandchild level (depth + 1), sharing the limits.

This element takes no parameter.

Returns: SubagentSpawner. A SubagentSpawner: Track spawned children of one run and refuse spawns beyond the limits.

SubagentSpawner.from_manifest

from_manifest(manifest: dict[str, Any], **kwargs: Any) -> SubagentSpawner

Build a spawner with the limits spec.autonomy.max_depth (default 1) and max_subagents (default 3) of an Agent Manifest.

Name	Type	Default	Required	Description
manifest	dict[str, Any]		yes	Agent Manifest of the parent, as a dict.
**kwargs	Any		no	Other constructor arguments: client, run_id, depth.

Returns: SubagentSpawner. A SubagentSpawner: Track spawned children of one run and refuse spawns beyond the limits.

SubagentSpawner.spawn

spawn(agent: str, input: Any = None, **extra: Any) -> Any

Spawn a sub-agent run. Starts a child run from a pending or running parent (else 409 run_not_running) and returns its Execution Contract. Needs tenant_admin, developer or agent and the scope agents:run. Checks, in order: the Kill Switch Registry; the depth against autonomy.max_depth (default 1, 409 subagent_depth_exceeded); the number of children against autonomy.max_subagents (default 3, 409 subagent_count_exceeded); the child agent against the subagents list of the parent manifest (403 subagent_not_allowed); the parent delegation. The child budget cannot exceed what the parent has left, the child joins the parent session, and a running parent records a subagent step.

Route: /v1/runs/{run_id}/subagents (POST).

Name	Type	Default	Required	Description
agent	str		yes	Child agent, name or agent:<name>. Default: the agent of the parent run.
input	Any	None	no	Input of the child run, optional.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Spawn a sub-agent run".

Raises: ValueError, the typed errors of the transport (Errors).

SubagentSpawner.spawn_local

spawn_local(agent: Any, task: Any, **run_kwargs: Any) -> Any

Run a child :class:~enterprise_ai.agent.Agent in-process with depth + 1.

Name	Type	Default	Required	Description
agent	Any		yes	Local agent; its subagents is set to a spawner one level deeper before it runs.
task	Any		yes	Task given to agent.run.
**run_kwargs	Any		no	Extra arguments of agent.run.

Returns: Any. What agent.run returns.

Model SubagentResult

Result of one child run.

Fields:

Name	Type	Required	Description
name	str	yes	Name of the child agent (remote name, or the name of the local agent or callable).
run_id	str | None	yes	Run of a remote child, None for a local one.
state	str	yes	Final state in lowercase, for example completed, succeeded, failed or timed_out.
output	Any	no	Output of the operation (transcript, image references...).
error	str | None	no	Error message of a failed or timed out child, None otherwise.

Class SubagentManager

Spawn children in parallel, monitor them and inject their results into the parent turn.

SubagentSpawner

Attributes:

Name	Type	Required	Description
max_parallel		yes	Maximum number of children running at the same time.
poll_interval		yes	Seconds between two reads of a remote child run.
results	list[SubagentResult]	yes	Every SubagentResult collected by run_parallel, in order.
timeout		yes	Maximum wait in seconds for a remote child.

Constructor SubagentManager

SubagentManager(max_parallel: int = 4, poll_interval: float = 1.0, timeout: float = 3600.0, **kwargs: Any) -> None

Build a spawner able to run children in parallel; the limits come from the SubagentSpawner arguments.

Name	Type	Default	Required	Description
max_parallel	int	4	no	Maximum number of children running at the same time (default 4).
poll_interval	float	1.0	no	Seconds between two reads of a remote child run (default 1).
timeout	float	3600.0	no	Maximum wait in seconds for a remote child (default 3600); past it the result is timed_out.
**kwargs	Any		no	Arguments of SubagentSpawner: client, run_id, depth, max_depth, max_subagents.

SubagentManager.inject_results

inject_results(messages: list[dict[str, Any]]) -> int

Append the results not yet announced as one user message. Returns how many were added.

Name	Type	Default	Required	Description
messages	list[dict[str, Any]]		yes	Message list of the parent turn, extended in place with a user message Subagent results:.

Returns: int. Number of results announced, 0 when none was pending (no message added).

SubagentManager.run_parallel

run_parallel(tasks: list[tuple[Any, Any]]) -> list[SubagentResult]

Run [(agent, input), ...] in parallel; agent is a name (remote) or a local agent/callable.

Name	Type	Default	Required	Description
tasks	list[tuple[Any, Any]]		yes	Pairs (agent, input); the limits are checked for every child before any starts.

Returns: list[SubagentResult]. A SubagentResult: Result of one child run.

Raises: ValueError.