Pilotes de navigateur et de bureau

Un pilote traduit les appels d’outils autorisés en actions dans un navigateur ou sur un bureau que vous contrôlez. Utilisez un pilote de navigateur si votre application peut fournir le texte des pages, les contrôles et la liste des onglets. Utilisez un pilote d’ordinateur si le modèle doit travailler à partir de captures d’écran et de coordonnées. Le SDK envoie les requêtes et distribue les appels. Votre application gère la session, les autorisations et la libération des ressources.

Configurez les contrôles communs

Commencez par l’exemple de navigateur en Python ou en Node. Il présente un pilote complet, une politique de confirmation et une exécution de l’API Responses avec un nombre limité de requêtes. Gardez la session ouverte jusqu’à la fin de l’exécution. Python fournit également les classes synchrones BrowserToolset et ResponsesToolRunner pour les pilotes synchrones.

Approuvez les actions et gérez la session

Créez les pilotes et les rappels d’approbation dans le code de confiance de votre application. Séparez la configuration exécutable des données de page non fiables et renvoyez ces données dans les champs de rapport déclarés par le pilote.

Toute méthode de navigateur sélectionnée qui modifie l’état ou lit des données de diagnostic exige confirm. Seule la valeur exacte true en Node ou True en Python approuve une action. navigate et new_tab exigent également urlPolicy (Node) ou url_policy (Python). Les deux rappels reçoivent un objet indépendant contenant member, les arguments validés dans arguments, l’état précédent dans state et call_id. Le rappel de la politique d’URL reçoit aussi l’URL demandée. Modifier cet objet ne permet pas de modifier l’action validée.

confirm approuve les arguments déjà fixés de l’action. Son champ state décrit une observation antérieure sans verrouiller le document ni le contrôle qui a le focus. Pendant que la personne décide, la page peut changer d’adresse ou le focus peut se déplacer. Si le consentement porte sur une page ou un contrôle précis, le pilote doit vérifier la cible d’origine au moment de l’exécution. Dans ce cas, désactivez key et refusez type si sa cible est nulle. Ces deux opérations utilisent le focus courant. Liez de la même manière les autres actions à leur cible lorsqu’elles dépendent de l’état courant du navigateur.

Pour demander l’approbation avant de lire une page privée, indiquez les méthodes de lecture dans confirmReads (Node) ou confirm_reads (Python). Le même rappel confirm s’exécute avant toute lecture de l’état ou du contenu par le pilote. Son contexte contient phase: "before_read". L’état y figure sous la forme state: null en Node ou vaut None en Python. Traitez ce cas sans lire les métadonnées de la page. En cas de refus, aucun contenu ni état de page n’est renvoyé. En l’absence de cette option, les lectures existantes conservent leur comportement. Les approbations obligatoires restent applicables aux actions.

Pour les appels à l’ordinateur, approuvez toutes les vérifications de sécurité en attente avant que l’utilitaire exécute la moindre action. approveSafetyChecks en Node et approve_safety_checks en Python doivent renvoyer exactement le booléen vrai. Si le rappel manque ou refuse l’approbation, l’exécution s’arrête. Le rappel facultatif beforeAction ou before_action vérifie chaque action juste avant son exécution, y compris la capture d’écran finale. Si vous le fournissez, il doit lui aussi donner son approbation explicitement. Ni un choix du modèle ni un message de fin ne peuvent valoir approbation. Consultez les consignes de sécurité pour l’utilisation de l’ordinateur.

Node passe { signal } comme dernier argument aux deux rappels d’approbation des actions sur l’ordinateur. Python fournit l’argument nommé facultatif cancelled si le rappel l’accepte. Les rappels existants qui acceptent moins d’arguments restent pris en charge. Utilisez ce contexte pour fermer une demande d’approbation en attente à l’arrêt de l’exécution. L’utilitaire attend que le rappel se termine avant de libérer la session.

L’approbation d’une action sur l’ordinateur porte sur ses arguments déjà fixés. Elle ne fige ni l’écran ni le focus pendant que la personne décide. Si le consentement doit s’appliquer à une cible particulière, le pilote doit lier l’action à cette cible ou la refuser après un changement d’état. Exécutez les actions sur l’ordinateur dans un environnement isolé dont l’accès réseau est limité.

Restreignez les URL

Activez navigate ou new_tab uniquement si la tâche l’exige. Fournissez à la fois confirm et urlPolicy en Node, ou confirm et url_policy en Python. Le rappel de vérification de l’URL reçoit (context, url), avec un contexte d’exécution facultatif en Node ou l’argument nommé cancelled en Python. Il doit renvoyer exactement le booléen vrai pour que le SDK passe à confirm. L’ouverture d’un onglet vide avec une URL nulle exige toujours une confirmation, mais aucune URL n’est à vérifier.

Analysez l’URL demandée. Comparez son protocole, son nom d’hôte et son port aux destinations autorisées pour la tâche. Ne vous fiez pas au préfixe de la chaîne. https://example.com.evil.test ne doit pas être accepté comme https://example.com. Un pilote de navigateur sans fonction de navigation n’a pas besoin de rappel de vérification de l’URL. L’exemple de navigateur laisse ces méthodes désactivées.

Appliquez aussi une politique réseau dans le navigateur ou l’environnement. Le rappel vérifie la navigation demandée, mais ne peut pas restreindre les redirections, les fenêtres contextuelles, les scripts de page ni les ressources intégrées. Conservez une seule session isolée d’une requête à l’autre et fermez les ressources créées par votre application. Laissez les propriétaires des ressources empruntées les gérer.

Examinez la consommation et les durées

Avec ResponsesToolRunner, passez onDiagnostic en Node ou on_diagnostic en Python à run. Pour chaque requête Responses terminée, le rappel reçoit un enregistrement contenant api: "responses", stage: "request", reason: "completed" et usage. Les données de consommation comprennent input_tokens, output_tokens et total_tokens lorsque l’API les fournit. Sinon, la valeur est null en Node ou None en Python. Pour mesurer la consommation de l’exécution, additionnez séparément les valeurs de chaque champ de tokens pour toutes les requêtes terminées. Si les données manquent pour une requête, les totaux sont incomplets.

ComputerToolset.run ne communique pas la consommation des requêtes via son rappel de diagnostic. La réponse renvoyée peut contenir la consommation de la dernière requête uniquement. Utilisez ResponsesToolRunner avec ComputerToolset pour obtenir la consommation de chaque requête.

Les enregistrements de diagnostic indiquent aussi l’API, l’étape, le motif, l’identifiant de l’appel, le membre appelé et la durée mesurée. Ils ne contiennent ni erreur brute, ni texte de page, ni arguments, ni image. Une défaillance de l’observateur ne peut ni approuver une action ni modifier son résultat. Excluez des journaux publics les identifiants d’appel et les noms des membres si votre application y place des données privées.

Utilisez un observateur synchrone. L’exécuteur n’attend pas la fin du traitement des diagnostics. Planifiez tout enregistrement asynchrone dans votre application.

En exécution anticipée, les durées des étapes peuvent se chevaucher, car le temps de réception du flux peut inclure celui d’une action. Ne les additionnez pas pour calculer la durée totale de l’exécution.

Fermez l’utilitaire et annulez les opérations

Un utilitaire refuse les appels qui se chevauchent en signalant qu’il est occupé. Un exécuteur refuse également une deuxième exécution simultanée sur la même instance. Confiez chaque session de navigateur ou de bureau à un seul propriétaire.

Appelez la méthode close() de l’utilitaire pour refuser toute nouvelle opération. Son status vaut closed lorsqu’il ne reste aucun appel actif, ou draining lorsqu’un appel antérieur peut encore produire des effets. Si l’état vaut draining, attendez la fin de l’appel d’exécution initial avant de fermer le pilote ou de transférer la session à un autre propriétaire. L’utilitaire ne ferme ni le navigateur ni le bureau. Un appel à close() depuis un rappel du pilote n’attend pas la fin de ce même rappel.

Les méthodes de pilote et les fonctions ordinaires qui prennent en charge l’annulation coopérative en Node peuvent accepter en deuxième argument un contexte contenant signal. Les méthodes Python peuvent accepter l’argument nommé cancelled. Vérifiez si une annulation a été demandée pendant les opérations longues, notamment la navigation et les captures d’écran. Les rappels existants à un seul argument restent valides, mais le SDK ne peut ni les forcer à s’arrêter ni annuler un effet déjà produit.

Contrat du pilote de navigateur

Implémentez state() et uniquement les opérations que vous souhaitez exposer. En Node, les méthodes peuvent renvoyer une valeur ou une promesse. Python fournit des classes distinctes pour les pilotes synchrones et asynchrones. Chaque opération reçoit ses arguments validés dans un seul objet ou dictionnaire. Pour les identifiants d’onglet et les cibles qui acceptent l’absence de valeur, indiquez explicitement null en Node ou None en Python.

Python rejette les incompatibilités détectables entre modes synchrone et asynchrone à la création de l’utilitaire. Utilisez des méthodes async def avec AsyncBrowserToolset. Si vous encapsulez les méthodes, préservez les métadonnées des décorateurs ou les annotations de type de retour. Les fonctions d’encapsulation opaques sont vérifiées lors de l’appel. Des protocoles facultatifs comme BrowserReadDriver et AsyncBrowserReadDriver permettent de typer un pilote partiel sans implémenter toutes les opérations. Node exporte BrowserArguments<Member> et BrowserResult<Member> pour les entrées et sorties correspondantes.

state() renvoie tabs, un tableau d’objets contenant id, title, url et active. Utilisez des identifiants stables et marquez comme actif l’onglet qui l’est réellement. Excluez des titres et des URL les données d’authentification et les informations privées. Le SDK renvoie l’état courant après les opérations ordinaires, même en cas d’échec. Si une lecture protégée est refusée, le SDK renvoie un refus prédéfini sans lire ni exposer l’état. Si une lecture d’état obligatoire échoue, l’exécution s’arrête. En Node, les fonctions de lecture d’état reçoivent { signal }. En Python, elles peuvent accepter l’argument nommé cancelled. Utilisez ce contexte pour interrompre les lectures d’état en attente lorsque l’appelant arrête l’exécution. Les fonctions de lecture existantes sans argument restent prises en charge.

L’état des onglets indique les origines HTTP et HTTPS, comme https://example.com:8443, sans données d’authentification, chemin, chaîne de requête ni fragment. L’ancien format d’état, sans métadonnées d’observation, conserve about:blank et ne renvoie que le schéma pour les autres URL, par exemple data: ou file:. Sa limite de 2 048 octets en UTF-8 s’applique à la valeur renvoyée. Un long chemin de page n’empêche donc pas la lecture de l’état. Avec les métadonnées d’observation V1, les titres sont tronqués à 1 024 octets en UTF-8 sans couper de caractère, et title_truncated est défini si nécessaire. Appliquez toujours les règles de confidentialité de votre application aux titres et au contenu des pages.

Sélectionnez les méthodes

Par défaut, le SDK expose les 18 méthodes suivantes lorsqu’elles sont implémentées et déduit list_tabs de state(). N’implémentez pas list_tabs. Une liste members permet de limiter les méthodes exposées ou d’activer explicitement les méthodes de lecture ciblée et de pointage ou les méthodes de diagnostic, de script et de transfert de fichiers. Chaque nom doit être unique et correspondre à un membre prédéfini implémenté par le pilote. Seule list_tabs ne nécessite aucune méthode en plus de state(). Une liste vide n’expose aucune méthode. Le SDK copie la sélection à la construction, conserve son propre ordre pour les outils et refuse les appels désactivés avant de lire l’état ou de demander le consentement.

Pour ajouter une méthode facultative tout en conservant les méthodes par défaut implémentées, utilisez additionalMembers en Node ou additional_members en Python. Ne combinez pas cette option avec members. Le pilote doit implémenter chaque méthode que vous demandez à ajouter. BROWSER_MEMBERS et DEFAULT_BROWSER_MEMBERS répertorient les noms prédéfinis sans inspecter le pilote.

Désactiver list_tabs ne masque pas l’état renvoyé par les autres opérations réussies. En Python et en Node, members filtre les méthodes de l’utilitaire de navigateur. Les noms des fonctions ordinaires peuvent commencer par browser_, mais ne doivent correspondre à aucun outil de navigateur activé.

Sauf pour switch_tab et close_tab, l’argument tab_id du tableau peut être nul. La direction peut être up, down, left ou right. En Node, BrowserArguments<Member> décrit chaque objet d’arguments. Python expose des types d’entrée nommés tels que TabInput, ReadPageInput et ClickInput.

Pour read_page, find et get_page_text, renvoyez null ou aucune valeur en Node, ou None en Python, pour fournir uniquement l’état actualisé du navigateur. Renvoyez une chaîne vide si la lecture se termine sans trouver de texte.

En Node, chaque opération du tableau, sauf list_tabs, reçoit { signal } en deuxième argument. list_tabs utilise la fonction de lecture d’état décrite plus haut. Python passe cancelled comme argument nommé si la méthode l’accepte. Utilisez ce contexte pour interrompre les opérations en attente, notamment la navigation et la saisie. Les méthodes existantes à un seul argument restent prises en charge.

Pour wait_for, utilisez un texte non vide d’au plus 256 octets en UTF-8 après normalisation des espaces. Le délai doit être compris entre 1 et 30 000 millisecondes. Après scroll_to, relisez la page courante avant d’agir sur un contrôle.

Renvoyez des lectures structurées

read_page, find et get_page_text peuvent renvoyer un résultat BrowserReadV1 contenant version: 1, le texte visible dans text, un tableau elements et un tableau omitted. Chaque élément possède une référence ref unique, un libellé label non vide et l’un des sept rôles suivants : button, textbox, combobox, checkbox, radio, slider ou listbox.

Ne renvoyez la valeur value d’un champ ou ses options (paires label et value) que si votre application autorise le modèle à les voir. Une case à cocher ou un bouton radio peut indiquer son état avec le booléen checked. Les options d’une listbox peuvent indiquer leur sélection avec le booléen selected. Le SDK omet ces champs pour les autres rôles. Node omet les champs facultatifs définis à undefined et refuse les valeurs null pour ces champs. get_page_text doit renvoyer un tableau elements vide. Le SDK ne convertit pas une chaîne ordinaire en lecture structurée.

Le SDK ne limite ni le nombre d’éléments ou d’options, ni la taille du texte de la page, ni celle du rapport complet. Les références et les libellés sont limités à 256 octets, les valeurs à 512 octets. Utilisez des valeurs scalaires Unicode valides. Les pilotes peuvent signaler une lecture partielle avec des codes omitted sans doublons : report_limit, text_limit, target_limit, work_limit, frame_limit, unsupported_root, unsupported_control, remote_action, private, value ou name_limit.

Le pilote détermine la visibilité des éléments, protège la confidentialité des champs et vérifie la validité des références. Après l’approbation et avant d’agir, vérifiez de nouveau que la référence correspond à la page courante. Le libellé d’un contrôle ne donne pas l’autorisation de lire sa valeur. Limiter la taille du contenu d’une page ne suffit pas à le rendre sûr.

Renvoyez des images du navigateur

screenshot et zoom renvoient une image native input_image contenant au moins un champ image_url ou file_id non vide. Les deux champs source peuvent être présents. Chaque source non nulle doit être une chaîne non vide. Les champs pris en charge sont type, image_url, file_id, detail et prompt_cache_breakpoint. Un point d’arrêt de cache doit valoir { mode: "explicit" }. Une valeur nulle est également acceptée lorsque le type de contenu natif le permet. Le SDK valide et copie ces champs avant de renvoyer l’image. Les deux méthodes Node renvoient un ResponseInputImageContent, dont le champ detail peut être absent ou nul. Si vous le renseignez, utilisez auto, low, high ou original.

Pour zoom, region prend la forme [left, top, right, bottom]. Les coordonnées doivent être des entiers de la plage sûre, positifs ou nuls, et délimiter une largeur et une hauteur strictement positives. Le pilote se charge du recadrage et vérifie les limites. Toutes les coordonnées ultérieures restent relatives à l’ensemble de la zone visible.

Activez les méthodes de lecture ciblée et de pointage

Ces six méthodes de navigateur sont désactivées par défaut, même si le pilote les implémente. Sélectionnez-les avec members ou ajoutez-les avec additionalMembers en Node ou additional_members en Python. Les 18 méthodes par défaut conservent leurs noms, arguments et types de résultat. Si vous utilisez members, incluez les méthodes par défaut dont vous avez encore besoin, comme screenshot ou read_page.

Node utilise BrowserArguments<Member>. Python exporte ReadPageScopedInput, ClickAtInput, DragPathInput, HoldKeysInput, HoverAtInput et SetCheckedInput. Tous les champs sont obligatoires. Pour l’onglet actif, tab_id peut valoir null ou None. Les champs inconnus sont refusés, y compris les champs supplémentaires dans un point du trajet. Les nombres doivent être des entiers finis représentables exactement dans la plage sûre. Python refuse True et False lorsqu’un nombre est exigé.

click_at accepte des coordonnées x et y positives ou nulles, un button valant left, right ou middle et un click_count égal à 1, 2 ou 3. drag_path accepte de 2 à 100 points de forme exacte {x, y} dont les coordonnées sont positives ou nulles. Ces deux méthodes utilisent des pixels CSS relatifs à l’ensemble de la zone visible de la page, même après un zoom. Le pilote doit vérifier les limites actuelles. Leurs champs keys contiennent une liste sans doublons de touches de modification parmi Control, Alt, Meta et Shift. La liste peut être vide.

hover_at déplace le pointeur aux coordonnées CSS courantes sans maintenir de bouton enfoncé. set_checked place une case à cocher dans l’état booléen demandé. Lui attribuer deux fois la valeur vraie doit la laisser cochée. Même si l’état ne change pas, l’opération doit utiliser la cible d’origine encore présente et obtenir confirmation. Elle doit refuser tout contrôle périmé ou remplacé.

hold_keys accepte de 1 à 8 noms de touches distincts et non vides, composés de valeurs scalaires Unicode valides et limités chacun à 64 octets en UTF-8. duration_ms doit être compris entre 1 et 3 000. Les méthodes qui modifient l’état exigent que confirm renvoie exactement le booléen vrai. Les méthodes coopératives reçoivent le contexte d’annulation propre à l’appel. Node passe { signal } en deuxième argument. Python passe l’argument nommé cancelled si la méthode l’accepte. Les méthodes existantes à un seul argument restent valides.

Lisez le contenu d’une section

Avec read_page_scoped, une valeur root nulle permet de découvrir les sections visibles. Une racine non nulle doit être une référence de section émise par le pilote, et non un sélecteur. Elle doit être non vide, contenir de l’Unicode valide et occuper au plus 256 octets en UTF-8. Définissez depth entre 1 et 32 et filter à all ou interactive. La profondeur mesure le parcours du DOM à partir de cette racine, indépendamment des limites applicables aux cadres et au DOM fantôme.

Renvoyez un BrowserScopedReadV1, qui ajoute scopes: [{ref, label}] au résultat de lecture existant. Les références et les libellés doivent être non vides, contenir de l’Unicode valide et occuper au plus 256 octets en UTF-8. Chaque référence de section doit être unique et distincte de toute référence d’élément. Cette méthode refuse les chaînes et les résultats nuls. Le SDK copie les champs connus avant de demander l’état final.

Utilisez les références de section uniquement pour sélectionner une nouvelle racine de lecture. Les opérations qui modifient des éléments doivent les refuser. Invalidez ensemble les références de section et d’élément lorsque leur onglet, leur document, leur génération ou leur visibilité change. Conservez les règles de confidentialité des champs et les limites existantes de travail total et de lecture.

Activez les diagnostics, les scripts et les transferts de fichiers

Ces quatre méthodes sont elles aussi désactivées par défaut. Sélectionnez chacune dans members ou ajoutez-la avec additionalMembers ou additional_members, puis fournissez confirm, y compris pour les lectures de diagnostic. Le seul fait de les implémenter dans le pilote ne les expose pas au modèle.

Pour read_diagnostics, choisissez console ou network comme source et une limite comprise entre 1 et 100. Renvoyez une lecture structurée avec un tableau elements vide. En Node, utilisez le type de résultat BrowserTextReadV1. Le pilote doit filtrer les données privées et limiter la taille de son historique. Ne renvoyez ni en-têtes bruts, ni cookies, ni données d’authentification, ni messages de console non filtrés.

run_script accepte du code source non vide contenant de l’Unicode valide et un délai compris entre 1 et 30 000 millisecondes. Le SDK conserve l’intégralité du code source. Renvoyez du texte contenant de l’Unicode valide. Une chaîne vide est valide, mais un résultat nul est refusé. Le SDK conserve les résultats volumineux. Les scripts s’exécutent avec les privilèges de la page. Utilisez une nouvelle session sans données d’authentification, restreignez son accès réseau et mettez-la hors service si l’état de l’exécution devient incertain. Arrêter l’attente côté client ne prouve pas que le script de la page s’est arrêté.

Les méthodes de transfert de fichiers acceptent uniquement un grant_id émis par l’appelant, non vide, contenant de l’Unicode valide et limité à 256 octets en UTF-8. Cet identifiant d’autorisation désigne un seul fichier approuvé dans le cadre de la tâche. Ce n’est ni un chemin ni une URL. Le propriétaire du fichier doit obtenir une approbation distincte pour ce fichier. Il doit vérifier de nouveau que l’autorisation n’a pas expiré et que le fichier lui appartient, faire respecter les limites de taille et n’accepter qu’une seule utilisation de l’autorisation. La confirmation du navigateur ne remplace pas cette approbation du fichier.

Renvoyez exactement version, status, effect et cleanup. Définissez version à 1. cleanup vaut not_started, pending ou completed. Les combinaisons valides d’état et d’effet sont les suivantes.

Le SDK copie et valide ce résultat avant de demander l’état final du navigateur. Seul completed attribue la valeur vraie au champ ok de la sortie de l’outil. Dans les autres cas, le résultat structuré est conservé avec ok à faux. L’exécuteur ignore alors les appels de navigateur dépendants dans cette réponse. Vérifiez l’état réel du fichier et de l’application avant de réessayer un transfert dont l’issue est inconnue. Le résultat d’une opération sur un fichier ne prouve pas qu’un envoi de formulaire ou une opération métier ultérieurs ont réussi.

run_script, upload_file et download_file reçoivent un contexte d’annulation propre à chaque appel. Node passe { signal } en deuxième argument et Python passe l’argument nommé cancelled. Python exporte ReadDiagnosticsInput, RunScriptInput et BrowserFileInput.

Contrat du pilote d’ordinateur

Un pilote d’ordinateur reçoit les actions natives sur l’ordinateur et renvoie des captures d’écran. Il doit implémenter les méthodes ci-dessous. En Node, importez ComputerDriver depuis openai. En Python, importez ComputerDriver ou AsyncComputerDriver depuis openai. Importez également le ComputerToolset correspondant ou, en Python, AsyncComputerToolset, depuis openai.

Les méthodes d’action reçoivent l’objet d’action sur l’ordinateur déjà généré, avec ses champs en snake_case, et ne renvoient aucune valeur. Elles doivent lever une erreur si elles ne peuvent pas exécuter l’action. N’ignorez pas silencieusement une entrée non prise en charge. Node accepte des résultats synchrones ou des promesses. En Python, attendez la fin des méthodes asynchrones.

En Python, utilisez des méthodes synchrones avec ComputerToolset et des méthodes async def avec AsyncComputerToolset. L’utilitaire refuse les incompatibilités détectables à sa création. Préservez les métadonnées des décorateurs ou les annotations de type de retour lorsque vous encapsulez des méthodes. Les fonctions d’encapsulation opaques sont vérifiées à l’appel. Leur propre code peut donc s’exécuter avant que l’utilitaire détecte une incompatibilité.

En Node, utilisez ComputerCallInput pour les appels passés à ComputerToolset.execute(). Ce type accepte les appels natifs et les appels au format moderne dont le tableau actions est présent et le champ pending_safety_checks absent. Lorsque ce champ est omis conformément au contrat, les rappels d’approbation reçoivent une copie indépendante de l’appel avec une liste de vérifications vide. L’appel rejoué conserve ses champs d’origine.

screenshot() renvoie un computer_screenshot avec une image_url (qui peut être une URL de données) ou un file_id. Les utilitaires d’ordinateur exigent au moins une source d’image et acceptent les deux champs source. L’utilitaire ne lit pas les fichiers locaux. Il exécute les actions une seule fois, dans l’ordre, puis prend la capture d’écran finale. Il ne retente pas les actions du pilote.

Pour une boucle Responses qui utilise uniquement l’ordinateur, utilisez ComputerToolset.run ou, en Python, AsyncComputerToolset.run. Choisissez un modèle accessible à votre projet qui prend en charge l’outil d’utilisation de l’ordinateur. Pour une exécution mixte, passez l’utilitaire d’ordinateur à l’exécuteur Responses via l’option computer. En Node, fournissez les rappels de l’ordinateur dans l’option d’exécution computerOptions. En Python, passez directement approve_safety_checks et before_action comme arguments nommés de l’exécution. L’exemple de navigateur contrôle uniquement un navigateur. Il n’implémente ni ne vérifie de bureau natif.

L’utilitaire d’ordinateur et ResponsesToolRunner prennent tous deux en charge le compactage Responses via context_management. Ils vérifient les champs obligatoires des éléments et rejouent le contenu chiffré tel quel. Pour ResponsesToolRunner, choisissez cette option native ou l’option locale contextBudget ou context_budget. Ne les combinez pas.

Exécutez une tâche à partir de captures d’écran

La section Exécutez votre première tâche propose un exemple complet en Python ou en Node. Il utilise l’outil d’utilisation de l’ordinateur de l’API Responses pour afficher les modalités de retrait dans un navigateur local.

Utilisez un bureau isolé

Pour contrôler le bureau d’un système d’exploitation, consultez l’exemple complet en Python ou en Node. Les deux exemples utilisent un système Linux invité isolé. Sur les Mac à puce Apple, le système invité s’exécute dans une machine virtuelle. Sur Linux x86-64, il s’exécute dans Docker. Chaque exemple comprend un exercice local sans clé API. La tâche en conditions réelles vérifie à la fois les données enregistrées dans le navigateur et le fichier sauvegardé. Pour votre propre environnement, partez de la procédure Docker et adaptez le contrat de pilote décrit plus haut.

Combinez les actions du navigateur avec d’autres outils

L’exécuteur Responses peut combiner les utilitaires de navigateur et d’ordinateur avec des fonctions ordinaires, la recherche web, la recherche de fichiers, l’interpréteur de code, la génération d’images et des outils MCP distants. Les résultats des outils côté serveur conservent leur contenu natif et leurs identifiants de conteneur lorsque la requête suivante rejoue la réponse. Tout résultat côté serveur en échec, incomplet ou encore en cours arrête le tour avant les actions locales.

Lorsqu’une exécution déclare des outils côté serveur, les appels locaux attendent la réponse complète, même si eager est activé. Avant d’agir en toute sécurité, l’exécuteur doit examiner les résultats côté serveur et les demandes d’approbation qui arrivent ensuite.

Une fois le tour terminé, supplyOutputs en Node ou supply_outputs en Python permet de remplacer le résultat d’une fonction ordinaire dont l’appel n’a pas été tenté, si la fonction a été enregistrée avec cette possibilité. Cela fonctionne aussi sans politique explicite d’exécution anticipée. Un résultat de remplacement ne peut pas répondre à un appel de navigateur, à un appel à l’ordinateur ni à une demande d’approbation MCP.

Cet exécuteur a besoin de réponses stockées pour poursuivre après une génération d’images. Il refuse store: false en Node ou store=False en Python si vous déclarez image_generation. Activez le stockage si cela convient, ou utilisez client.responses.create pour une seule requête sans état. L’exécuteur n’active jamais le stockage à votre place.

Réutilisez les outils de fonction typés pour éviter de dupliquer leur validation. En Node, encapsulez un zodResponsesFunction ou un standardResponsesFunction avec runnerFunction de openai/helpers/responses-tool-runner. L’outil doit inclure son rappel. En Python, utilisez RegisteredFunction.from_tool ou AsyncRegisteredFunction.from_tool avec un pydantic_responses_function_tool existant et un exécuteur typé fourni explicitement. Des arguments invalides arrêtent le traitement avant l’appel à cet exécuteur. Une sortie de rappel invalide arrête l’exécution sans répéter l’effet produit. Les fonctions enregistrées directement avec RunnerFunction et RegisteredFunction conservent leur comportement actuel pour les arguments.

Pour MCP, fournissez approveMcp en Node ou approve_mcp en Python. Le rappel reçoit une copie indépendante de la demande d’approbation réelle et renvoie vrai ou faux. L’exécuteur associe la réponse à l’identifiant de cette demande et au serveur déclaré. Il ne peut ni inventer une approbation ni interpréter un message final comme un consentement.

Les requêtes qui déclarent des outils MCP désactivent les nouvelles tentatives automatiques du SDK, avec ou sans journal d’exécution. Si une requête échoue, vérifiez ce que le serveur MCP a fait avant de démarrer une autre exécution.

Gérez les échecs

Pour un problème récupérable, comme une référence périmée, levez BrowserError uniquement avec un texte que vous pouvez communiquer au modèle en toute sécurité. Les autres erreurs levées par une opération de navigateur produisent un message d’échec générique. En cas d’échec de ce type, l’exécuteur fournit une sortie pour chaque appel de navigateur, ignore les opérations de navigateur restantes dans la réponse et laisse le modèle choisir de nouveau au tour suivant. Un résultat renvoyé invalide ou un état invalide arrête l’exécution. L’impossibilité de fournir l’état, l’échec d’une fonction ordinaire ou l’absence d’approbation des vérifications natives de l’ordinateur l’arrêtent également.

Définissez maxSteps ou max_steps pour limiter le nombre de requêtes API. La valeur par défaut est 20. La dernière requête autorisée ne peut déclencher aucun nouvel effet. Une nouvelle tentative HTTP du SDK ne répète pas une action du pilote. Utilisez signal en Node ou cancelled en Python pour arrêter l’exécution entre deux opérations. Il n’est pas toujours possible d’annuler les effets d’un appel de pilote en cours.

ResponsesToolRunner conserve tool_choice dans chaque requête. Un choix qui impose systématiquement un outil local empêche l’exécution de se terminer. L’exécuteur le refuse donc avant toute opération. Utilisez auto pour une boucle ou responses.create pour une seule requête imposant un outil. Les choix obligatoires qui autorisent aussi un outil côté serveur déclaré restent valides.

Diagnostiquez une exécution

Corrigez les clics mal positionnés

Prenez une nouvelle capture d’écran et vérifiez qu’elle montre la fenêtre voulue. Utilisez le même repère pour la capture et l’action. Si vous envoyez une capture de 800 × 600 pixels pour un écran de 1 600 × 1 200 pixels, multipliez par deux les deux coordonnées renvoyées avant de cliquer. Si le pilote d’ordinateur envoie une capture recadrée, ajoutez le décalage du recadrage après la mise à l’échelle. Les méthodes de pointage du pilote de navigateur utilisent les pixels CSS de l’ensemble de la zone visible de la page, même après un zoom. Ne les confondez pas avec les pixels de l’écran.

La taille des captures d’écran influe sur le nombre de tokens d’entrée et sur le coût. Consultez la section Capture d’écran pour connaître les dimensions des images et les limites des modèles.

Traitez les réponses en flux et reprenez une exécution

Par défaut, les exécutions Responses ne traitent pas les réponses en flux. Avec stream et onEvent (Node) ou on_event (Python), l’exécuteur fournit des copies indépendantes des événements du flux et attend la fin de la réponse avant d’agir. Avec eager, il peut exécuter par anticipation les éléments de sortie terminés, dans l’ordre. Il n’exécute jamais les fragments d’arguments reçus progressivement.

Activez l’exécution anticipée uniquement si un élément terminé peut être exécuté en toute sécurité avant la validation de la réponse complète. Si un événement ultérieur modifie ou supprime cet élément, l’exécuteur s’arrête et conserve la trace de son exécution. Il ne peut pas annuler l’action. Si toutes les actions doivent attendre la validation de la réponse complète, laissez l’exécution anticipée désactivée ou utilisez une politique d’exécution anticipée vide.

Si les éléments terminés arrivent dans le désordre ou si leurs indices ne sont pas consécutifs, l’exécuteur attend la réponse complète avant d’exécuter cette partie de la séquence. Les effets déjà produits restent consignés si le flux échoue.

earlyExecution ou early_execution permet de restreindre l’exécution anticipée aux fonctions dont vous sélectionnez les noms tels qu’ils sont transmis dans le protocole, et de contrôler séparément la distribution des actions natives sur l’ordinateur avec un booléen. Un objet vide diffère tous les outils locaux. Si vous omettez l’option, l’exécution anticipée s’applique normalement à tous. Dès qu’un outil est différé, tous les suivants le sont aussi pour préserver leur ordre. Avec iterate(), examinez le tour terminé avant de passer au suivant. Si vous fermez l’itérateur à ce stade, aucun outil différé ne s’exécute. Ces options modifient le moment d’exécution, sans changer les règles d’approbation.

Pour un appel terminé donné, beforeEarlyCall ou before_early_call peut renvoyer defer avant sa distribution. Ce rappel ne peut pas anticiper un appel absent de la liste des fonctions autorisées à s’exécuter par anticipation. Marquez une fonction ordinaire independent: true uniquement si son exécution ne dépend d’aucune autre action. Sans journal d’exécution, les fonctions indépendantes peuvent s’exécuter pendant la réception du flux. Les exécutions persistantes, les actions de navigateur et les actions sur l’ordinateur respectent toujours leur ordre. Toute opération commencée conserve sa trace d’exécution, même si un autre appel échoue.

Par défaut, deux appels indépendants au maximum peuvent s’exécuter simultanément par anticipation. Définissez maxConcurrentCalls en Node ou max_concurrent_calls en Python à un entier strictement positif pour modifier cette limite. L’exécuteur attend la fin du groupe courant avant de lire d’autres appels dans le flux. Cette option s’applique uniquement aux appels indépendants exécutés par anticipation sans journal. Chaque fonction doit limiter elle-même les opérations qu’elle lance.

Si une exécution anticipée est interrompue, examinez ResponsesToolRunnerError.attemptedCallIds et completedCallIds en Node, ou attempted_call_ids et completed_call_ids en Python. Ces champs contiennent des identifiants d’appel, sans résultats, arguments ni messages du pilote. Des effets peuvent déjà s’être produits. Consultez l’état de l’application qui fait foi avant de retenter une action déjà tentée ou dont l’issue est incertaine.

Utilisez contextBudget ou context_budget pour limiter le nombre d’octets et d’images en entrée de la requête suivante, avec ou sans stockage persistant. La projection conserve les observations courantes et les liens nécessaires entre les outils. Une limite en mémoire ne permet pas de reprendre une exécution après l’arrêt du processus.

À la fin d’un tour, appendUserText ou append_user_text met en file d’attente les instructions d’une personne. L’exécuteur les ajoute après avoir consigné les sorties en attente. Cette méthode accepte du texte, mais ni des sorties d’outils arbitraires ni des objets d’approbation. Elle ne réinitialise pas le nombre de requêtes autorisées.

Utilisez cette méthode pour préciser la tâche en cours, par exemple pour demander à l’agent de vérifier une autre date. Si l’utilisateur remplace la tâche, arrêtez l’exécution en cours et attendez sa fin avant d’en démarrer une nouvelle. Relisez l’état de l’application et obtenez une nouvelle approbation pour les nouvelles actions. Conservez la trace de l’ancienne exécution. Modifier les instructions n’annule pas ses effets.

Pour permettre une reprise persistante, fournissez un ledger qui enregistre chaque point de reprise sous le contrôle exclusif du propriétaire de l’exécution. Reprenez uniquement à la fin d’un tour terminé. Si une action est en attente ou que son issue est incertaine, établissez d’abord ce qui s’est réellement passé. La reprise conserve le nombre de requêtes restantes et l’historique des opérations terminées. Le compactage local lié au budget de contexte conserve toutes les données justificatives dans le journal et maintient dans le contexte les observations courantes, les vérifications de sécurité, les messages et le raisonnement. Il ne vaut jamais approbation.

Chaque sauvegarde reçoit une copie indépendante et complète du point de reprise, y compris avant et après les effets locaux. Le point de reprise contient le lot entier et l’historique accumulé. Pour les grands lots, le travail total de copie et de stockage de ces enregistrements peut croître de façon quadratique. Choisissez un stockage adapté à ce volume. contextBudget et context_budget limitent les entrées des requêtes, pas la taille du journal.

En cas d’interruption, un point de reprise en attente contient la séquence initiale enregistrée lors de la dernière sauvegarde. Il peut omettre du texte ultérieur et des propositions qui n’ont pas été tentées. Il n’autorise jamais à rejouer les actions. Avant et après un effet, le point de reprise sauvegardé contient toute la séquence observée jusque-là et les traces d’exécution.

Une exécution qui inclut des outils MCP sauvegarde un point de reprise en attente avant chaque requête. Si la connexion échoue, vérifiez ce que le serveur MCP a fait avant de démarrer une autre exécution. Ce point de reprise en attente ne permet pas de reprendre automatiquement.

Les déclarations MCP sauvegardées omettent les données d’autorisation et les en-têtes personnalisés, et remplacent les URL des serveurs par des empreintes SHA-256. Les requêtes natives continuent d’utiliser l’URL d’origine. Placez les données d’authentification à renouveler dans le champ d’autorisation ou dans les en-têtes. Modifier le chemin d’une URL ou une valeur de paramètre de requête non reconnue change son identité et exige une nouvelle exécution. Les points de reprise contenant des URL MCP brutes ne permettent pas de reprendre l’exécution. Node a besoin de crypto.subtle.digest pour sauvegarder une URL MCP. Les autres entrées et sorties des points de reprise restent des données privées de l’application.

Lors de la reprise, fournissez des données d’authentification à jour et vérifiez qu’elles correspondent au serveur et au compte voulus.

Les déclarations sauvegardées de l’Interpréteur de code conservent les noms et domaines des données d’authentification, mais effacent leurs valeurs secrètes. Lors de la reprise, fournissez les valeurs à jour dans la configuration de l’outil. Pour les approbations MCP, un filtre vide always: {} ou never: {} s’applique à tous les outils.

Fournissez approveMcp en Node ou approve_mcp en Python si l’entrée initiale ou un journal sauvegardé contient des demandes MCP approuvées. Avant la première sauvegarde ou requête API, l’exécuteur redemande chaque approbation pour laquelle aucun appel MCP correspondant n’est terminé. Cette règle s’applique avec ou sans journal ou budget de contexte. Les appels terminés et les refus antérieurs sont conservés tels quels. Si une nouvelle approbation est nécessaire, l’absence de rappel arrête l’exécution.

Vérifiez un pilote personnalisé en local

Exécutez l’exercice local de la démo de réservation ou de l’exemple de bureau isolé avant de l’adapter. Ajoutez des vérifications portant sur l’état réel de la page dans votre pilote, les effets des entrées et la libération des ressources. La validation par le SDK ne prouve pas que l’environnement a correctement exécuté une action.

Consultez Exécutez votre première tâche pour suivre un exemple de bout en bout avec le SDK et les procédures d’intégration pour configurer l’environnement. Après toute modification, vérifiez le formulaire sauvegardé, le fichier ou les autres données enregistrées dans l’application avant d’annoncer la réussite de l’opération.