OpenAI Agents API 2026 : comment un agent IA appelle-t-il des outils ? JSON Schema, Tool Calling et données de workflow

En un coup d’œil

Idée	Une ligne	Tombe sur
Agents API	Harness Codex hébergé par OpenAI	sessions.create / agent
Tool Calling	Le modèle propose un nom et des arguments	function_call / arguments
JSON Schema	La forme d’argument admise dans la boucle	parameters / additionalProperties
Workflow	Session, tour, items, passation	session / turn / items

Retenir la coupure : vous déclarez Agent, Tools, Environment ; OpenAI tourne la boucle. Les effets de bord restent chez l’hôte ou dans le bac à sable, pas dans les poids.

Il peut appeler des outils. Le modèle n’est pas l’appelant

Après la bêta, un POST /v1/agents/sessions lance un agent long : consulter une commande, lire un dépôt, envoyer un sous-agent. Ces effets de bord sont réels.

« Appeler directement » met le sujet au mauvais endroit. Le modèle ne tient pas la socket MCP, ne spawn pas le bac à sable, ne frappe pas votre API métier. Il émet un objet validable. Ce qui s’exécute, c’est le harness géré et l’Environment choisi.

• Déclarer : functions, MCP et web_search sur agent.tools.
• Proposer : le modèle émet un function_call — un nom plus un objet d’arguments.
• Exécuter : le harness touche un outil de service, votre handler, ou une commande dans le bac à sable.

Si Agent, Tool Calling et Function Calling tiennent encore en un mot, commencer par Guide complet de l’agent IA. Cet article ne traite qu’un fait : comment l’Agents API héberge cette chaîne JSON.

Ce que la bêta du 10 septembre a vraiment livré

OpenAI l’a dit net : le même harness derrière Codex et ChatGPT for Work, en API. Côté modèle, on voit souvent Guide GPT-6 Astra. Vous payez les jetons et l’usage des outils ; l’API n’ajoute pas de frais.

• Boucle gérée : session, orchestration, reprise — sans colle LangChain maison.
• Compactage de contexte : compact auto près de la limite, travail sur plusieurs fenêtres.
• Tool search + programmatic tool calling : charger les définitions à la demande, appeler en parallèle, ne ramener que les résultats utiles.
• MCP / function / web_search : une table d’outils peut les mélanger.
• Sous-agents : multi_agent.enabled, avec un plafond de concurrence (la doc met souvent 6).

Prédictions OpenAI DevDay 2026 prédisait Structured Outputs et Function Calling. Ce qui est arrivé est une ressource session : Agent, Environment, Session, Events / Items — pas un autre emballage de chat completion.

Le squelette reste le JSON Tool Calling

Le nom d’API a changé. Les quatre sauts non :

1. Déclarer : agent.tools[] offre un Schema de fonction, un serveur MCP, des outils intégrés.
2. Proposer : le modèle remplit un nom et des arguments. Il n’exécute pas.
3. Porte : le harness ou votre handler valide, allowliste, et peut attendre un humain.
4. Réécrire : un tool result devient le prochain item visible.

Une création de session ressemble à peu près à ceci. La commande est fictive — pas de secrets ni d’URL intranet sur un site public :

{
  "agent": {
    "model": "gpt-6-astra",
    "instructions": "Look up orders. Confirm before any refund.",
    "tools": [
      { "type": "programmatic_tool_calling" },
      {
        "type": "function",
        "name": "lookup_order",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" }
          },
          "required": ["order_id"],
          "additionalProperties": false
        }
      },
      {
        "type": "mcp",
        "server_label": "orders",
        "transport": {
          "type": "http",
          "server_url": "https://orders.example.com/mcp"
        }
      }
    ],
    "multi_agent": {
      "enabled": true,
      "max_concurrent_subagents": 3
    }
  },
  "environment": {
    "type": "hosted",
    "workspace_directory": "/workspace"
  },
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Look up order A-1042." }
      ]
    }
  ]
}

Une fois la boucle lancée, le modèle émet encore un objet, pas un paragraphe « merci de consulter la commande » :

{
  "type": "function_call",
  "id": "call_3c91",
  "name": "lookup_order",
  "arguments": "{\"order_id\":\"A-1042\"}"
}

La ligne MCP est une autre orthographe de la même table ; frontière dans MCP Tool Schema vs Function Calling. Un agent de code dans le bac à sable reste du JSON — voir Agents de code et chaîne d’appel JSON.

JSON Schema est la porte, pas « rendez du JSON »

Héberger la boucle ne rend pas sûr un object large. Contrat dans Pourquoi l’IA a besoin de JSON Schema : le prompt influence ce qu’il remplit ; le Schema décide ce qui peut s’exécuter.

{
  "name": "lookup_order",
  "description": "Look up an order by ID",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "pattern": "^[A-Z]-\\d{4}$"
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

Un Schema de fonction capable de bloquer un mauvais saut a besoin de quatre choses :

• Serrer les types : donner à order_id un pattern, pas une string nue.
• Enumérer montants et actions : remboursements et changements d’état veulent un enum.
• Fermer les clés en trop : additionalProperties: false. Un objet large est une autre porte.
• L’hôte écrit la confirmation : le modèle peut proposer create_refund ; il ne doit pas écrire allowed: true dans l’état.

Garder outils et workflows en Schema dans le dépôt, pas en accord de chat. Enchaîner les portes : JSON Schema et workflows d’agents IA.

Le workflow, ce sont quatre objets, pas une chaîne de prompts

OpenAI plie l’Agents API en quatre notions. En ingénierie, ce sont toutes du JSON :

• Agent : modèle, instructions, tools, MCP. La table de capacités.
• Environment : bac à sable hébergé ou self-hosted. Fichiers, commandes et skills vivent ici.
• Session : une instance durable. L’état reste côté service ; vous ne reconstruisez pas l’historique.
• Events / Items : entrée, appels d’outils, résultats, coordination des sous-agents.

Un workflow auditable ressemble à des objets, pas à une dernière phrase « c’est fait » :

{
  "session_id": "sess_9f2a",
  "turn": 2,
  "items": [
    { "type": "function_call", "name": "lookup_order", "id": "call_3c91" },
    { "type": "function_call_result", "call_id": "call_3c91", "status": "paid" }
  ],
  "state": {
    "order_id": "A-1042",
    "status": "paid"
  },
  "next": {
    "tool": "create_refund",
    "allowed": false,
    "reason": "missing_confirmation"
  }
}

Chaque sous-agent garde son contexte. L’agent principal coordonne avec des items create / message / wait / interrupt. Plafonner la concurrence. Sans plafond, jetons et effets de bord s’éventent.

Qui tourne la boucle

La question n’est pas qui est plus intelligent. Où vit l’orchestration :

Choisir le sujet avant l’API : voulez-vous posséder la boucle ? La comparaison complète vient ensuite. Ici, une seule exigence : changer l’entrée, la chaîne d’appel JSON reste.

Inspecter les objets, pas « l’agent a fini »

Après une session, ne pas relire la dernière phrase. Relire la trace.

• formater agent.tools, function_call et function_call_result. Vérifier que le nom et les arguments sont le saut prévu.
• Avec extraction JSONPath, extraire name, arguments et server_url. Ne pas scanner la prose à l’œil.
• JSON Diff contre une trace de session passée la semaine dernière. Si la boucle a dérivé, d’abord la table d’outils et la forme des arguments, ensuite le modèle.
• Les résumés après compact doivent encore porter les champs clés. Perdre order_id et le saut suivant se trompe.
• Ne pas coller commandes, sessions ou URL MCP intranet dans un formateur public. JSONSort tourne localement dans le navigateur ; c’est l’endroit pour lire ces objets.

Si la trace se reconstruit, la session se relit. C’est le billet d’entrée en production, pas un luxe.

Pièges

• Croire que l’Agents API fait exécuter les outils par le modèle. L’exécution vit sur le harness et l’Environment.
• Donner un object large à une boucle gérée. Hébergé n’est pas une porte.
• Activer multi_agent sans plafond de concurrence. Les sous-agents éventent jetons et effets de bord.
• Traiter une Session comme une autre chat completion. État, reprise et compact sont des objets de premier rang.
• Remplacer le Schema par un prompt. Le contrat doit être validable.
• Lire un bac à sable hébergé comme Zero Data Retention. OpenAI est explicite : un bac self-hosted ne rend pas l’Agents API éligible au ZDR.

FAQ

L’Agents API laisse-t-elle le modèle appeler les outils directement ?

Elle lui laisse émettre du JSON d’outil directement. L’exécution reste dans le harness géré, votre handler ou le bac à sable. Sans tools[], il n’appelle rien.

Agents API ou Responses API — par où commencer ?

Vous voulez qu’OpenAI tourne une longue boucle, compacte le contexte et envoie des sous-agents ? Agents API. Vous voulez posséder chaque appel modèle ? Responses API. La boucle dans votre processus ? Agents SDK.

Faut-il encore un JSON Schema sur l’Agents API ?

Oui. La boucle gérée n’orchestre que. Paramètres de fonction, inputSchema MCP et objets d’état doivent rester serrés. Un Schema large plus une boucle automatique ouvre plus grand.

Différence entre Session, Turn et Item ?

Une Session est l’instance durable. Un Turn est le travail lancé par une entrée utilisateur. Les Items sont les entrées, appels, résultats ou coordinations de sous-agents dans ce segment. Auditer les items, pas la dernière phrase.

Un agent peut-il toucher une base de production ou un remboursement réel ?

Pas d’effet de bord de production au premier saut. Le laisser rédiger dans un environnement isolé derrière un Schema serré. L’hôte écrit la confirmation. Secrets et mise en prod restent une porte humaine.

Conclusion

L’Agents API laisse un agent « appeler les outils directement » — cette phrase n’est vraie qu’à moitié. La vraie moitié : vous n’écrivez plus la boucle. La fausse est le sujet. Le sujet est le harness ; le verbe est exécuter ; l’objet est le JSON rempli par le modèle.

À partir d’aujourd’hui, moins débattre s’il « fait le travail lui-même ». Mettre d’abord Agent, Tools, items de session et Schema dans le dépôt. Les modèles changeront. Cette chaîne JSON Tool Calling doit d’abord tenir.

Pour aller plus loin

• Qu’est-ce qu’un agent IA ? Guide complet Runtime, tool calling et contrat JSON
• JSON Schema et workflows d’agents IA Capturer outils et état en Schema
• MCP Tool Schema vs Function Calling Frontière de protocole du JSON d’outil
• Pourquoi l’IA a besoin de JSON Schema Schema / Function Calling / Structured Output
• Prédictions OpenAI DevDay 2026 L’ancien cadrage Structured Outputs / Agent
• Boîte à outils locale JSONSort Formater, valider, Diff
• Tous les articles Plus de notes JSON et IA

Journal : 2026-09-20 Première publication