agent/runner.ts

Source : sdks/typescript/packages/sdk/src/agent/runner.ts. Retour à l'index de la référence du SDK TypeScript.

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.

Interface ToolCall

Appel d'outil demandé par un modèle : identifiant, type function, nom et arguments.

Champs :

Nom	Type	Requis	Description
id	string	oui	Identifiant de l'appel.
type	"function"	oui	Type de l'appel, toujours function.
function	{ name: string; arguments: string }	oui	Fonction appelée : nom et arguments sous forme de chaîne JSON.
input	unknown	non	Valeur refusée.

Interface AgentMessage

Message de conversation d'un tour au format OpenAI : rôle, contenu, appels d'outils et identifiant d'appel d'outil.

Champs :

Nom	Type	Requis	Description
role	"system" | "user" | "assistant" | "tool"	oui	system, user, assistant ou tool.
content	string | null	oui	Texte du message ; null pour un message assistant qui ne fait qu'appeler des outils.
tool_calls	ToolCall[]	non	Appels d'outils demandés par un message assistant.
tool_call_id	string	non	Identifiant de l'appel d'outil auquel répond ce message tool.
name	string	non	Nom de l'outil, sur un message tool.

Interface ModelResponse

Réponse d'un appel au modèle : le message assistant, le motif de fin, les jetons, le coût et la réponse brute.

Champs :

Nom	Type	Requis	Description
message	AgentMessage	oui	Message d'état (2000 caractères au plus).
finishReason	string | null	oui	Motif de fin du modèle, par exemple stop, length ou tool_calls.
tokens	number	non	Jetons consommés par l'appel, ajoutés au budget du tour.
cost	number	non	Coût de l'appel, ajouté au budget du tour.
raw	unknown	non	Réponse brute de la passerelle.

Interface ModelRequest

Ce que le runner transmet à un appel au modèle : messages, déclarations d'outils et numéro d'étape.

Champs :

Nom	Type	Requis	Description
messages	AgentMessage[]	oui	Messages du tour jusqu'ici.
tools	Array<{ type: "function"; function: { name: string; description: string; parameters: Record<string, unknown> } }>	oui	Outils que ses agents externes peuvent invoquer (noms ou motifs comme crm.*).
step	number	oui	Étape courante, texte libre (500 caractères au plus).

Alias de type ModelCaller

Remplace l'appel à la passerelle (tests, routage personnalisé).

Définition : (req: ModelRequest) => Promise<ModelResponse> \| ModelResponse.

Interface RunnerLimits

Limites d'un tour d'AgentRunner : appels au modèle, appels d'outils, coût, jetons et durée.

Champs :

Nom	Type	Requis	Description
maxSteps	number	non	Appels au modèle par tour (50 par défaut).
maxToolCalls	number	non	Nombre maximal d'appels d'outils par tour ; l'atteindre arrête avec max_tool_calls.
maxCost	number	non	Limite de coût, dans l'unité monétaire indiquée par la passerelle.
maxTokens	number	non	Nombre maximal de jetons de sortie ; s'il est fourni, c'est la sortie retenue pour le pire cas.
maxDurationMs	number	non	Durée maximale du tour en millisecondes ; la dépasser arrête avec timeout.

Alias de type StopReason

Raison de la fin d'un tour : completed, stopped, aborted, waiting_approval, max_steps, max_tool_calls, budget, timeout ou no_progress.

Définition : \| "completed" \| "stopped" \| "aborted" \| "waiting_approval" \| "max_steps" \| "max_tool_calls" \| "budget" \| "timeout" \| "no_progress".

Interface RunnerStep

Une étape de modèle ou d'outil d'un tour, telle que transmise à onStep et rapportée au run.

Champs :

Nom	Type	Requis	Description
index	number	oui	Position de l'étape dans le tour, à partir de 1.
type	"model" | "tool"	oui	model ou tool.
name	string	oui	Nom de l'outil, ou nom du modèle pour une étape de modèle.
input	unknown	non	Valeur refusée.
output	unknown	non	Sortie de l'opération (transcription, références d'images...).
error	string	non	Message d'erreur d'une étape d'outil en échec.
status	"succeeded" | "failed" | "waiting_approval"	oui	succeeded, failed ou waiting_approval.
kind	ToolKind	non	Ce que fait l'outil, lu par les règles de continuation (exploration, verify_before_done).
tokens	number	non	Jetons consommés par une étape de modèle.
cost	number	non	Coût d'une étape de modèle.
durationMs	number	oui	Durée de l'étape en millisecondes.
toolCalls	number	non	Étape de modèle : nombre d'appels d'outils demandés.
finishReason	string | null	non	Motif de fin d'une étape de modèle.

Interface TurnResult

Résultat d'AgentRunner.runTurn.

Champs :

Nom	Type	Requis	Description
finalText	string	oui	Dernière réponse textuelle du modèle.
messages	AgentMessage[]	oui	Tous les messages du tour, y compris l'entrée, les relances et les résultats d'outils.
steps	RunnerStep[]	oui	Étapes de modèle et d'outil du tour, dans l'ordre.
stopReason	StopReason	oui	Raison de la fin du tour.
stopDetail	string	non	Cause lisible d'un tour non terminé (limite, motif du heartbeat).
nudges	Record<string	oui	Relances envoyées dans le tour, par code de règle.
usage	{ tokens: number; cost: number; durationMs: number; modelCalls: number; toolCalls: number }	oui	Compteurs d'usage ajoutés à la consommation de budget, par exemple input_tokens, output_tokens.
approval	Doc	non	Renseigné quand stopReason vaut waiting_approval.

Interface AgentRunnerOptions

Options d'AgentRunner : modèle ou callModel, outils, identifiants du run, limites, règles, heartbeat, arrêt d'urgence et compte rendu.

Champs :

Nom	Type	Requis	Description
client	EnterpriseAI	non	Client EnterpriseAI utilisé pour la passerelle, les outils, MCP et les comptes rendus du run.
model	string	non	Alias de modèle ou de route de la passerelle.
effort	string	non	Effort de raisonnement envoyé en reasoning_effort.
callModel	ModelCaller	non	Remplace l'appel à la passerelle (tests, routage personnalisé).
tools	Tool<any	non	Outils que ses agents externes peuvent invoquer (noms ou motifs comme crm.*).
remoteTools	RemoteToolSpec[]	non	Outils exécutés côté serveur par la Tool Gateway (POST /v1/tools/{name}/invoke).
mcpTools	McpToolSpec[]	non	Outils de serveurs MCP enregistrés, appelés via la passerelle MCP (tools/call).
agentId	string	non	Identifiant de l'agent envoyé en agent_id à la passerelle et à la Tool Gateway.
sessionId	string	non	Identifiant de session envoyé en session_id à la passerelle.
runId	string	non	Identifiant du run : envoyé en run_id et, avec un client, active les comptes rendus d'étapes et de points de reprise.
taskId	string	non	Identifiant de tâche envoyé en task_id à la passerelle.
dataClassification	string	non	Classification des données envoyée en data_classification avec les appels au modèle et aux outils distants.
limits	RunnerLimits	non	Limites d'étapes, d'appels d'outils, de coût, de jetons et de durée d'un tour.
rules	ContinuationRule[]	non	Règles d'une politique builtin.
deliveryRequired	boolean	non	Le flux exige l'exécution d'un outil avant la réponse (règle delivery).
auditMode	boolean	non	Mode audit : plafond d'exploration de 8 au lieu de 4.
heartbeat	HeartbeatHandle	non	Handle de heartbeat ; un battement est envoyé avant chaque appel au modèle et stopRequested est vérifié avant chaque appel.
shouldStop	() => Promise<boolean> | boolean	non	Arrêt d'urgence supplémentaire, vérifié avant chaque appel au modèle et à un outil.
signal	AbortSignal	non	AbortSignal transmis à chaque appel ; une annulation termine le tour avec aborted.
locale	Locale	non	Langue des messages produits par le runner, en (par défaut) ou fr.
reportSteps	boolean	non	POST /v1/runs/{id}/steps pour chaque appel (vrai par défaut quand client et runId sont fournis).
checkpoints	boolean	non	POST /v1/runs/{id}/checkpoints après les étapes d'outils et à l'arrêt (vrai par défaut quand client et runId sont fournis).
onStep	(s: RunnerStep) => Promise<void> | void	non	Appelée avec chaque étape de modèle et d'outil.
onError	(err: unknown) => void	non	Les erreurs de compte rendu (étapes, points de reprise) ne font jamais échouer le tour ; elles arrivent ici.

Classe AgentRunner

Le modèle puis les outils, répétés jusqu'à la réponse finale, puis les règles de continuation Navin.

Attributs :

Nom	Type	Requis	Description
options	AgentRunnerOptions	oui	Options transmises au constructeur.

Constructeur AgentRunner

new AgentRunner(options: AgentRunnerOptions)

Indexe les outils locaux, distants et MCP et prend defaultRules() quand aucune règle n'est fournie ; lève invalid_request sans client ni callModel.

Nom	Type	Défaut	Requis	Description
options	AgentRunnerOptions		oui	Options de l'appel (clé d'idempotence, traceparent, en-têtes, signal d'annulation).

AgentRunner.runTurn

async runTurn(input: AgentMessage[]): Promise<TurnResult>

Exécute un tour utilisateur jusqu'à la réponse finale ou un arrêt.

Nom	Type	Défaut	Requis	Description
input	AgentMessage[]		oui	Messages de la conversation jusqu'ici ; le dernier message user est lu par la règle de feu vert.

Retour : Promise<TurnResult>. Texte final, messages, étapes, motif d'arrêt, relances envoyées et consommation du tour.