agent.ts

Source : sdks/typescript/packages/sdk/src/agent.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.

Alias de type PlanResult

Ce que renvoie plan : un appel d'outil (tool, input) ou la réponse finale (final), avec tokens et cost facultatifs.

Définition : { tool: string; input: unknown; tokens?: number; cost?: number } \| { final: unknown; tokens?: number; cost?: number }.

Interface VerifyResult

Résultat de verify pour une étape d'outil : ok et un retour facultatif.

Champs :

Nom	Type	Requis	Description
ok	boolean	oui	Indique si l'exercice a réussi.
feedback	string	non	Retour facultatif conservé dans l'historique pour le prochain appel de plan.

Interface LoopStep

Une étape d'outil de runAgentLoop : l'outil, son entrée, sa sortie ou son erreur et le résultat de la vérification.

Champs :

Nom	Type	Requis	Description
step	number	oui	Étape courante, texte libre (500 caractères au plus).
tool	string	oui	Nom de l'outil appelé.
input	unknown	oui	Valeur refusée.
output	unknown	non	Sortie de l'opération (transcription, références d'images...).
error	string	non	Message d'erreur lorsque l'appel de l'outil a échoué.
verified	boolean	oui	Vrai lorsque l'appel a réussi et que verify l'a accepté.
feedback	string	non	Retour de verify, ou le message d'erreur lorsque l'outil a échoué.

Interface LoopBudget

Limites de runAgentLoop sur les jetons, le coût et la durée.

Champs :

Nom	Type	Requis	Description
maxTokens	number	non	Nombre maximal de jetons de sortie ; s'il est fourni, c'est la sortie retenue pour le pire cas.
maxCost	number	non	Limite de coût, dans l'unité monétaire utilisée par les résultats de plan.
maxDurationMs	number	non	Durée maximale de la boucle en millisecondes.

Interface AgentLoopOptions

Options de runAgentLoop : les outils, les fonctions plan et verify, la limite d'étapes, le budget et l'arrêt d'urgence.

Champs :

Nom	Type	Requis	Description
tools	Tool<any	oui	Outils que ses agents externes peuvent invoquer (noms ou motifs comme crm.*).
plan	(history: LoopStep[], step: number) => Promise<PlanResult> | PlanResult	oui	Planification : choisit le prochain appel d'outil ou renvoie la réponse finale.
verify	(s: LoopStep) => Promise<VerifyResult> | VerifyResult	non	Vérification : contrôle chaque résultat d'outil (par défaut, accepte tout appel réussi).
maxSteps	number	non	Nombre maximal d'étapes (10 par défaut) ; l'atteindre lève agent_max_steps.
budget	LoopBudget	non	Limites de jetons, de coût et de durée fusionnées dans les limites du runner ; les dépasser lève agent_budget.
killSwitch	() => Promise<boolean> | boolean	non	Renvoie true quand l'agent doit s'arrêter (arrêt d'urgence). Vérifié avant chaque appel au modèle et à un outil.
onStep	(s: LoopStep) => Promise<void> | void	non	Appelée après chaque étape d'outil, par exemple pour envoyer un heartbeat en POST.
signal	AbortSignal	non	AbortSignal qui annule la boucle ; une annulation lève agent_aborted.
locale	Locale	non	Langue des messages d'erreur, en (par défaut) ou fr.
agentId	string	non	Identifiant de l'agent transmis au runner et cité dans le message de l'erreur agent_killed.

Interface AgentLoopResult

Résultat de runAgentLoop : la réponse finale, les étapes d'outil et la consommation (jetons, coût, durée en millisecondes).

Champs :

Nom	Type	Requis	Description
final	unknown	oui	Vrai si c'est la dernière étape du run. Faux par défaut.
steps	LoopStep[]	oui	Toutes les étapes d'outil exécutées par la boucle, dans l'ordre.
usage	{ tokens: number; cost: number; durationMs: number }	oui	Compteurs d'usage ajoutés à la consommation de budget, par exemple input_tokens, output_tokens.

Fonctions

runAgentLoop

async runAgentLoop(o: AgentLoopOptions): Promise<AgentLoopResult>

Boucle planifier / agir / vérifier avec une limite d'étapes, un budget et un arrêt d'urgence. Délègue à AgentRunner : plan joue le rôle du modèle, les règles de continuation sont désactivées.

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

Retour : Promise<AgentLoopResult>. Réponse finale, étapes d'outil et consommation ; lève AgentLoopError en cas de limite d'étapes, de budget, d'annulation ou d'arrêt d'urgence.

Erreurs levées : AgentLoopError.