For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navigation principale
Theme

Suggestions

API Agents

Agents SDK

ChatKit

Tableau de bord de l’API
Essayez ChatGPT

Automatisations planifiées

Planifiez les tâches d’un agent ou laissez-le planifier lui-même ses prochaines tâches.

Utilisez les automatisations planifiées pour lancer des sessions d’agent aux horaires définis par une expression cron. Vous pouvez aussi activer l’outil automations pour que vos agents puissent planifier des tâches au fil de leur travail.

  • Automatisez les sessions avec cron

    Utilisez une expression cron et un fuseau horaire pour démarrer de nouvelles sessions ou poursuivre une session existante.

  • Permettez aux agents de créer des automatisations

    Ajoutez l’outil automations pour qu’un agent puisse planifier des tâches de suivi dans sa session en cours.

  • Suivez les invocations des automatisations

    Chaque invocation consigne une tentative d’envoi d’une tâche à une session. Consultez son statut et l’identifiant de la session.
Automatisez les sessions avec cron
import OpenAI from "openai";

const client = new OpenAI();
const automation = await client.beta.agents.automations.create({
  type: "periodic",
  name: "Daily session",
  expression: "0 10 * * *",
  timezone: "America/New_York",
  target: {
    type: "new_session",
    agent_id: "agt_123",
    environment: { type: "openai_hosted" },
    input: [
      {
        role: "user",
        content: [
          {
            type: "input_text",
            text: "Summarize the current status and next steps.",
          },
        ],
      },
    ],
  },
});
console.log(automation);

Ressources de l’API

  • Agents

    /v1/agents

    Définissez les instructions et les outils nécessaires à la tâche.

  • Automatisations

    /v1/agents/automations

    Enregistrez l’horaire d’exécution et la session à utiliser.

  • Invocations

    /v1/agents/automations/{automation_id}/invocations

    Vérifiez quand une tâche a été envoyée et quelle session l’a reçue.

  • Sessions

    /v1/agents/sessions

    Exécutez la tâche avec l’historique de la conversation et les outils de la session.

  • Événements de session

    /v1/agents/sessions/{session_id}/events

    Suivez l’avancement de la tâche et récupérez le résultat.

Cas d’usage

Fonctionnement

Une automatisation est une planification enregistrée pour les tâches d’un agent. L’API Agents conserve cette planification et envoie chaque tâche à sa session cible.

  1. Définissez la tâche. Choisissez quand l’exécuter et précisez si chaque exécution doit démarrer une nouvelle session ou poursuivre une session existante.
  2. Envoyez la tâche. Chaque exécution crée une invocation, qui consigne la tentative d’envoi de la tâche à sa session cible. Si cette session est occupée, la tâche reste en attente.
  3. Suivez l’exécution jusqu’au résultat. L’agent utilise les outils et le contexte de la session. Suivez les événements de session pour connaître l’avancement et récupérer les résultats. La réception de la tâche par la session ne signifie pas que l’agent a terminé son travail.

Votre application peut créer, modifier, suspendre ou supprimer des planifications via l’API. Si l’outil automations est activé, un agent peut également planifier sa prochaine vérification dans sa session en cours.

Choisissez la session et l’horaire

Choisissez la cible selon que la tâche nécessite ou non l’historique de la conversation.

Cible Cas d’usage Configuration requise
new_session Tâche indépendante, par exemple un bilan mensuel des dépenses. Un agent, un environnement et des messages initiaux dans target.input.
existing_session Tâche de suivi qui s’appuie sur les résultats précédents de la session. Un identifiant de session et le texte du rappel dans target.instructions.

Choisissez l’horaire indépendamment de la cible.

Type Champs de planification Exemple
periodic expression et timezone Tous les jours à 10 h dans le fuseau America/New_York.
once run_at Une seule vérification à une date future exprimée sous forme d’horodatage Unix en secondes.

Les deux types de planification acceptent l’une ou l’autre cible. Lorsque vous créez une automatisation, l’API l’enregistre avec le statut active sans exécuter immédiatement la tâche. La première exécution d’une automatisation périodique est prévue au prochain horaire correspondant à sa planification.

Planifiez des suggestions quotidiennes

Avant de créer l’automatisation, créez un agent et fournissez-lui les instructions et les outils nécessaires à la tâche, notamment l’accès à l’agenda, aux tâches et aux messages de l’utilisateur. Consultez la section Réutilisez un agent dans plusieurs sessions.

Les SDK incluent l’en-tête OpenAI-Beta: agents=v1. Ajoutez-le lorsque vous appelez l’API avec cURL.

Cet exemple crée une automatisation qui démarre une nouvelle session chaque jour à 10 h, heure de New York.

Planifiez des suggestions quotidiennes
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="periodic",
    name="Daily suggestions",
    expression="0 10 * * *",
    timezone="America/New_York",
    target={
        "type": "new_session",
        "agent_id": "agt_123",
        "environment": {"type": "openai_hosted"},
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": (
                            "Review my calendar, tasks, and recent messages for today. "
                            "Suggest the most useful actions I could take today, "
                            "with a short reason for each."
                        ),
                    }
                ],
            }
        ],
    },
)
print(automation.to_json())

Conservez l’identifiant de l’automatisation renvoyé dans id pour consulter ou gérer la planification par la suite. Chaque invocation démarre une nouvelle conversation. La configuration d’environnement ci-dessus crée un bac à sable hébergé par OpenAI pour cette session.

Vous pouvez fournir directement la configuration de l’agent dans target.agent au lieu de référencer un agent enregistré avec target.agent_id. Renseignez un seul de ces deux champs. Placez les messages initiaux dans target.input et non au premier niveau de la requête. Incluez au moins un message contenant du texte non vide ou l’URL d’une image.

Analysez les dépenses chaque mois

La même méthode permet d’établir un bilan mensuel des dépenses. Donnez à l’agent enregistré accès aux données financières de l’utilisateur, puis planifiez une nouvelle session à 9 h le premier jour de chaque mois.

Planifiez un bilan mensuel des dépenses
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="periodic",
    name="Monthly spending review",
    expression="0 9 1 * *",
    timezone="America/New_York",
    target={
        "type": "new_session",
        "agent_id": "agt_123",
        "environment": {"type": "openai_hosted"},
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": (
                            "Review my spending for the previous month. Flag unused "
                            "subscriptions, price increases, and other potential "
                            "savings for me to review."
                        ),
                    }
                ],
            }
        ],
    },
)
print(automation.to_json())

Définissez des horaires récurrents

Utilisez une expression cron à cinq champs et indiquez le nom du fuseau horaire.

Expression Horaire
0 10 * * * Tous les jours à 10 h
0 */2 * * * Toutes les deux heures
0 9 1 * * Le premier jour de chaque mois à 9 h
0 9 * * MON-FRI Du lundi au vendredi à 9 h

Le fuseau horaire détermine comment interpréter l’expression. Utilisez UTC pour planifier en UTC ou un fuseau horaire IANA tel que America/New_York pour planifier en heure locale. N’incluez pas run_at dans une automatisation périodique.

Une planification cron suit les heures du fuseau sélectionné. Par exemple, 0 */3 * * * prévoit des exécutions à minuit, à 3 h, à 6 h, puis toutes les trois heures. L’intervalle ne se calcule pas à partir de l’heure de création.

La planification indique l’heure prévue. Pour répartir la charge, l’API Agents ajoute un léger délai aléatoire aux exécutions récurrentes. La tâche peut attendre plus longtemps si la session cible est occupée.

Poursuivez une session existante

Utilisez une session existante lorsque l’agent a besoin de résultats antérieurs, de messages précédents ou de travaux enregistrés. Par exemple, une session consacrée à l’organisation d’un dîner peut conserver les préférences de l’utilisateur en matière de restaurants et les résultats des vérifications de disponibilité précédentes.

Cet exemple vérifie toutes les deux heures, dans cette même session, si des tables sont disponibles à la réservation.

Vérifiez les disponibilités des restaurants
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="periodic",
    name="Check restaurant reservations",
    expression="0 */2 * * *",
    timezone="America/New_York",
    target={
        "type": "existing_session",
        "session_id": "sess_123",
        "instructions": (
            "Check restaurant availability for our dinner plans. "
            "Compare with earlier checks and report newly available tables."
        ),
    },
)
print(automation.to_json())

À chaque invocation, la même session reçoit les instructions enregistrées sous forme de notification d’automatisation. Elle utilise la configuration actuelle de son agent et son état enregistré. Cette notification est distincte d’un nouveau message de l’utilisateur.

Si la session est occupée, l’envoi est différé jusqu’à ce qu’elle soit disponible. Une exécution planifiée n’interrompt pas le tour en cours. Elle ne fournit ni le résultat d’outil ni l’approbation que la session attend. Votre application doit toujours traiter les actions requises.

Planifiez une vérification unique

Pour un suivi ponctuel, utilisez type: "once" avec run_at. La valeur doit être un horodatage Unix entier en secondes correspondant à une date future. N’incluez ni expression ni timezone.

Planifiez une vérification pour le 1er janvier 2027 à 9 h UTC.

Planifiez une exécution unique de l’agent
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="once",
    name="Check restaurant reply",
    run_at=1798794000,
    target={
        "type": "existing_session",
        "session_id": "sess_123",
        "instructions": (
            "Check whether the restaurant replied about our booking. "
            "Summarize any changes to the dinner plans."
        ),
    },
)
print(automation.to_json())

Une fois l’exécution ponctuelle terminée, aucune autre exécution n’est prévue. Vous pouvez toujours déclencher l’automatisation manuellement ou créer une autre automatisation pour planifier un nouveau suivi.

Laissez l’agent planifier les tâches de suivi

Ajoutez automations aux outils de l’agent pour lui permettre de planifier les tâches demandées par l’utilisateur. Cet exemple active également les sous-agents afin que l’agent principal puisse déléguer chaque tâche planifiée et conserver un bref résumé du résultat.

Laissez les agents planifier des tâches
from openai import OpenAI

client = OpenAI()
session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": (
            "Use automations to schedule tasks requested by the user. "
            "Delegate each scheduled task to a subagent and ask for a concise result. "
            "Keep the goal, schedule, and useful summaries in the main session. "
            "Adjust or stop schedules when the user asks."
        ),
        "multi_agent": {"enabled": True},
        "tools": [{"type": "automations"}],
    },
    environment={"type": "openai_hosted"},
    input=(
        "Every day at 10 AM in America/New_York, review the goals we discuss here "
        "and suggest the next actions I could take."
    ),
)
print(session.id)

L’agent peut ainsi créer, lister, récupérer, modifier, suspendre, reprendre et supprimer ses propres automatisations. L’API Agents définit la session en cours comme cible. L’agent peut planifier des exécutions ponctuelles ou périodiques, mais il ne peut pas utiliser ces outils pour démarrer une nouvelle session ni pour gérer les automatisations d’une autre session.

Les outils ont uniquement accès aux automatisations créées par l’agent dans la session en cours. Votre application peut les gérer via l’API, au même titre que celles qu’elle a créées elle-même. L’API Agents enregistre le créateur dans created_by. N’envoyez pas ce champ dans une requête de création.

Par défaut, l’outil est absent de la configuration. Votre application peut planifier des tâches sans l’activer. Si vous retirez l’outil de la configuration d’un agent, les planifications enregistrées sont conservées. Suspendez-les ou supprimez-les via l’API si nécessaire.

Gardez les détails des tâches répétitives hors du contexte principal

Pour les objectifs qui s’inscrivent dans la durée, activez l’orchestration multi-agent avec agent.multi_agent.enabled: true. Demandez à l’agent principal de conserver l’objectif et la planification, de déléguer chaque tâche à un sous-agent et de garder un bref résumé du résultat. Les sorties détaillées des outils utilisés lors des vérifications successives restent ainsi hors de la fenêtre de contexte de la session principale.

Par exemple, ajoutez ce passage aux instructions de l’agent principal :

Déléguez chaque tâche planifiée à un sous-agent. Transmettez-lui l’objectif et les résultats antérieurs pertinents, puis demandez-lui un résultat concis. Examinez ce résultat, conservez-en les éléments utiles sous forme de résumé et décidez s’il faut maintenir, modifier ou arrêter la planification.

L’outil automations gère les planifications. Conservez les autres outils et les accès aux données dont l’agent a besoin pour exécuter les tâches planifiées.

Planifiez le suivi de la prise en main depuis votre application

Votre application peut aussi créer des planifications en réponse à ses propres événements. Par exemple, à l’inscription d’un utilisateur, démarrez une session de prise en main et planifiez un premier suivi 48 heures plus tard.

Planifiez un suivi de la prise en main
import time

from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="once",
    name="Onboarding follow-up",
    run_at=int(time.time()) + 48 * 60 * 60,
    target={
        "type": "existing_session",
        "session_id": "sess_123",
        "instructions": (
            "Review onboarding progress and send the next onboarding message "
            "if the user has not completed onboarding."
        ),
    },
)
print(automation.to_json())

Après chaque suivi terminé, votre application peut en planifier un autre 48 heures plus tard. Arrêtez les suivis lorsque la prise en main est terminée ou que l’utilisateur y renonce, et supprimez tout suivi en attente. Utilisez des planifications ponctuelles pour respecter cet intervalle. Une expression cron fondée sur le jour du mois ne garantit pas un intervalle régulier de 48 heures lors du passage d’un mois au suivant.

L’agent chargé de la prise en main doit avoir accès à la progression de l’utilisateur et aux outils de messagerie de l’application. La création de l’automatisation planifie la tâche sans envoyer immédiatement le message.

Testez une exécution et vérifiez la réception de la tâche

Pour tester immédiatement une automatisation enregistrée, envoyez POST /v1/agents/automations/auto_123/invocations sans corps de requête. Une invocation manuelle ne modifie pas la planification enregistrée et ne consomme pas l’exécution prévue d’une automatisation ponctuelle. Elle fonctionne également lorsque la planification est suspendue.

Conservez l’identifiant d’invocation renvoyé. Récupérez l’invocation avec GET /v1/agents/automations/auto_123/invocations/ainv_123 ou consultez l’historique des envois avec GET /v1/agents/automations/auto_123/invocations.

Pour obtenir une vue d’ensemble des exécutions passées, listez les invocations de l’automatisation.

Suivez les invocations des automatisations
import OpenAI from "openai";

const client = new OpenAI();
for await (const invocation of client.beta.agents.automations.invocations.list(
  "auto_123"
)) {
  console.log(invocation.id, invocation.status, invocation.session_id);
}

L’historique contient les invocations déjà créées, mais ne recense pas toutes les exécutions à venir. Vérifiez les champs suivants.

Champ Points à vérifier
status Vaut initialement queued, puis passe à completed lorsque l’envoi aboutit.
session_id Identifie la session à suivre après l’envoi. Peut valoir null tant qu’aucune session n’est disponible.
source.type Vaut manual pour une invocation manuelle ou automation pour une exécution planifiée.
scheduled_at Indique l’heure prévue ou vaut null pour une invocation manuelle.

La réception de la tâche ne signifie pas que l’agent a terminé son travail. Pour une nouvelle session, elle indique que la session a accepté ses données d’entrée initiales. Pour une session existante, elle indique que la session a accepté la notification et la demande de démarrage de la tâche.

Utilisez le champ session_id de l’invocation pour suivre les événements de session et examiner le résultat du tour.

L’automatisation planifie la tâche. Votre application affiche les résultats de la session et envoie les éventuelles notifications à l’utilisateur.

Modifiez ou arrêtez une planification

Récupérez une automatisation avec GET /v1/agents/automations/auto_123. Listez les automatisations de votre projet avec GET /v1/agents/automations. Ajoutez session_id=sess_123 pour trouver celles qui ciblent une session existante.

Modifiez l’expression cron pour déplacer une vérification récurrente à 11 h.

Modifiez une planification
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.update(
    automation_id="auto_123",
    expression="0 11 * * *",
)
print(automation.to_json())

Les champs omis conservent leur valeur. Si vous fournissez target, vous remplacez toute la cible. Incluez donc tous ses champs obligatoires et conservez son type. Modifiez le texte du rappel dans target.instructions ou les messages initiaux dans target.input. Une automatisation créée par un agent doit conserver comme cible la session dans laquelle l’agent l’a créée.

Apportez vos modifications avant la prochaine échéance prévue. Elles s’appliquent aux invocations futures. Une invocation déjà en file d’attente conserve la cible et les données d’entrée enregistrées lors de sa création.

Utilisez les opérations suivantes sans corps de requête.

Objectif Opération Effet
Suspendez les tâches planifiées. POST /v1/agents/automations/auto_123/pause Suspend les envois planifiés en attente. Les invocations manuelles restent possibles.
Reprenez les tâches planifiées. POST /v1/agents/automations/auto_123/resume Réactive la planification enregistrée.
Supprimez la planification. DELETE /v1/agents/automations/auto_123 Empêche toute invocation ultérieure, planifiée ou manuelle.

Suspendre ou supprimer une automatisation n’arrête pas une tâche déjà acceptée par une session et ne supprime pas la session. Un envoi en cours peut encore atteindre sa session cible. Pour arrêter le travail en cours, annulez le tour actif.

Si l’heure prévue d’une automatisation ponctuelle passe pendant sa suspension, attribuez à run_at une nouvelle valeur dans le futur avant de reprendre l’automatisation. Une automatisation ponctuelle terminée ne peut être ni suspendue ni reprise. Créez une autre automatisation pour planifier un nouveau suivi.