Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Geplante Automatisierungen

Lass Agenten Aufgaben nach einem Zeitplan ausführen oder Folgeaufgaben selbst planen.

Mit geplanten Automatisierungen kannst du Agentensitzungen nach einem Cron-Zeitplan starten. Du kannst für deine Agenten auch das Tool automations aktivieren, damit sie während ihrer Arbeit selbst Aufgaben planen können.

  • Sitzungen nach einem Cron-Zeitplan automatisieren

    Gib einen Cron-Ausdruck und eine Zeitzone an, um neue Sitzungen zu starten oder eine bestehende Sitzung fortzusetzen.

  • Agenten das Erstellen von Automatisierungen ermöglichen

    Füge das Tool automations hinzu, damit ein Agent Folgeaufgaben für seine aktuelle Sitzung planen kann.

  • Aufrufe von Automatisierungen überwachen

    Jeder Aufruf dokumentiert einen Versuch, eine Aufgabe an eine Sitzung zu senden. Prüfe den Status und die Sitzungs-ID des Aufrufs.

Sitzungen nach einem Cron-Zeitplan automatisieren
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);

API-Ressourcen

  • Agenten

    /v1/agents

    Lege die Anweisungen und Tools für die Aufgabe fest.

  • Automatisierungen

    /v1/agents/automations

    Speichere, wann und in welcher Sitzung die Aufgabe ausgeführt werden soll.

  • Aufrufe

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

    Sieh nach, wann eine Aufgabe gesendet wurde und welche Sitzung sie empfangen hat.

  • Sitzungen

    /v1/agents/sessions

    Führe die Aufgabe mit dem Gesprächsverlauf und den Tools der Sitzung aus.

  • Sitzungsereignisse

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

    Verfolge den Fortschritt und erfasse das Ergebnis.

Anwendungsfälle

So funktioniert es

Eine Automatisierung ist ein gespeicherter Zeitplan für die Aufgaben eines Agenten. Die Agents API speichert den Zeitplan und sendet jede Aufgabe an die vorgesehene Sitzung.

  1. Aufgabe festlegen. Lege fest, wann die Aufgabe ausgeführt werden soll und ob jeder Lauf eine neue Sitzung startet oder eine bestehende fortsetzt.
  2. Aufgabe senden. Bei jedem Lauf entsteht ein Aufruf. Er dokumentiert den Versuch, die Aufgabe an die Zielsitzung zu senden. Ist die Sitzung beschäftigt, wartet die Aufgabe.
  3. Ergebnis verfolgen. Der Agent nutzt die Tools und den Kontext der Sitzung. Verfolge die Sitzungsereignisse, um den Fortschritt zu sehen und die Ergebnisse zu erfassen. Auch wenn die Sitzung die Aufgabe empfangen hat, kann der Agent noch daran arbeiten.

Deine Anwendung kann Zeitpläne über die API erstellen, aktualisieren, pausieren oder löschen. Ist das Tool automations aktiviert, kann ein Agent auch selbst die nächste Prüfung für seine aktuelle Sitzung planen.

Sitzung und Zeitplan auswählen

Wähle das Ziel danach aus, ob die Aufgabe den bisherigen Gesprächsverlauf benötigt.

Ziel Geeignet für Erforderliche Konfiguration
new_session Eigenständige Aufgaben, etwa eine monatliche Ausgabenanalyse. Ein Agent, eine Umgebung und die ersten Nachrichten in target.input.
existing_session Folgeaufgaben, die auf früheren Ergebnissen der Sitzung aufbauen. Eine Sitzungs-ID und ein Erinnerungstext in target.instructions.

Den Zeitpunkt legst du unabhängig vom Ziel fest.

Typ Felder für die Zeitplanung Beispiel
periodic expression und timezone Täglich um 10 Uhr in der Zeitzone America/New_York.
once run_at Eine einmalige Prüfung zu einem zukünftigen Zeitpunkt, angegeben als Unix-Zeitstempel in Sekunden.

Beide Zeitplantypen funktionieren mit beiden Zielen. Beim Erstellen erhält die Automatisierung den Status active. Die Aufgabe wird dabei noch nicht ausgeführt. Der erste Lauf einer wiederkehrenden Automatisierung ist für den nächsten Zeitpunkt vorgesehen, der dem Zeitplan entspricht.

Tägliche Vorschläge planen

Erstelle vor der Automatisierung einen Agenten mit den Anweisungen und Tools für die Aufgabe. Er benötigt unter anderem Zugriff auf Kalender, Aufgaben und Nachrichten der jeweiligen Person. Siehe Einen Agenten in mehreren Sitzungen verwenden.

Die SDKs senden den Header OpenAI-Beta: agents=v1 mit. Wenn du die API mit cURL aufrufst, füge ihn selbst hinzu.

Dieses Beispiel erstellt eine Automatisierung, die täglich um 10 Uhr New Yorker Zeit eine neue Sitzung startet.

Tägliche Vorschläge planen
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())

Speichere die zurückgegebene id der Automatisierung, um den Zeitplan später abzurufen oder zu verwalten. Jeder Aufruf startet ein neues Gespräch. Die oben gezeigte Umgebungskonfiguration stellt für die Sitzung eine von OpenAI gehostete Sandbox bereit.

Du kannst die Agentenkonfiguration direkt in target.agent angeben, anstatt mit target.agent_id auf einen gespeicherten Agenten zu verweisen. Gib genau eines dieser Felder an. Die ersten Nachrichten gehören in target.input und dürfen nicht auf der obersten Ebene der Anfrage stehen. Gib mindestens eine Nachricht mit nicht leerem Text oder einer Bild-URL an.

Ausgaben monatlich prüfen

Genauso kannst du eine monatliche Ausgabenanalyse planen. Gib dem gespeicherten Agenten Zugriff auf die Finanzunterlagen der jeweiligen Person und plane für den ersten Tag jedes Monats um 9 Uhr eine neue Sitzung.

Monatliche Ausgabenanalyse planen
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())

Wiederkehrende Termine festlegen

Verwende einen Cron-Ausdruck mit fünf Feldern und gib die Zeitzone mit ihrem Namen an.

Ausdruck Zeitplan
0 10 * * * Täglich um 10 Uhr
0 */2 * * * Alle zwei Stunden
0 9 1 * * Am ersten Tag jedes Monats um 9 Uhr
0 9 * * MON-FRI Montag bis Freitag um 9 Uhr

Die Zeitzone bestimmt, wie die API den Ausdruck interpretiert. Verwende UTC für einen UTC-Zeitplan oder eine IANA-Zeitzone wie America/New_York für einen Zeitplan nach Ortszeit. Gib bei einer wiederkehrenden Automatisierung kein run_at an.

Ein Cron-Zeitplan richtet sich nach den Uhrzeiten in der gewählten Zeitzone. Beispielsweise plant 0 */3 * * * Läufe für 0 Uhr, 3 Uhr, 6 Uhr und danach alle drei Stunden. Der Zeitpunkt der Erstellung spielt für diesen Rhythmus keine Rolle.

Der Zeitplan gibt den vorgesehenen Zeitpunkt an. Um die Last zu verteilen, verzögert die Agents API wiederkehrende Läufe um eine kurze, zufällig gewählte Zeitspanne. Ist die Zielsitzung beschäftigt, kann die Wartezeit länger ausfallen.

Eine bestehende Sitzung fortsetzen

Verwende eine bestehende Sitzung, wenn der Agent frühere Erkenntnisse, Nachrichten oder gespeicherte Arbeitsergebnisse benötigt. In einer Sitzung zur Planung eines Abendessens bleiben beispielsweise die Restaurantwünsche und die Ergebnisse früherer Verfügbarkeitsprüfungen erhalten.

So prüfst du in dieser Sitzung alle zwei Stunden, ob sich ein Tisch reservieren lässt.

Verfügbarkeit von Tischen prüfen
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())

Jeder Aufruf übermittelt die gespeicherten Anweisungen als Benachrichtigung der Automatisierung an dieselbe Sitzung. Dabei gelten die aktuelle Agentenkonfiguration und der gespeicherte Zustand der Sitzung. Die Sitzung empfängt die Benachrichtigung getrennt von neuen Nachrichten der Person, die sie nutzt.

Arbeitet die Sitzung gerade an einer Aufgabe, erfolgt die Zustellung erst, wenn die Sitzung wieder verfügbar ist. Ein geplanter Lauf unterbricht den aktiven Turn nicht. Er liefert auch kein fehlendes Tool-Ergebnis und erteilt keine ausstehende Genehmigung. Deine Anwendung muss weiterhin erforderliche Aktionen bearbeiten.

Eine einzelne Prüfung planen

Verwende für eine einmalige Folgeaufgabe type: "once" mit run_at. Der Wert muss ein ganzzahliger Unix-Zeitstempel in Sekunden sein und einen Zeitpunkt in der Zukunft angeben. Lass expression und timezone weg.

So planst du eine Prüfung für den 1. Januar 2027 um 9 Uhr UTC.

Einmaligen Lauf eines Agenten planen
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())

Nach Abschluss eines einmaligen Zeitplans stehen keine weiteren Läufe an. Du kannst die Automatisierung weiterhin manuell aufrufen oder für eine weitere geplante Folgeaufgabe eine neue Automatisierung erstellen.

Folgeaufgaben vom Agenten planen lassen

Füge automations zu den Tools des Agenten hinzu, damit er Aufgaben auf Wunsch der jeweiligen Person planen kann. Dieses Beispiel aktiviert außerdem Subagenten. So kann der Hauptagent jede geplante Aufgabe delegieren und eine kurze Zusammenfassung des Ergebnisses behalten.

Agenten Aufgaben planen lassen
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)

Damit kann der Agent eigene Automatisierungen erstellen, auflisten, einzeln abrufen, aktualisieren, pausieren, fortsetzen und löschen. Die Agents API legt die aktuelle Sitzung als Ziel fest. Der Agent kann einmalige oder wiederkehrende Läufe planen. Mit diesen Tools kann er jedoch keine neue Sitzung starten und keine Automatisierungen anderer Sitzungen verwalten.

Die Tools haben nur Zugriff auf Automatisierungen, die der Agent in der aktuellen Sitzung erstellt hat. Deine Anwendung kann diese Automatisierungen über die API zusammen mit ihren eigenen verwalten. Die Agents API hält in created_by fest, wer die Automatisierung erstellt hat. Lass dieses Feld in der Anfrage zum Erstellen weg.

Standardmäßig ist das Tool nicht eingebunden. Deine Anwendung kann auch ohne das Tool Aufgaben planen. Wenn du das Tool aus der Agentenkonfiguration entfernst, bleiben gespeicherte Zeitpläne erhalten. Bei Bedarf kannst du sie über die API pausieren oder löschen.

Den Kontext der Hauptsitzung bei wiederkehrenden Aufgaben klein halten

Für längerfristige Ziele kannst du die Orchestrierung mehrerer Agenten aktivieren, indem du agent.multi_agent.enabled: true setzt. Weise den Hauptagenten an, das Ziel und den Zeitplan festzuhalten, jede Aufgabe an einen Subagenten zu delegieren und eine kurze Zusammenfassung des Ergebnisses aufzubewahren. So bleiben detaillierte Tool-Ausgaben aus wiederholten Prüfungen außerhalb des Kontextfensters der Hauptsitzung.

Du kannst zum Beispiel folgende Anweisung für den Hauptagenten verwenden.

Delegiere jede geplante Aufgabe an einen Subagenten. Teile ihm das Ziel und relevante frühere Erkenntnisse mit und bitte ihn um ein knappes Ergebnis. Prüfe das Ergebnis, halte die nützlichen Informationen in einer kurzen Zusammenfassung fest und entscheide, ob du den Zeitplan fortsetzt, änderst oder beendest.

Das Tool automations verwaltet Zeitpläne. Stelle dem Agenten weiterhin die anderen Tools und Datenzugriffe zur Verfügung, die er für die geplanten Aufgaben benötigt.

Folgeaufgaben für das Onboarding in deiner App planen

Deine Anwendung kann auch als Reaktion auf eigene Ereignisse Zeitpläne erstellen. Wenn sich beispielsweise jemand registriert, kannst du eine Onboarding-Sitzung starten und die erste Folgeaufgabe für 48 Stunden später planen.

Eine Folgeaufgabe für das Onboarding planen
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())

Nach jeder abgeschlossenen Folgeaufgabe kann deine Anwendung die nächste für 48 Stunden später planen. Beende die Reihe, sobald das Onboarding abgeschlossen ist oder die Person keine weiteren Nachrichten wünscht, und lösche ausstehende Folgeaufgaben. Verwende für dieses Intervall einmalige Zeitpläne. Ein Cron-Ausdruck für den Tag des Monats kann ein wiederkehrendes Intervall von 48 Stunden über Monatsgrenzen hinweg nicht abbilden.

Der Onboarding-Agent benötigt Zugriff auf den Stand des Onboardings und auf die Tools der Anwendung zum Versenden von Nachrichten. Wenn du die Automatisierung erstellst, planst du die Aufgabe. Die Nachricht wird dabei noch nicht gesendet.

Einen Lauf testen und die Zustellung prüfen

Um eine gespeicherte Automatisierung sofort zu testen, sende POST /v1/agents/automations/auto_123/invocations ohne Anfragetext. Ein manueller Aufruf ändert den gespeicherten Zeitplan nicht. Auch ein geplanter einmaliger Lauf bleibt ausstehend. Du kannst die Automatisierung selbst bei pausiertem Zeitplan manuell aufrufen.

Speichere die zurückgegebene Aufruf-ID. Mit GET /v1/agents/automations/auto_123/invocations/ainv_123 rufst du den einzelnen Aufruf ab. Mit GET /v1/agents/automations/auto_123/invocations lässt du dir den Zustellungsverlauf anzeigen.

Für einen Überblick über vergangene Läufe kannst du die Aufrufe der Automatisierung auflisten.

Aufrufe von Automatisierungen überwachen
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);
}

Der Verlauf enthält die bereits erstellten Aufrufe und führt daher nicht jeden zukünftigen Termin auf. Prüfe die folgenden Felder.

Feld Bedeutung
status Hat anfangs den Wert queued und wechselt bei erfolgreicher Zustellung zu completed.
session_id Gibt an, welche Sitzung du nach der Zustellung verfolgen kannst. Solange noch keine Sitzung verfügbar ist, kann der Wert null sein.
source.type manual bei einem manuellen Aufruf oder automation bei einem geplanten Lauf.
scheduled_at Der laut Zeitplan vorgesehene Zeitpunkt oder null bei einem manuellen Aufruf.

Eine erfolgreiche Zustellung sagt noch nichts darüber aus, ob der Agent seine Aufgabe abgeschlossen hat. Bei einer neuen Sitzung bedeutet die erfolgreiche Zustellung, dass die Sitzung ihre ersten Eingaben angenommen hat. Bei einer bestehenden Sitzung bedeutet sie, dass die Sitzung die Benachrichtigung und die Aufforderung zum Arbeitsbeginn angenommen hat.

Verwende die session_id des Aufrufs, um die Sitzungsereignisse zu verfolgen und das Ergebnis des Turns zu prüfen.

Die Automatisierung plant die Aufgabe. Deine Anwendung zeigt die Ausgaben der Sitzung an und versendet bei Bedarf Benachrichtigungen an die jeweilige Person.

Einen Zeitplan ändern oder beenden

Rufe eine Automatisierung mit GET /v1/agents/automations/auto_123 ab. Mit GET /v1/agents/automations listest du die Automatisierungen deines Projekts auf. Füge session_id=sess_123 hinzu, um Automatisierungen für eine bestimmte bestehende Sitzung zu finden.

Ändere den Cron-Ausdruck, um eine wiederkehrende Prüfung auf 11 Uhr zu verschieben.

Einen Zeitplan ändern
from openai import OpenAI

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

Felder, die du weglässt, behalten ihren bisherigen Wert. Wenn du target angibst, ersetzt du das gesamte Ziel. Gib daher alle Pflichtfelder des Ziels an und behalte seinen Typ bei. Aktualisiere den Erinnerungstext in target.instructions oder die ersten Nachrichten in target.input. Bei einer vom Agenten erstellten Automatisierung muss die Sitzung, in der er sie erstellt hat, das Ziel bleiben.

Nimm Änderungen vor dem nächsten geplanten Zeitpunkt vor. Aktualisierungen gelten für zukünftige Aufrufe. Ein Aufruf, der bereits in der Warteschlange steht, behält das Ziel und die Eingaben, die bei seiner Erstellung gespeichert wurden.

Sende die folgenden Anfragen ohne Anfragetext.

Ziel Operation Wirkung
Geplante Aufgaben pausieren. POST /v1/agents/automations/auto_123/pause Hält ausstehende geplante Zustellungen zurück. Manuelle Aufrufe sind weiterhin möglich.
Geplante Aufgaben fortsetzen. POST /v1/agents/automations/auto_123/resume Aktiviert den gespeicherten Zeitplan wieder.
Den Zeitplan entfernen. DELETE /v1/agents/automations/auto_123 Verhindert zukünftige geplante und manuelle Aufrufe.

Wenn du eine Automatisierung pausierst oder löschst, bearbeitet die Sitzung bereits angenommene Aufgaben weiter. Die Sitzung selbst bleibt bestehen. Eine bereits laufende Zustellung kann ihre Zielsitzung noch erreichen. Um die aktuelle Aufgabe zu stoppen, brich den aktiven Turn ab.

Verstreicht der geplante Zeitpunkt einer einmaligen Automatisierung während einer Pause, setze run_at vor dem Fortsetzen auf einen neuen Zeitpunkt in der Zukunft. Eine abgeschlossene einmalige Automatisierung lässt sich weder pausieren noch fortsetzen. Erstelle für eine weitere geplante Folgeaufgabe eine neue Automatisierung.