enterprise_ai.runtime.runner

Source: sdks/python/src/enterprise_ai/runtime/runner.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.

Model TurnResult

Outcome of :meth:AgentRunner.run_turn.

Fields:

Name	Type	Required	Description
final_text	str | None	yes	Final answer of the model, or None when the turn stopped before one.
messages	list[dict[str, Any]]	yes	Every message of the turn, including the tool results and the nudges.
steps	int	yes	Number of model calls of the turn.
stop_reason	str	yes	Why the turn ended: completed, stopped, waiting_approval, no_progress, max_steps, max_tool_calls, max_cost or max_duration.
nudges	dict[str, int]	no	Number of times each continuation rule fired, by rule code.
usage	dict[str, Any]	no	Usage counters added to the budget consumption, for example input_tokens, output_tokens.
tool_calls	int	no	Number of tool calls of the turn.

Attributes:

Name	Type	Required	Description
ok	bool	yes	True when stop_reason is completed.
output	str | None	yes	Final answer text (same as final_text).

TurnResult.state

state() -> dict[str, Any]

Serializable state stored in checkpoints (resume input).

This element takes no parameter.

Returns: dict[str, Any]. Dict with messages, step, tool_calls, nudges, usage, stop_reason and final.

Class AgentRunner

Run agent turns against the platform gateway with tools, rules and governance.

Attributes:

Name	Type	Required	Description
agent_id		yes	Agent identifier sent in the eai extension.
approval_for		yes	Glob patterns of tool names that need a human approval.
approval_timeout		yes	Maximum wait for an approval decision, in seconds.
audit_mode		yes	Audit turn with a longer exploration allowance.
budget		yes	Limits of the turn (LoopBudget).
client		yes	Enterprise AI client (gateway, tools, runs, approvals), or None.
data_classification		yes	Classification of the data of the turn, sent in the eai extension.
effort		yes	Reasoning effort of the gateway model calls.
heartbeat		yes	Heartbeats are posted before every model and tool call.
last_heartbeat	HeartbeatResponse | None	yes	Last heartbeat answer, parsed as a HeartbeatResponse, or None.
mcp_tools		yes	OpenAI tool specs of the MCP tools.
model		yes	Model identifier used for the gateway calls.
on_event		yes	Event callback (kind, data), or None.
read_only_patterns		yes	Glob patterns of read only tool names.
remote_tool		yes	Function that runs the tools that are neither local nor MCP, or None.
remote_tools		yes	OpenAI tool specs of the Tool Gateway tools.
require_delivery		yes	The turn must use at least one tool before answering.
rules		yes	Continuation rules evaluated by the turn.
run_id		yes	Server run that receives the steps, checkpoints and heartbeats.
session_id		yes	Session identifier sent in the eai extension.
stop_event		yes	threading.Event that stops the turn at its next boundary.
subagents		yes	Subagent manager plugged into the turn, or None.
task_id		yes	Task identifier sent in the eai extension.
tools	dict[str, LocalTool]	yes	Local tools by name.
verify_patterns		yes	Glob patterns of verification tool names.
wait_for_approval		yes	The turn waits for approval decisions instead of stopping.

Constructor AgentRunner

AgentRunner(client: Any = None, model: str | None = None, model_call: ModelCall | None = None, effort: str | None = None, tools: dict[str, LocalTool] | list[LocalTool] | None = None, remote_tools: list[dict[str, Any]] | None = None, mcp_tools: list[dict[str, Any]] | None = None, remote_tool: Callable[[str, dict[str, Any]], Any] | None = None, budget: Any = None, rules: list[ContinuationRule] | None = None, agent_id: str | None = None, session_id: str | None = None, run_id: str | None = None, task_id: str | None = None, data_classification: str | None = None, approval_for: list[str] | None = None, wait_for_approval: bool = True, approval_timeout: float = 3600.0, stop_event: threading.Event | None = None, heartbeat: bool = True, require_delivery: bool = False, audit_mode: bool = False, verify_patterns: tuple[str, ...] = VERIFY_PATTERNS, read_only_patterns: tuple[str, ...] = READ_ONLY_PATTERNS, subagents: Any = None, on_event: Callable[[str, dict[str, Any]], None] | None = None) -> None

Configure the runner; it needs a model_call, or a client and a model.

Name	Type	Default	Required	Description
client	Any	None	no	Parent client.
model	str | None	None	no	Model identifier used for the gateway calls when no model_call is given.
model_call	ModelCall | None	None	no	Function (messages, tools) -> dict that replaces the gateway call.
effort	str | None	None	no	Reasoning effort of the gateway model calls.
tools	dict[str, LocalTool] | list[LocalTool] | None	None	no	Local tools, as a dict by name or a list of LocalTool.
remote_tools	list[dict[str, Any]] | None	None	no	OpenAI tool specs of the Tool Gateway tools offered to the model.
mcp_tools	list[dict[str, Any]] | None	None	no	OpenAI tool specs of MCP tools, run through client.mcp.call_tool.
remote_tool	Callable[[str, dict[str, Any]], Any] | None	None	no	Function (name, arguments) that runs the tools that are neither local nor MCP.
budget	Any	None	no	Limits of the turn (max_steps, max_tool_calls, max_cost, max_duration); a default LoopBudget when omitted.
rules	list[ContinuationRule] | None	None	no	Continuation rules; default_rules() when omitted.
agent_id	str | None	None	no	Agent identifier sent in the eai extension of the model calls.
session_id	str | None	None	no	Session identifier sent in the eai extension.
run_id	str | None	None	no	Server run that receives the steps, checkpoints and heartbeats; without it nothing is reported.
task_id	str | None	None	no	Task identifier sent in the eai extension.
data_classification	str | None	None	no	Classification of the data of the turn, sent in the eai extension.
approval_for	list[str] | None	None	no	Glob patterns of tool names (also matched as tool:<name>) that need a human approval.
wait_for_approval	bool	True	no	Wait for the approval decision; when False, the turn ends with stop_reason waiting_approval (default True).
approval_timeout	float	3600.0	no	Maximum wait for an approval decision, in seconds (default 3600.0).
stop_event	threading.Event | None	None	no	threading.Event that stops the turn at its next boundary when set; a new one by default.
heartbeat	bool	True	no	Post a heartbeat to the run before every model and tool call and stop on action=stop (default True).
require_delivery	bool	False	no	Send the model back to work when it answers without using any tool (default False).
audit_mode	bool	False	no	Audit turn: allows 8 read only rounds before the exploration nudge instead of 4 (default False).
verify_patterns	tuple[str, ...]	VERIFY_PATTERNS	no	Glob patterns of verification tool names (*test*, *verify*, *check*, *lint*).
read_only_patterns	tuple[str, ...]	READ_ONLY_PATTERNS	no	Glob patterns of read only tool names (read*, get*, list*...), used by the exploration and verification rules.
subagents	Any	None	no	Subagent manager whose inject_results adds finished subagent results to the messages before each model call.
on_event	Callable[[str, dict[str, Any]], None] | None	None	no	Function (kind, data) called on model, tool, nudge, approval_requested and stop events.

AgentRunner.approve

approve(name: str, arguments: dict[str, Any], approval_id: str | None = None) -> bool

Ask for a human approval of a tool call (tools:invoke) and wait for the decision.

Name	Type	Default	Required	Description
name	str		yes	Name of the tool to approve.
arguments	dict[str, Any]		yes	Arguments of the tool call, recorded as the reason of the request (first 500 characters).
approval_id	str | None	None	no	Existing approval request to wait for; a new one is created when omitted.

Returns: bool. True when the decision is approved; without a client or with wait_for_approval=False the turn stops as waiting_approval.

AgentRunner.call_model

call_model(messages: list[dict[str, Any]], tools: list[dict[str, Any]]) -> dict[str, Any]

Call the model with model_call, or else through client.gateway.chat with the model, effort and eai of the runner.

Name	Type	Default	Required	Description
messages	list[dict[str, Any]]		yes	Chat messages of the turn so far.
tools	list[dict[str, Any]]		yes	OpenAI tool specs offered to the model.

Returns: dict[str, Any]. Raw chat.completion dict, with eai_cost when the gateway measured the cost; raises ValueError without model_call, client or model.

Raises: ValueError.

AgentRunner.check_stop

check_stop(step: int) -> None

Raise when the stop event is set or the heartbeat answers action=stop.

Name	Type	Default	Required	Description
step	int		yes	Current step number, sent with the heartbeat.

Returns: None.

AgentRunner.checkpoint

checkpoint(state: dict[str, Any]) -> Any

Write a checkpoint of the turn on the run, labelled step-<n>.

Name	Type	Default	Required	Description
state	dict[str, Any]		yes	Turn state to store (see TurnResult.state).

Returns: Any. Answer of client.runs.checkpoint, or None without a client or a run.

AgentRunner.eai

eai() -> dict[str, Any]

The eai gateway extension: agent, session, run, task and data classification.

This element takes no parameter.

Returns: dict[str, Any]. Dict of the identity fields that are set, without empty values.

AgentRunner.execute

execute(name: str, arguments: dict[str, Any]) -> Any

Run a local, MCP or Tool Gateway tool.

Name	Type	Default	Required	Description
name	str		yes	Name of the tool requested by the model.
arguments	dict[str, Any]		yes	Arguments of the tool call, decoded from the model JSON.

Returns: Any. Result of the tool; {error: rejected_by_approver} when a Tool Gateway approval is refused; raises EaiError tool_not_found when nothing runs it.

Raises: EaiError.

AgentRunner.limit_reached

limit_reached(steps: int, tool_calls: int, cost: Decimal, started: float) -> str | None

Check the step, cost and duration limits of the budget.

Name	Type	Default	Required	Description
steps	int		yes	Model calls made in the turn so far.
tool_calls	int		yes	Tool calls made so far; the tool call limit itself is checked before each tool call.
cost	Decimal		yes	Cost spent in the turn so far, as a Decimal.
started	float		yes	time.monotonic() value at the start of the turn.

Returns: str \| None. max_steps, max_cost or max_duration for the first limit reached, otherwise None.

AgentRunner.needs_approval

needs_approval(name: str) -> bool

Tell whether a tool call needs a human approval.

Name	Type	Default	Required	Description
name	str		yes	Name of the tool.

Returns: bool. True when the local tool has requires_approval or the name matches approval_for.

AgentRunner.record

record(step: dict[str, Any]) -> None

Report a step on the run (POST /v1/runs/{id}/steps); does nothing without a client or a run.

Name	Type	Default	Required	Description
step	dict[str, Any]		yes	Step document, such as {kind: model_call, name, state} or {kind: tool_call, name, state}.

Returns: None.

AgentRunner.run_turn

run_turn(messages: list[dict[str, Any]], state: dict[str, Any] | None = None) -> TurnResult

Run one turn. state (a checkpoint) resumes a turn that was interrupted.

Name	Type	Default	Required	Description
messages	list[dict[str, Any]]		yes	Chat messages that open the turn; ignored when state holds messages.
state	dict[str, Any] | None	None	no	Checkpoint state to resume (messages, step, tool calls, nudges, usage).

Returns: TurnResult. A TurnResult: Outcome of :meth:AgentRunner.run_turn.

AgentRunner.tool_specs

tool_specs() -> list[dict[str, Any]]

Tools offered to the model: the local tools, then the Tool Gateway tools, then the MCP tools.

This element takes no parameter.

Returns: list[dict[str, Any]]. List of OpenAI function tool specs.