enterprise_ai.loop

Source : sdks/python/src/enterprise_ai/loop/__init__.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 LoopBudget

Budgets locaux ; None signifie illimité.

Champs :

Nom	Type	Requis	Description
max_steps	int	non	Nombre maximal d'appels au modèle (étapes de planification). Par défaut 20.
max_tool_calls	int | None	non	Nombre maximal d'appels d'outils sur l'exécution ; None signifie illimité.
max_output_tokens	int | None	non	Nombre maximal de jetons de sortie sur l'exécution ; None signifie illimité.
max_cost	Decimal | None	non	Coût mesuré maximal de l'exécution, sous forme de Decimal ; None signifie illimité.
max_recoveries	int	non	Nombre maximal de reprises après un appel d'outil en échec ou une réponse rejetée avant l'échec de l'exécution. Par défaut 3.
max_duration	float | None	non	Durée maximale de l'exécution, en secondes ; None signifie illimité.
max_seconds	float | None	non	Alias de max_duration, conservé pour la compatibilité.

LoopBudget.from_manifest

from_manifest(manifest: dict[str, Any]) -> LoopBudget

Budgets issus de spec.autonomy, spec.budgets et spec.runtime.limits.

Nom	Type	Défaut	Requis	Description
manifest	dict[str, Any]		oui	Manifeste d'agent sous forme de dictionnaire, lu sous sa clé spec.

Retour : LoopBudget. Un LoopBudget : budgets locaux ; None signifie illimité.

Modèle LoopState

État sérialisable d'une exécution (enregistré dans les points de reprise).

Champs :

Nom	Type	Requis	Description
messages	list[dict[str, Any]]	non	Messages de conversation de l'exécution, résultats d'outils compris.
step	int	non	Étape courante, texte libre (500 caractères au plus).
tool_calls	int	non	Nombre d'appels d'outils exécutés jusqu'ici.
input_tokens	int	non	Jetons d'entrée comptés sur l'exécution.
output_tokens	int	non	Jetons de sortie comptés sur l'exécution.
cost	str	non	Coût mesuré jusqu'ici, sous forme de chaîne décimale. Par défaut "0".
pending	list[dict[str, Any]]	non	Appels d'outils demandés par le modèle et pas encore exécutés.
final	Any	non	Vrai si c'est la dernière étape du run. Faux par défaut.
status	str	non	Statut de l'exécution : running (par défaut), completed, failed, budget_exhausted ou stopped.
recoveries	int	non	Nombre de reprises jusqu'ici (appels d'outils en échec ou réponses rejetées).
last_error	str | None	non	Dernier échec ou nom du budget épuisé, ou None.
phase	str	non	Prochaine phase à exécuter : plan (par défaut), act, verify ou done.
started_at	float	non	Valeur de l'horloge monotone au démarrage, utilisée pour max_duration ; non enregistrée dans les points de reprise.

LoopState.from_dict

from_dict(data: dict[str, Any]) -> LoopState

Reconstruit un état à partir d'un dictionnaire de point de reprise ; les clés inconnues et started_at sont ignorées.

Nom	Type	Défaut	Requis	Description
data	dict[str, Any]		oui	Dictionnaire produit par to_dict, par exemple le state d'un point de reprise.

Retour : LoopState. Un LoopState : état sérialisable d'une exécution (enregistré dans les points de reprise).

LoopState.to_dict

to_dict() -> dict[str, Any]

Forme sérialisable de l'état pour un point de reprise, sans started_at.

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

Retour : dict[str, Any]. Dictionnaire de tous les champs sauf started_at.

Modèle LoopResult

Résultat de :meth:AgentLoop.run.

Champs :

Nom	Type	Requis	Description
status	str	oui	Statut final de l'exécution : completed, failed, budget_exhausted ou stopped.
output	Any	oui	Sortie de l'opération (transcription, références d'images...).
state	LoopState	oui	État sérialisable d'une exécution (enregistré dans les points de reprise).
reason	str | None	non	Raison de l'action. Inscrite dans le journal d'audit avec l'acteur et l'heure.

Attributs :

Nom	Type	Requis	Description
ok	bool	oui	True si status vaut completed.

Classe AgentLoop

Agents. Registre des agents du tenant et exécution côté serveur de leurs runs : étapes, budgets, points de reprise, heartbeats, sous-agents, messages d'agent à agent (A2A), sessions de conversation, planifications cron, déclencheurs sur événement et exécutions en sandbox.

Attributs :

Nom	Type	Requis	Description
agent_id		oui	Identifiant de l'agent surveillé par le coupe-circuit, ou None.
approval_for		oui	Motifs glob des outils qui exigent une approbation humaine.
approval_timeout		oui	Attente maximale d'une décision d'approbation, en secondes.
budget		oui	Budgets locaux (LoopBudget) appliqués par route.
bus		oui	Bus de messages lu par serve, ou None.
checkpoint_every		oui	Nombre d'étapes entre deux points de reprise ; 0 n'enregistre que le dernier.
client		oui	Client Enterprise AI utilisé pour les points de reprise, les approbations, le coupe-circuit, les sessions et l'usage, ou None pour fonctionner hors ligne.
context_budget		oui	ContextBudget utilisé par prepare_context, ou None.
final_verifier		oui	Fonction qui vérifie la réponse finale, ou None pour accepter toute réponse.
history_limit		oui	Nombre de derniers messages de session chargés comme historique ; 0 les charge tous.
kill_poll_every		oui	Nombre d'étapes entre deux interrogations du statut de l'agent ; 0 désactive l'interrogation.
last_runner	Any	oui	Dernier AgentRunner construit par runner, ou None.
model		oui	Identifiant du modèle, ou None.
model_call		oui	Fonction (messages, tools) -> completion appelée pendant la phase de planification.
on_event		oui	Fonction de rappel (kind, data) appelée à chaque événement de la boucle, ou None.
poll_interval		oui	Pause entre deux cycles de réception de serve, en secondes.
processed_runs	set[str]	oui	Identifiants des exécutions en attente déjà prises en charge par serve, afin qu'aucune ne soit lancée deux fois.
record_steps		oui	Si True, chaque phase est enregistrée comme étape d'exécution sur le serveur.
remote_tool		oui	Fonction (name, arguments) qui exécute les outils non locaux, ou None.
remote_tool_specs		oui	Entrées tools OpenAI des outils distants.
run_id		oui	Identifiant de l'exécution serveur, ou None.
runner_options		oui	Arguments nommés supplémentaires passés à chaque AgentRunner.
session_cursors	dict[str, str | None]	oui	Sessions surveillées avec l'identifiant du dernier message traité (None avant le premier).
session_id		oui	Session par défaut de la boucle, ou None.
stop_event		oui	Événement qui arrête la boucle lorsqu'il est activé (heartbeat ou agent tué).
tools	dict[str, LocalTool]	oui	Outils locaux par nom (un dictionnaire de LocalTool).
verifier		oui	Fonction qui vérifie chaque résultat d'outil, ou None pour accepter tout résultat.

Constructeur AgentLoop

AgentLoop(model_call: ModelCall | None = None, model: str | None = None, session_id: str | None = None, bus: Any = None, context_budget: Any = None, history_limit: int = 50, poll_interval: float = 2.0, watch_sessions: list[str] | None = None, runner_options: dict[str, Any] | None = None, tools: dict[str, LocalTool] | list[LocalTool] | None = None, remote_tool: Callable[[str, dict[str, Any]], Any] | None = None, remote_tool_specs: list[dict[str, Any]] | None = None, budget: LoopBudget | None = None, verifier: Verifier | None = None, final_verifier: Callable[[Any], bool | str] | None = None, approval_for: list[str] | None = None, client: Any = None, agent_id: str | None = None, run_id: str | None = None, checkpoint_every: int = 1, kill_poll_every: int = 1, record_steps: bool = True, stop_event: threading.Event | None = None, on_event: Callable[[str, dict[str, Any]], None] | None = None, approval_timeout: float = 3600.0) -> None

Configure la boucle : modèle, outils locaux et distants, budgets, vérificateurs, approbations et client utilisé pour les points de reprise, le coupe-circuit et les étapes d'exécution.

Nom	Type	Défaut	Requis	Description
model_call	ModelCall | None	None	non	Fonction (messages, tools) -> completion qui renvoie une complétion de style OpenAI ; une clé eai_cost facultative est ajoutée au coût.
model	str | None	None	non	Identifiant du modèle utilisé par l'exécuteur et le constructeur de contexte.
session_id	str | None	None	non	Session par défaut dont l'historique est chargé et à laquelle les réponses sont publiées.
bus	Any	None	non	Bus de messages lu par serve : les messages entrants reçoivent une réponse publiée en sortie ; None le désactive.
context_budget	Any	None	non	ContextBudget utilisé pour faire tenir le prompt système, l'historique et l'entrée dans prepare_context ; None conserve tous les messages.
history_limit	int	50	non	Nombre de derniers messages de session chargés comme historique ; 0 les charge tous. Par défaut 50.
poll_interval	float	2.0	non	Pause entre deux cycles de réception de serve, en secondes. Par défaut 2.0.
watch_sessions	list[str] | None	None	non	Sessions dont les nouveaux messages sont traités par serve, depuis le début.
runner_options	dict[str, Any] | None	None	non	Arguments nommés supplémentaires passés à chaque AgentRunner construit par runner.
tools	dict[str, LocalTool] | list[LocalTool] | None	None	non	Outils locaux, sous forme de liste de LocalTool ou de dictionnaire par nom.
remote_tool	Callable[[str, dict[str, Any]], Any] | None	None	non	Fonction (name, arguments) qui exécute un outil non local, par exemple via la Tool Gateway.
remote_tool_specs	list[dict[str, Any]] | None	None	non	Entrées tools OpenAI des outils distants, proposées au modèle à côté des outils locaux.
budget	LoopBudget | None	None	non	Budgets locaux (LoopBudget) ; par défaut 20 étapes et 3 reprises, rien d'autre n'est limité.
verifier	Verifier | None	None	non	Fonction (name, result) qui vérifie chaque résultat d'outil : True l'accepte, toute autre valeur est un motif d'échec et déclenche une reprise.
final_verifier	Callable[[Any], bool | str] | None	None	non	Fonction qui vérifie la réponse finale : True l'accepte, toute autre valeur est le motif de rejet renvoyé au modèle.
approval_for	list[str] | None	None	non	Motifs glob des outils qui exigent une approbation humaine, comparés à name et tool:<name> ; vide par défaut.
client	Any	None	non	Client parent.
agent_id	str | None	None	non	Identifiant de l'agent dont le statut est interrogé par le coupe-circuit et indiqué dans les événements d'usage.
run_id	str | None	None	non	Identifiant de l'exécution serveur utilisé pour les points de reprise, les étapes d'exécution et les événements d'usage.
checkpoint_every	int	1	non	Enregistre un point de reprise après la phase d'action toutes les N étapes ; 0 n'enregistre que le dernier. Par défaut 1.
kill_poll_every	int	1	non	Interroge le statut de l'agent pour le coupe-circuit toutes les N étapes ; 0 désactive l'interrogation. Par défaut 1.
record_steps	bool	True	non	Si True (par défaut) et qu'un identifiant d'exécution est défini, chaque phase est enregistrée comme étape d'exécution sur le serveur.
stop_event	threading.Event | None	None	non	Événement qui arrête la boucle lorsqu'il est activé (heartbeat) ; un nouveau threading.Event par défaut.
on_event	Callable[[str, dict[str, Any]], None] | None	None	non	Fonction de rappel (kind, data) appelée à chaque événement de la boucle (plan, tool, approval_requested, done).
approval_timeout	float	3600.0	non	Attente maximale d'une décision d'approbation, en secondes. Par défaut 3600.0.

AgentLoop.act

act(state: LoopState) -> LoopState

Exécute les appels d'outils en attente ; les échecs et les refus deviennent des messages d'outil.

Nom	Type	Défaut	Requis	Description
state	LoopState		oui	LoopState courant, dont les appels d'outils pending sont exécutés ; il est mis à jour sur place.

Retour : LoopState. Un LoopState : état sérialisable d'une exécution (enregistré dans les points de reprise).

AgentLoop.check_budget

check_budget(state: LoopState) -> str | None

Nom du budget épuisé, ou None.

Nom	Type	Défaut	Requis	Description
state	LoopState		oui	LoopState courant, comparé aux limites de budget.

Retour : str \| None. max_steps, max_tool_calls, max_output_tokens, max_cost ou max_duration, ou None si aucun budget n'est épuisé.

AgentLoop.check_kill_switch

check_kill_switch(state: LoopState) -> None

Lève :class:AgentStopped lorsque le heartbeat ou le statut de l'agent demande l'arrêt.

Nom	Type	Défaut	Requis	Description
state	LoopState		oui	LoopState courant ; son numéro d'étape détermine si le statut de l'agent est interrogé cette fois.

Retour : None.

Erreurs levées : AgentStopped.

AgentLoop.checkpoint

checkpoint(state: LoopState) -> Any

Envoie l'état à l'API des points de reprise du serveur (lorsqu'un identifiant d'exécution est connu).

Nom	Type	Défaut	Requis	Description
state	LoopState		oui	État à enregistrer, envoyé avec le libellé step-<n>.

Retour : Any. Réponse de l'API des points de reprise, ou None sans client ni identifiant d'exécution.

AgentLoop.history

history(session_id: str) -> list[dict[str, Any]]

Lister les messages d'une session. Messages dans l'ordre, paginés avec cursor. after (identifiant de message ou horodatage) permet à un runtime de ne récupérer que les nouveaux messages ; un identifiant inconnu ou un horodatage mal formé répond 400 invalid_request.

Route : /v1/sessions/{session_id}/messages (GET).

Nom	Type	Défaut	Requis	Description
session_id	str		oui	Identifiant (UUID) de la session.

Retour : list[dict[str, Any]]. Réponse JSON décodée de l'opération « Lister les messages d'une session ».

Erreurs levées : les erreurs typées du transport (Erreurs).

AgentLoop.needs_approval

needs_approval(name: str) -> bool

Indique si un appel d'outil exige une approbation humaine : l'outil local l'exige ou son nom correspond à approval_for.

Nom	Type	Défaut	Requis	Description
name	str		oui	Nom de l'outil, comparé sous les formes name et tool:<name>.

Retour : bool. True si l'appel doit d'abord être approuvé.

AgentLoop.plan

plan(state: LoopState) -> LoopState

Appelle le modèle ; enregistre les appels d'outils dans pending ou la réponse dans final.

Nom	Type	Défaut	Requis	Description
state	LoopState		oui	LoopState courant ; ses messages sont envoyés au modèle et il est mis à jour sur place.

Retour : LoopState. Un LoopState : état sérialisable d'une exécution (enregistré dans les points de reprise).

AgentLoop.poll_once

poll_once() -> list[TurnResult]

Lister les runs. Runs du tenant, du plus récent au plus ancien, paginés avec cursor. Filtres : agent_id (identifiant ou nom ; agent en est un alias), state, session_id, parent_run_id. Un état inconnu ou un UUID mal formé répond 400 invalid_request.

Route : /v1/runs (GET).

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

Retour : list[TurnResult]. Réponse JSON décodée de l'opération « Lister les runs ».

Erreurs levées : les erreurs typées du transport (Erreurs).

AgentLoop.prepare_context

prepare_context(input: Any, session_id: str | None = None, system: str | None = None) -> list[dict[str, Any]]

Prompt système, historique de session et nouvelle entrée, ajustés à context_budget s'il est défini.

Nom	Type	Défaut	Requis	Description
input	Any		oui	Nouvelle entrée de l'utilisateur ; une valeur non textuelle est sérialisée en JSON, None n'ajoute aucun message utilisateur.
session_id	str | None	None	non	Session dont l'historique est chargé ; None n'utilise aucun historique.
system	str | None	None	non	Prompt système placé en premier, ou None.

Retour : list[dict[str, Any]]. Liste de messages de conversation (role, content) prête pour le modèle.

AgentLoop.request_approval

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

Crée une approbation et attend la décision. True si elle est approuvée.

Nom	Type	Défaut	Requis	Description
name	str		oui	Nom de l'outil, envoyé comme ressource de l'approbation (action tools:invoke).
arguments	dict[str, Any]		oui	Arguments de l'appel d'outil, envoyés comme motif de l'approbation (JSON, 500 caractères au plus).

Retour : bool. True si la décision est approved ; lève ApprovalRequired sans client.

Erreurs levées : ApprovalRequired.

AgentLoop.resume

resume(run_id: str) -> TurnResult

Lister les points de reprise d'un run. Points de reprise du run dans l'ordre de séquence. Une seule page. 404 run_not_found.

Route : /v1/runs/{run_id}/checkpoints (GET).

Nom	Type	Défaut	Requis	Description
run_id	str		oui	Identifiant (UUID) du run.

Retour : TurnResult. Réponse JSON décodée de l'opération « Lister les points de reprise d'un run ».

Erreurs levées : ValueError, les erreurs typées du transport (Erreurs).

AgentLoop.route

route(state: LoopState) -> str

Phase suivante : plan, act, verify ou done (applique les budgets et les limites de reprise).

Nom	Type	Défaut	Requis	Description
state	LoopState		oui	LoopState courant ; ses champs status et last_error sont renseignés lorsque la boucle se termine.

Retour : str. Nom de la phase suivante : plan, act, verify ou done.

AgentLoop.run_legacy

run_legacy(task: Any = None, system: str | None = None, messages: list[dict[str, Any]] | None = None, state: LoopState | None = None, raise_on_budget: bool = False) -> LoopResult

Mène la boucle jusqu'à son terme. Reprend depuis state s'il est fourni (restauration d'un point de reprise).

Nom	Type	Défaut	Requis	Description
task	Any	None	non	Tâche confiée à l'agent sous forme de message utilisateur ; une valeur non textuelle est sérialisée en JSON.
system	str | None	None	non	Prompt système, ajouté en premier si les messages n'en contiennent pas.
messages	list[dict[str, Any]] | None	None	non	Messages de conversation précédents à partir desquels démarrer.
state	LoopState | None	None	non	État restauré depuis un point de reprise ; s'il est fourni, task, system et messages sont ignorés.
raise_on_budget	bool	False	non	Si True, un budget épuisé lève BudgetExhausted au lieu de renvoyer un résultat. Par défaut False.

Retour : LoopResult. Un LoopResult : résultat de :meth:AgentLoop.run.

Erreurs levées : BudgetExhausted.

AgentLoop.run_once

run_once(input: Any = None, session_id: str | None = None, run_id: str | None = None, system: str | None = None, state: dict[str, Any] | None = None) -> TurnResult

Exécute un tour Navin (:class:AgentRunner) et publie la réponse dans la session.

Nom	Type	Défaut	Requis	Description
input	Any	None	non	Nouvelle entrée utilisateur du tour ; ignorée si state est fourni.
session_id	str | None	None	non	Session du tour, utilisée pour l'historique et la publication de la réponse ; par défaut le session_id de la boucle.
run_id	str | None	None	non	Exécution serveur du tour ; par défaut le run_id de la boucle.
system	str | None	None	non	Prompt système du tour, ou None.
state	dict[str, Any] | None	None	non	État de l'exécuteur restauré depuis un point de reprise pour reprendre le tour.

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

AgentLoop.runner

runner(run_id: str | None = None, session_id: str | None = None) -> AgentRunner

Un :class:AgentRunner qui partage le modèle, les outils, le budget et l'événement d'arrêt de cette boucle.

Nom	Type	Défaut	Requis	Description
run_id	str | None	None	non	Exécution serveur de l'exécuteur ; par défaut le run_id de la boucle.
session_id	str | None	None	non	Session de l'exécuteur ; par défaut le session_id de la boucle.

Retour : AgentRunner. Un AgentRunner : exécute des tours d'agent via la passerelle de la plateforme avec outils, règles et gouvernance.

AgentLoop.serve

async serve(max_cycles: int | None = None) -> None

Sert jusqu'à :meth:shutdown : messages entrants du bus, exécutions en attente et nouveaux messages de session.

Nom	Type	Défaut	Requis	Description
max_cycles	int | None	None	non	S'arrête après ce nombre de cycles de réception ; None sert jusqu'à shutdown.

Retour : None.

AgentLoop.shutdown

shutdown() -> None

Demande à :meth:serve de s'arrêter après le tour en cours.

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

Retour : None.

AgentLoop.start_state

start_state(task: Any, system: str | None = None, messages: list[dict[str, Any]] | None = None) -> LoopState

Construit le LoopState initial : messages précédents, prompt système s'il n'y en a pas, puis la tâche comme message utilisateur.

Nom	Type	Défaut	Requis	Description
task	Any		oui	Tâche ajoutée comme message utilisateur ; une valeur non textuelle est sérialisée en JSON, None n'ajoute rien.
system	str | None	None	non	Prompt système, inséré en premier si les messages n'en contiennent pas.
messages	list[dict[str, Any]] | None	None	non	Messages de conversation précédents, copiés.

Retour : LoopState. Un LoopState : état sérialisable d'une exécution (enregistré dans les points de reprise).

AgentLoop.tool_specs

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

Liste tools OpenAI : outils locaux plus outils distants de la Tool Gateway.

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

Retour : list[dict[str, Any]]. Liste d'entrées tools OpenAI, outils locaux en premier.

AgentLoop.verify

verify(state: LoopState) -> LoopState

Vérifie la réponse finale ; une réponse rejetée est renvoyée au modèle (reprise).

Nom	Type	Défaut	Requis	Description
state	LoopState		oui	LoopState courant, dont la réponse final est vérifiée ; il est mis à jour sur place.

Retour : LoopState. Un LoopState : état sérialisable d'une exécution (enregistré dans les points de reprise).

AgentLoop.watch

watch(session_id: str, after: str | None = None) -> None

Traite les nouveaux messages de session_id dans :meth:serve.

Nom	Type	Défaut	Requis	Description
session_id	str		oui	Session à surveiller.
after	str | None	None	non	Identifiant du dernier message déjà vu ; None traite la session depuis le début.

Retour : None.