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.
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.
Agenten das Erstellen von Automatisierungen ermöglichen
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import OpenAI from"openai";constclient=newOpenAI();constsession=await 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.", tools: [{ type: "automations" }], multi_agent: { enabled: true }, }, 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.",});console.log(session.id);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22from openai import OpenAIclient = 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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32import ( "context" "fmt" "github.com/openai/openai-go/v3")ctx := context.Background()client := openai.NewClient()session, err := client.Beta.Agents.Sessions.New(ctx, openai.BetaAgentSessionNewParams{ Agent: openai.BetaAgentSessionNewParamsAgent{ Model: openai.String("gpt-6-astra"), Instructions: openai.String("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."), MultiAgent: openai.MultiAgentConfigParam{ Enabled: true, }, Tools: []openai.AgentToolParamUnion{ {OfParamAutomations: &openai.AgentToolParamAutomations{}}, }, }, Environment: openai.EnvironmentParamUnion{ OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{}, }, Input: openai.BetaAgentSessionNewParamsInputUnion{ OfString: openai.String("Every day at 10 AM in America/New_York, review the goals we discuss here and suggest the next actions I could take."), }, })if err != nil { panic(err)}fmt.Println(session.ID)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27import com.openai.client.OpenAIClient;import com.openai.client.okhttp.OpenAIOkHttpClient;import com.openai.models.beta.agents.EnvironmentParam;import com.openai.models.beta.agents.MultiAgentConfigParam;import com.openai.models.beta.agents.sessions.SessionCreateParams;OpenAIClient client = OpenAIOkHttpClient.fromEnv();var session = client .beta() .agents() .sessions() .create( SessionCreateParams.builder() .agent( SessionCreateParams.Agent.builder() .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.") .multiAgent(MultiAgentConfigParam.builder().enabled(true).build()) .addToolAutomations() .build()) .environment(EnvironmentParam.OpenAIHosted.builder().build()) .input( "Every day at 10 AM in America/New_York, review the goals we discuss here and suggest the next actions I could take.") .build());System.out.println(session.id());
1
2
3
4
5
6
7
8
9
10
11
12
13
14require "openai"client = OpenAI::Client.newsession = 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.")puts session.id
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16curl https://api.openai.com/v1/agents/sessions \ -H "OpenAI-Beta: agents=v1" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "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.", "tools": [{ "type": "automations" }], "multi_agent": { "enabled": true } }, "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." }'
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.
Aufgabe festlegen. Lege fest, wann die Aufgabe ausgeführt werden soll und ob jeder Lauf eine neue Sitzung startet oder eine bestehende fortsetzt.
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.
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
Python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import OpenAI from "openai";const client = new OpenAI();const automation = await 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.", }, ], }, ], },});console.log(automation);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30from openai import OpenAIclient = 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())
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42import ( "context" "fmt" "github.com/openai/openai-go/v3")ctx := context.Background()client := openai.NewClient()automation, err := client.Beta.Agents.Automations.New(ctx, openai.BetaAgentAutomationNewParams{ CreateAutomationParams: openai.AutomationScheduleParamUnion{ OfParamPeriodic: &openai.AutomationScheduleParamPeriodic{ Name: "Daily suggestions", Expression: "0 10 * * *", Timezone: "America/New_York", Target: openai.AutomationTargetParamUnion{ OfParamNewSession: &openai.AutomationTargetParamNewSession{ AgentID: openai.String("agt_123"), Environment: openai.EnvironmentParamUnion{ OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{}, }, Input: []openai.AgentSessionInputMessageParam{ { Content: []openai.InputContentParamUnion{ { OfParamInputText: &openai.InputContentParamInputText{ 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.", }, }, }, }, }, }, }, }, }, })if err != nil { panic(err)}fmt.Println(automation.ID)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34import com.openai.client.OpenAIClient;import com.openai.client.okhttp.OpenAIOkHttpClient;import com.openai.models.beta.agents.AgentSessionInputMessageParam;import com.openai.models.beta.agents.EnvironmentParam;import com.openai.models.beta.agents.automations.AutomationCreateParams;import com.openai.models.beta.agents.automations.AutomationScheduleParam;import com.openai.models.beta.agents.automations.AutomationTargetParam;OpenAIClient client = OpenAIOkHttpClient.fromEnv();var automation = client .beta() .agents() .automations() .create( AutomationCreateParams.builder() .automationScheduleParam( AutomationScheduleParam.Periodic.builder() .name("Daily suggestions") .expression("0 10 * * *") .timezone("America/New_York") .target( AutomationTargetParam.NewSession.builder() .agentId("agt_123") .environment(EnvironmentParam.OpenAIHosted.builder().build()) .addInput( AgentSessionInputMessageParam.builder() .addInputTextContent( "Review my calendar, tasks, and recent messages for today. Suggest the most useful actions I could take today, with a short reason for each.") .build()) .build()) .build()) .build());System.out.println(automation);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28require "openai"client = OpenAI::Client.newautomation = client.beta.agents.automations.create( create_automation_params: { 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." } ] } ] } })puts automation.id
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28curl https://api.openai.com/v1/agents/automations \ -H "OpenAI-Beta: agents=v1" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "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." } ] } ] } }'
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
Python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import OpenAI from "openai";const client = new OpenAI();const automation = await 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.", }, ], }, ], },});console.log(automation);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30from openai import OpenAIclient = 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())
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.
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
Python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15import OpenAI from "openai";const client = new OpenAI();const automation = await 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.", },});console.log(automation);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17from openai import OpenAIclient = 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
Python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import OpenAI from "openai";const client = new OpenAI();const session = await 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.", tools: [{ type: "automations" }], multi_agent: { enabled: true }, }, 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.",});console.log(session.id);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22from openai import OpenAIclient = 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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32import ( "context" "fmt" "github.com/openai/openai-go/v3")ctx := context.Background()client := openai.NewClient()session, err := client.Beta.Agents.Sessions.New(ctx, openai.BetaAgentSessionNewParams{ Agent: openai.BetaAgentSessionNewParamsAgent{ Model: openai.String("gpt-6-astra"), Instructions: openai.String("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."), MultiAgent: openai.MultiAgentConfigParam{ Enabled: true, }, Tools: []openai.AgentToolParamUnion{ {OfParamAutomations: &openai.AgentToolParamAutomations{}}, }, }, Environment: openai.EnvironmentParamUnion{ OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{}, }, Input: openai.BetaAgentSessionNewParamsInputUnion{ OfString: openai.String("Every day at 10 AM in America/New_York, review the goals we discuss here and suggest the next actions I could take."), }, })if err != nil { panic(err)}fmt.Println(session.ID)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27import com.openai.client.OpenAIClient;import com.openai.client.okhttp.OpenAIOkHttpClient;import com.openai.models.beta.agents.EnvironmentParam;import com.openai.models.beta.agents.MultiAgentConfigParam;import com.openai.models.beta.agents.sessions.SessionCreateParams;OpenAIClient client = OpenAIOkHttpClient.fromEnv();var session = client .beta() .agents() .sessions() .create( SessionCreateParams.builder() .agent( SessionCreateParams.Agent.builder() .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.") .multiAgent(MultiAgentConfigParam.builder().enabled(true).build()) .addToolAutomations() .build()) .environment(EnvironmentParam.OpenAIHosted.builder().build()) .input( "Every day at 10 AM in America/New_York, review the goals we discuss here and suggest the next actions I could take.") .build());System.out.println(session.id());
1
2
3
4
5
6
7
8
9
10
11
12
13
14require "openai"client = OpenAI::Client.newsession = 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.")puts session.id
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16curl https://api.openai.com/v1/agents/sessions \ -H "OpenAI-Beta: agents=v1" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "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.", "tools": [{ "type": "automations" }], "multi_agent": { "enabled": true } }, "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." }'
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
Python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15import OpenAI from "openai";const client = new OpenAI();const automation = await client.beta.agents.automations.create({ type: "once", name: "Onboarding follow-up", run_at: Math.floor(Date.now() / 1000) + 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.", },});console.log(automation);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import timefrom openai import OpenAIclient = 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())
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29import com.openai.client.OpenAIClient;import com.openai.client.okhttp.OpenAIOkHttpClient;import com.openai.models.beta.agents.automations.AutomationCreateParams;import com.openai.models.beta.agents.automations.AutomationScheduleParam;import com.openai.models.beta.agents.automations.AutomationTargetParam;import java.time.Duration;import java.time.Instant;OpenAIClient client = OpenAIOkHttpClient.fromEnv();var automation = client .beta() .agents() .automations() .create( AutomationCreateParams.builder() .automationScheduleParam( AutomationScheduleParam.Once.builder() .name("Onboarding follow-up") .runAt(Instant.now().plus(Duration.ofHours(48)).getEpochSecond()) .target( AutomationTargetParam.ExistingSession.builder() .sessionId("sess_123") .instructions( "Review onboarding progress and send the next onboarding message if the user has not completed onboarding.") .build()) .build()) .build());System.out.println(automation);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16require "openai"client = OpenAI::Client.newautomation = client.beta.agents.automations.create( create_automation_params: { type: "once", name: "Onboarding follow-up", run_at: Time.now.to_i + 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." } })puts automation.id
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18RUN_AT=$(($(date +%s) + 48 * 60 * 60))curl https://api.openai.com/v1/agents/automations \ -H "OpenAI-Beta: agents=v1" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d @- <<EOF{ "type": "once", "name": "Onboarding follow-up", "run_at": $RUN_AT, "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." } }EOF
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.
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.
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.
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.