enterprise_ai.runtime.runner

Source : sdks/python/src/enterprise_ai/runtime/runner.py. Retour à l'index de la référence du SDK Python.

remarque

Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.

Modèle TurnResult

Résultat de :meth:AgentRunner.run_turn.

Champs :

Nom	Type	Requis	Description
final_text	str | None	oui	Réponse finale du modèle, ou None si le tour s'est arrêté avant.
messages	list[dict[str, Any]]	oui	Tous les messages du tour, y compris les résultats d'outils et les relances.
steps	int	oui	Nombre d'appels au modèle du tour.
stop_reason	str	oui	Raison de la fin du tour : completed, stopped, waiting_approval, no_progress, max_steps, max_tool_calls, max_cost ou max_duration.
nudges	dict[str, int]	non	Nombre de déclenchements de chaque règle de continuation, par code de règle.
usage	dict[str, Any]	non	Compteurs d'usage ajoutés à la consommation de budget, par exemple input_tokens, output_tokens.
tool_calls	int	non	Nombre d'appels d'outils du tour.

Attributs :

Nom	Type	Requis	Description
ok	bool	oui	Vrai quand stop_reason vaut completed.
output	str | None	oui	Texte de la réponse finale (identique à final_text).

TurnResult.state

state() -> dict[str, Any]

État sérialisable stocké dans les checkpoints (entrée de reprise).

Cet élément ne prend aucun paramètre.

Retour : dict[str, Any]. Dict avec messages, step, tool_calls, nudges, usage, stop_reason et final.

Classe AgentRunner

Exécute des tours d'agent via la passerelle de la plateforme, avec outils, règles et gouvernance.

Attributs :

Nom	Type	Requis	Description
agent_id		oui	Identifiant de l'agent envoyé dans l'extension eai.
approval_for		oui	Motifs glob des noms d'outils qui demandent une approbation humaine.
approval_timeout		oui	Attente maximale d'une décision d'approbation, en secondes.
audit_mode		oui	Tour d'audit avec une marge d'exploration plus longue.
budget		oui	Limites du tour (LoopBudget).
client		oui	Client Enterprise AI (passerelle, outils, runs, approbations), ou None.
data_classification		oui	Classification des données du tour, envoyée dans l'extension eai.
effort		oui	Effort de raisonnement des appels au modèle via la passerelle.
heartbeat		oui	Les heartbeats sont envoyés avant chaque appel au modèle et à un outil.
last_heartbeat	HeartbeatResponse | None	oui	Dernière réponse de heartbeat, analysée en HeartbeatResponse, ou None.
mcp_tools		oui	Specs d'outils OpenAI des outils MCP.
model		oui	Identifiant du modèle utilisé pour les appels à la passerelle.
on_event		oui	Fonction de rappel des événements (kind, data), ou None.
read_only_patterns		oui	Motifs glob des noms d'outils en lecture seule.
remote_tool		oui	Fonction qui exécute les outils ni locaux ni MCP, ou None.
remote_tools		oui	Specs d'outils OpenAI des outils du Tool Gateway.
require_delivery		oui	Le tour doit utiliser au moins un outil avant de répondre.
rules		oui	Règles de continuation évaluées par le tour.
run_id		oui	Run serveur qui reçoit les étapes, checkpoints et heartbeats.
session_id		oui	Identifiant de session envoyé dans l'extension eai.
stop_event		oui	threading.Event qui arrête le tour à sa prochaine frontière.
subagents		oui	Gestionnaire de sous-agents branché sur le tour, ou None.
task_id		oui	Identifiant de tâche envoyé dans l'extension eai.
tools	dict[str, LocalTool]	oui	Outils locaux par nom.
verify_patterns		oui	Motifs glob des noms d'outils de vérification.
wait_for_approval		oui	Le tour attend les décisions d'approbation au lieu de s'arrêter.

Constructeur 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 le runner ; il lui faut un model_call, ou un client et un model.

Nom	Type	Défaut	Requis	Description
client	Any	None	non	Client parent.
model	str | None	None	non	Identifiant du modèle utilisé pour les appels à la passerelle quand aucun model_call n'est fourni.
model_call	ModelCall | None	None	non	Fonction (messages, tools) -> dict qui remplace l'appel à la passerelle.
effort	str | None	None	non	Effort de raisonnement des appels au modèle via la passerelle.
tools	dict[str, LocalTool] | list[LocalTool] | None	None	non	Outils locaux, sous forme de dict par nom ou de liste de LocalTool.
remote_tools	list[dict[str, Any]] | None	None	non	Specs d'outils OpenAI des outils du Tool Gateway proposés au modèle.
mcp_tools	list[dict[str, Any]] | None	None	non	Specs d'outils OpenAI des outils MCP, exécutés via client.mcp.call_tool.
remote_tool	Callable[[str, dict[str, Any]], Any] | None	None	non	Fonction (name, arguments) qui exécute les outils ni locaux ni MCP.
budget	Any	None	non	Limites du tour (max_steps, max_tool_calls, max_cost, max_duration) ; un LoopBudget par défaut s'il est omis.
rules	list[ContinuationRule] | None	None	non	Règles de continuation ; default_rules() si elles sont omises.
agent_id	str | None	None	non	Identifiant de l'agent envoyé dans l'extension eai des appels au modèle.
session_id	str | None	None	non	Identifiant de session envoyé dans l'extension eai.
run_id	str | None	None	non	Run serveur qui reçoit les étapes, checkpoints et heartbeats ; sans lui, rien n'est remonté.
task_id	str | None	None	non	Identifiant de tâche envoyé dans l'extension eai.
data_classification	str | None	None	non	Classification des données du tour, envoyée dans l'extension eai.
approval_for	list[str] | None	None	non	Motifs glob de noms d'outils (comparés aussi sous la forme tool:<nom>) qui demandent une approbation humaine.
wait_for_approval	bool	True	non	Attend la décision d'approbation ; si False, le tour se termine avec le stop_reason waiting_approval (True par défaut).
approval_timeout	float	3600.0	non	Attente maximale d'une décision d'approbation, en secondes (3600.0 par défaut).
stop_event	threading.Event | None	None	non	threading.Event qui arrête le tour à sa prochaine frontière quand il est positionné ; un nouvel événement par défaut.
heartbeat	bool	True	non	Envoie un heartbeat au run avant chaque appel au modèle et à un outil, et s'arrête sur action=stop (True par défaut).
require_delivery	bool	False	non	Renvoie le modèle au travail quand il répond sans avoir utilisé d'outil (False par défaut).
audit_mode	bool	False	non	Tour d'audit : autorise 8 tours en lecture seule avant la relance d'exploration au lieu de 4 (False par défaut).
verify_patterns	tuple[str, ...]	VERIFY_PATTERNS	non	Motifs glob des noms d'outils de vérification (*test*, *verify*, *check*, *lint*).
read_only_patterns	tuple[str, ...]	READ_ONLY_PATTERNS	non	Motifs glob des noms d'outils en lecture seule (read*, get*, list*...), utilisés par les règles d'exploration et de vérification.
subagents	Any	None	non	Gestionnaire de sous-agents dont inject_results ajoute les résultats des sous-agents terminés aux messages avant chaque appel au modèle.
on_event	Callable[[str, dict[str, Any]], None] | None	None	non	Fonction (kind, data) appelée sur les événements model, tool, nudge, approval_requested et stop.

AgentRunner.approve

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

Demande une approbation humaine d'un appel d'outil (tools:invoke) et attend la décision.

Nom	Type	Défaut	Requis	Description
name	str		oui	Nom de l'outil à approuver.
arguments	dict[str, Any]		oui	Arguments de l'appel d'outil, inscrits comme motif de la demande (500 premiers caractères).
approval_id	str | None	None	non	Demande d'approbation existante à attendre ; une nouvelle est créée si elle est omise.

Retour : bool. Vrai quand la décision vaut approved ; sans client ou avec wait_for_approval=False, le tour s'arrête en waiting_approval.

AgentRunner.call_model

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

Appelle le modèle avec model_call, sinon via client.gateway.chat avec le modèle, l'effort et l'eai du runner.

Nom	Type	Défaut	Requis	Description
messages	list[dict[str, Any]]		oui	Messages de chat du tour jusqu'ici.
tools	list[dict[str, Any]]		oui	Specs d'outils OpenAI proposées au modèle.

Retour : dict[str, Any]. Dict chat.completion brut, avec eai_cost quand la passerelle a mesuré le coût ; lève ValueError sans model_call, client ou modèle.

Erreurs levées : ValueError.

AgentRunner.check_stop

check_stop(step: int) -> None

Lève une exception quand l'événement d'arrêt est positionné ou que le heartbeat répond action=stop.

Nom	Type	Défaut	Requis	Description
step	int		oui	Numéro de l'étape courante, envoyé avec le heartbeat.

Retour : None.

AgentRunner.checkpoint

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

Écrit un checkpoint du tour sur le run, nommé step-<n>.

Nom	Type	Défaut	Requis	Description
state	dict[str, Any]		oui	État du tour à enregistrer (voir TurnResult.state).

Retour : Any. Réponse de client.runs.checkpoint, ou None sans client ni run.

AgentRunner.eai

eai() -> dict[str, Any]

L'extension eai de la passerelle : agent, session, run, tâche et classification des données.

Cet élément ne prend aucun paramètre.

Retour : dict[str, Any]. Dict des champs d'identité renseignés, sans les valeurs vides.

AgentRunner.execute

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

Exécute un outil local, MCP ou du Tool Gateway.

Nom	Type	Défaut	Requis	Description
name	str		oui	Nom de l'outil demandé par le modèle.
arguments	dict[str, Any]		oui	Arguments de l'appel d'outil, décodés depuis le JSON du modèle.

Retour : Any. Résultat de l'outil ; {error: rejected_by_approver} quand une approbation du Tool Gateway est refusée ; lève EaiError tool_not_found si rien ne l'exécute.

Erreurs levées : EaiError.

AgentRunner.limit_reached

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

Vérifie les limites d'étapes, de coût et de durée du budget.

Nom	Type	Défaut	Requis	Description
steps	int		oui	Appels au modèle effectués dans le tour jusqu'ici.
tool_calls	int		oui	Appels d'outils effectués jusqu'ici ; la limite d'appels d'outils est elle-même vérifiée avant chaque appel.
cost	Decimal		oui	Coût dépensé dans le tour jusqu'ici, en Decimal.
started	float		oui	Valeur de time.monotonic() au début du tour.

Retour : str \| None. max_steps, max_cost ou max_duration pour la première limite atteinte, sinon None.

AgentRunner.needs_approval

needs_approval(name: str) -> bool

Indique si un appel d'outil demande une approbation humaine.

Nom	Type	Défaut	Requis	Description
name	str		oui	Nom de l'outil.

Retour : bool. Vrai quand l'outil local a requires_approval ou que le nom correspond à approval_for.

AgentRunner.record

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

Remonte une étape sur le run (POST /v1/runs/{id}/steps) ; sans effet sans client ni run.

Nom	Type	Défaut	Requis	Description
step	dict[str, Any]		oui	Document d'étape, par exemple {kind: model_call, name, state} ou {kind: tool_call, name, state}.

Retour : None.

AgentRunner.run_turn

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

Exécute un tour. state (un checkpoint) reprend un tour interrompu.

Nom	Type	Défaut	Requis	Description
messages	list[dict[str, Any]]		oui	Messages de chat qui ouvrent le tour ; ignorés quand state contient des messages.
state	dict[str, Any] | None	None	non	État de checkpoint à reprendre (messages, étape, appels d'outils, relances, consommation).

Retour : TurnResult. Un TurnResult : résultat de :meth:AgentRunner.run_turn.

AgentRunner.tool_specs

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

Outils proposés au modèle : les outils locaux, puis ceux du Tool Gateway, puis les outils MCP.

Cet élément ne prend aucun paramètre.

Retour : list[dict[str, Any]]. Liste de specs d'outils fonction OpenAI.