1# Scheduled automations
2
3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.
4
5Use scheduled automations to kick off agent sessions on a cron schedule. You can also enable the `automations` tool for your agents, so they can schedule tasks in the course of their work.
6
7
8
9**Automate sessions on a cron schedule**
10
11Use a cron expression and time zone to start new sessions or continue an existing session.
12
13
14
15
16
17
18**Enable agents to create automations**
19
20Add the `automations` tool so an agent can schedule follow-ups in its current session.
21
22
23
24
25
26
27**Monitor automation invocations**
28
29Each invocation records an attempt to send a task to a session. Inspect its status and session ID.
30
31
32
33
34
35Automate sessions on a cron schedule
36
37```javascript
38import OpenAI from "openai";
39
40const client = new OpenAI();
41const automation = await client.beta.agents.automations.create({
42 type: "periodic",
43 name: "Daily session",
44 expression: "0 10 * * *",
45 timezone: "America/New_York",
46 target: {
47 type: "new_session",
48 agent_id: "agt_123",
49 environment: { type: "openai_hosted" },
50 input: [
51 {
52 role: "user",
53 content: [
54 {
55 type: "input_text",
56 text: "Summarize the current status and next steps.",
57 },
58 ],
59 },
60 ],
61 },
62});
63console.log(automation);
64```
65
66```python
67from openai import OpenAI
68
69client = OpenAI()
70automation = client.beta.agents.automations.create(
71 type="periodic",
72 name="Daily session",
73 expression="0 10 * * *",
74 timezone="America/New_York",
75 target={
76 "type": "new_session",
77 "agent_id": "agt_123",
78 "environment": {"type": "openai_hosted"},
79 "input": [
80 {
81 "role": "user",
82 "content": [
83 {
84 "type": "input_text",
85 "text": "Summarize the current status and next steps.",
86 }
87 ],
88 }
89 ],
90 },
91)
92print(automation.to_json())
93```
94
95```go
96import (
97 "context"
98 "fmt"
99
100 "github.com/openai/openai-go/v3"
101)
102
103ctx := context.Background()
104client := openai.NewClient()
105automation, err := client.Beta.Agents.Automations.New(ctx,
106 openai.BetaAgentAutomationNewParams{
107 CreateAutomationParams: openai.AutomationScheduleParamUnion{
108 OfParamPeriodic: &openai.AutomationScheduleParamPeriodic{
109 Name: "Daily session",
110 Expression: "0 10 * * *",
111 Timezone: "America/New_York",
112 Target: openai.AutomationTargetParamUnion{
113 OfParamNewSession: &openai.AutomationTargetParamNewSession{
114 AgentID: openai.String("agt_123"),
115 Environment: openai.EnvironmentParamUnion{
116 OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{},
117 },
118 Input: []openai.AgentSessionInputMessageParam{
119 {
120 Content: []openai.InputContentParamUnion{
121 {
122 OfParamInputText: &openai.InputContentParamInputText{
123 Text: "Summarize the current status and next steps.",
124 },
125 },
126 },
127 },
128 },
129 },
130 },
131 },
132 },
133 })
134if err != nil {
135 panic(err)
136}
137fmt.Println(automation)
138```
139
140```java
141import com.openai.client.OpenAIClient;
142import com.openai.client.okhttp.OpenAIOkHttpClient;
143import com.openai.models.beta.agents.AgentSessionInputMessageParam;
144import com.openai.models.beta.agents.EnvironmentParam;
145import com.openai.models.beta.agents.automations.AutomationCreateParams;
146import com.openai.models.beta.agents.automations.AutomationScheduleParam;
147import com.openai.models.beta.agents.automations.AutomationTargetParam;
148
149OpenAIClient client = OpenAIOkHttpClient.fromEnv();
150var automation =
151 client
152 .beta()
153 .agents()
154 .automations()
155 .create(
156 AutomationCreateParams.builder()
157 .automationScheduleParam(
158 AutomationScheduleParam.Periodic.builder()
159 .name("Daily session")
160 .expression("0 10 * * *")
161 .timezone("America/New_York")
162 .target(
163 AutomationTargetParam.NewSession.builder()
164 .agentId("agt_123")
165 .environment(EnvironmentParam.OpenAIHosted.builder().build())
166 .addInput(
167 AgentSessionInputMessageParam.builder()
168 .addInputTextContent(
169 "Summarize the current status and next steps.")
170 .build())
171 .build())
172 .build())
173 .build());
174System.out.println(automation);
175```
176
177```csharp
178using OpenAI;
179using OpenAI.Agents;
180#pragma warning disable OPENAI001
181
182string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
183AgentClient client = new OpenAIClient(key).GetAgentClient();
184AgentAutomation automation = await client.CreateAutomationAsync(
185 new AgentAutomationCreationOptions
186 {
187 Type = AgentAutomationType.Periodic,
188 Name = "Daily session",
189 Expression = "0 10 * * *",
190 Timezone = "America/New_York",
191 Target = new NewSessionAutomationTarget
192 {
193 AgentId = "agt_123",
194 Environment = new EnvironmentParamOpenaiHosted(),
195 Input =
196 [
197 new InputMessageParam(
198 [new InputContentParamInputText("Summarize the current status and next steps.")]
199 ),
200 ],
201 },
202 }
203);
204Console.WriteLine(automation.Id);
205```
206
207```ruby
208require "openai"
209
210client = OpenAI::Client.new
211automation = client.beta.agents.automations.create(
212 body: {
213 type: "periodic",
214 name: "Daily session",
215 expression: "0 10 * * *",
216 timezone: "America/New_York",
217 target: {
218 type: "new_session",
219 agent_id: "agt_123",
220 environment: { type: "openai_hosted" },
221 input: [
222 {
223 role: "user",
224 content: [
225 {
226 type: "input_text",
227 text: "Summarize the current status and next steps."
228 }
229 ]
230 }
231 ]
232 }
233 }
234)
235puts automation
236```
237
238```bash
239curl https://api.openai.com/v1/agents/automations \
240 -H "OpenAI-Beta: agents=v1" \
241 -H "Authorization: Bearer $OPENAI_API_KEY" \
242 -H "Content-Type: application/json" \
243 -d '{
244 "type": "periodic",
245 "name": "Daily session",
246 "expression": "0 10 * * *",
247 "timezone": "America/New_York",
248 "target": {
249 "type": "new_session",
250 "agent_id": "agt_123",
251 "environment": {
252 "type": "openai_hosted"
253 },
254 "input": [
255 {
256 "role": "user",
257 "content": [
258 {
259 "type": "input_text",
260 "text": "Summarize the current status and next steps."
261 }
262 ]
263 }
264 ]
265 }
266 }'
267```
268
269
270
271
272
273 Enable agents to create automations
274
275```javascript
276import OpenAI from "openai";
277
278const client = new OpenAI();
279const session = await client.beta.agents.sessions.create({
280 agent: {
281 model: "gpt-6-astra",
282 instructions:
283 "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.",
284 tools: [{ type: "automations" }],
285 multi_agent: { enabled: true },
286 },
287 environment: { type: "openai_hosted" },
288 input:
289 "Every day at 10 AM in America/New_York, review the goals we discuss here and suggest the next actions I could take.",
290});
291console.log(session.id);
292```
293
294```python
295from openai import OpenAI
296
297client = OpenAI()
298session = client.beta.agents.sessions.create(
299 agent={
300 "model": "gpt-6-astra",
301 "instructions": (
302 "Use automations to schedule tasks requested by the user. "
303 "Delegate each scheduled task to a subagent and ask for a concise result. "
304 "Keep the goal, schedule, and useful summaries in the main session. "
305 "Adjust or stop schedules when the user asks."
306 ),
307 "multi_agent": {"enabled": True},
308 "tools": [{"type": "automations"}],
309 },
310 environment={"type": "openai_hosted"},
311 input=(
312 "Every day at 10 AM in America/New_York, review the goals we discuss here "
313 "and suggest the next actions I could take."
314 ),
315)
316print(session.id)
317```
318
319```go
320import (
321 "context"
322 "fmt"
323
324 "github.com/openai/openai-go/v3"
325)
326
327ctx := context.Background()
328client := openai.NewClient()
329session, err := client.Beta.Agents.Sessions.New(ctx,
330 openai.BetaAgentSessionNewParams{
331 Agent: openai.BetaAgentSessionNewParamsAgent{
332 Model: openai.String("gpt-6-astra"),
333 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."),
334 MultiAgent: openai.MultiAgentConfigParam{
335 Enabled: true,
336 },
337 Tools: []openai.AgentToolParamUnion{
338 {OfParamAutomations: &openai.AgentToolParamAutomations{}},
339 },
340 },
341 Environment: openai.EnvironmentParamUnion{
342 OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{},
343 },
344 Input: openai.BetaAgentSessionNewParamsInputUnion{
345 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."),
346 },
347 })
348if err != nil {
349 panic(err)
350}
351fmt.Println(session.ID)
352```
353
354```java
355import com.openai.client.OpenAIClient;
356import com.openai.client.okhttp.OpenAIOkHttpClient;
357import com.openai.models.beta.agents.EnvironmentParam;
358import com.openai.models.beta.agents.MultiAgentConfigParam;
359import com.openai.models.beta.agents.sessions.SessionCreateParams;
360
361OpenAIClient client = OpenAIOkHttpClient.fromEnv();
362var session =
363 client
364 .beta()
365 .agents()
366 .sessions()
367 .create(
368 SessionCreateParams.builder()
369 .agent(
370 SessionCreateParams.Agent.builder()
371 .model("gpt-6-astra")
372 .instructions(
373 "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.")
374 .multiAgent(MultiAgentConfigParam.builder().enabled(true).build())
375 .addToolAutomations()
376 .build())
377 .environment(EnvironmentParam.OpenAIHosted.builder().build())
378 .input(
379 "Every day at 10 AM in America/New_York, review the goals we discuss here and suggest the next actions I could take.")
380 .build());
381System.out.println(session.id());
382```
383
384```csharp
385using OpenAI;
386using OpenAI.Agents;
387#pragma warning disable OPENAI001
388
389string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
390AgentClient client = new OpenAIClient(key).GetAgentClient();
391AgentSession session = await client.CreateAgentSessionAsync(
392 new AgentSessionCreationOptions
393 {
394 Agent = new SessionAgentConfigParam
395 {
396 Model = "gpt-6-astra",
397 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.",
398 MultiAgent = new MultiAgentConfigParam { Enabled = true },
399 Tools = [new AgentToolConfigParamAutomations()],
400 },
401 Environment = new EnvironmentParamOpenaiHosted(),
402 Input =
403 [
404 new InputMessageParam(
405 [new InputContentParamInputText("Every day at 10 AM in America/New_York, review the goals we discuss here and suggest the next actions I could take.")]
406 ),
407 ],
408 }
409);
410Console.WriteLine(session.Id);
411```
412
413```ruby
414require "openai"
415
416client = OpenAI::Client.new
417session = client.beta.agents.sessions.create(
418 agent: {
419 model: "gpt-6-astra",
420 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.",
421 multi_agent: { enabled: true },
422 tools: [{ type: "automations" }]
423 },
424 environment: { type: "openai_hosted" },
425 input: "Every day at 10 AM in America/New_York, review the goals we discuss here and suggest the next actions I could take."
426)
427puts session.id
428```
429
430```bash
431curl https://api.openai.com/v1/agents/sessions \
432 -H "OpenAI-Beta: agents=v1" \
433 -H "Authorization: Bearer $OPENAI_API_KEY" \
434 -H "Content-Type: application/json" \
435 -d '{
436 "agent": {
437 "model": "gpt-6-astra",
438 "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.",
439 "tools": [{ "type": "automations" }],
440 "multi_agent": { "enabled": true }
441 },
442 "environment": {
443 "type": "openai_hosted"
444 },
445 "input": "Every day at 10 AM in America/New_York, review the goals we discuss here and suggest the next actions I could take."
446 }'
447```
448
449
450
451
452
453 Monitor automation invocations
454
455```javascript
456import OpenAI from "openai";
457
458const client = new OpenAI();
459for await (const invocation of client.beta.agents.automations.invocations.list(
460 "auto_123"
461)) {
462 console.log(invocation.id, invocation.status, invocation.session_id);
463}
464```
465
466```python
467from openai import OpenAI
468
469client = OpenAI()
470invocations = client.beta.agents.automations.invocations.list(automation_id="auto_123")
471for invocation in invocations:
472 print(invocation.id, invocation.status, invocation.session_id)
473```
474
475```go
476import (
477 "context"
478 "fmt"
479
480 "github.com/openai/openai-go/v3"
481)
482
483ctx := context.Background()
484client := openai.NewClient()
485invocations := client.Beta.Agents.Automations.Invocations.ListAutoPaging(ctx, "auto_123",
486 openai.BetaAgentAutomationInvocationListParams{})
487for invocations.Next() {
488 invocation := invocations.Current()
489 fmt.Println(invocation.ID, invocation.Status, invocation.SessionID)
490}
491if err := invocations.Err(); err != nil {
492 panic(err)
493}
494```
495
496```java
497import com.openai.client.OpenAIClient;
498import com.openai.client.okhttp.OpenAIOkHttpClient;
499import com.openai.models.beta.agents.automations.invocations.InvocationListParams;
500
501OpenAIClient client = OpenAIOkHttpClient.fromEnv();
502var invocations =
503 client
504 .beta()
505 .agents()
506 .automations()
507 .invocations()
508 .list(InvocationListParams.builder().automationId("auto_123").build());
509for (var invocation : invocations.autoPager()) {
510 System.out.println(
511 invocation.id() + " " + invocation.status() + " " + invocation.sessionId());
512}
513```
514
515```csharp
516using OpenAI;
517using OpenAI.Agents;
518#pragma warning disable OPENAI001
519
520string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
521AgentClient client = new OpenAIClient(key).GetAgentClient();
522await foreach (AgentAutomationInvocation invocation in client.GetAutomationInvocationsAsync("auto_123"))
523{
524 Console.WriteLine($"{invocation.Id} {invocation.Status} {invocation.SessionId}");
525}
526```
527
528```ruby
529require "openai"
530
531client = OpenAI::Client.new
532invocations = client.beta.agents.automations.invocations.list("auto_123")
533invocations.auto_paging_each do |invocation|
534 puts "#{invocation.id} #{invocation.status} #{invocation.session_id}"
535end
536```
537
538```bash
539curl https://api.openai.com/v1/agents/automations/auto_123/invocations \
540 -H "OpenAI-Beta: agents=v1" \
541 -H "Authorization: Bearer $OPENAI_API_KEY"
542```
543
544
545
546
547
548
549
550
551## API resources
552
553
554
555
556
557
558[Agents](https://developers.openai.com/api/reference/resources/beta/subresources/agents)
559
560`/v1/agents`
561
562
563
564
565Define the instructions and tools for the task.
566
567
568
569
570
571
572
573
574[Automations](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/automations)
575
576`/v1/agents/automations`
577
578
579
580
581Save when to run and which session to use.
582
583
584
585
586
587
588
589
590[Invocations](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/automations/subresources/invocations)
591
592`/v1/agents/automations/{automation_id}/invocations`
593
594
595
596
597See when a task was sent and which session received it.
598
599
600
601
602
603
604
605
606[Sessions](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/sessions)
607
608`/v1/agents/sessions`
609
610
611
612
613Run the task with conversation history and tools.
614
615
616
617
618
619
620
621
622[Session events](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/sessions/subresources/events)
623
624`/v1/agents/sessions/{session_id}/events`
625
626
627
628
629Follow progress and collect the result.
630
631
632
633
634
635
636
637
638
639
640## Use cases
641
642### Restaurant reservations
643
644```javascript
645import OpenAI from "openai";
646
647const client = new OpenAI();
648const automation = await client.beta.agents.automations.create({
649 type: "periodic",
650 name: "Check restaurant reservations",
651 expression: "0 */2 * * *",
652 timezone: "America/New_York",
653 target: {
654 type: "existing_session",
655 session_id: "sess_123",
656 instructions:
657 "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables.",
658 },
659});
660console.log(automation);
661```
662
663```python
664from openai import OpenAI
665
666client = OpenAI()
667automation = client.beta.agents.automations.create(
668 type="periodic",
669 name="Check restaurant reservations",
670 expression="0 */2 * * *",
671 timezone="America/New_York",
672 target={
673 "type": "existing_session",
674 "session_id": "sess_123",
675 "instructions": (
676 "Check restaurant availability for our dinner plans. "
677 "Compare with earlier checks and report newly available tables."
678 ),
679 },
680)
681print(automation.to_json())
682```
683
684```go
685import (
686 "context"
687 "fmt"
688
689 "github.com/openai/openai-go/v3"
690)
691
692ctx := context.Background()
693client := openai.NewClient()
694automation, err := client.Beta.Agents.Automations.New(ctx,
695 openai.BetaAgentAutomationNewParams{
696 CreateAutomationParams: openai.AutomationScheduleParamUnion{
697 OfParamPeriodic: &openai.AutomationScheduleParamPeriodic{
698 Name: "Check restaurant reservations",
699 Expression: "0 */2 * * *",
700 Timezone: "America/New_York",
701 Target: openai.AutomationTargetParamUnion{
702 OfParamExistingSession: &openai.AutomationTargetParamExistingSession{
703 SessionID: "sess_123",
704 Instructions: "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables.",
705 },
706 },
707 },
708 },
709 })
710if err != nil {
711 panic(err)
712}
713fmt.Println(automation)
714```
715
716```java
717import com.openai.client.OpenAIClient;
718import com.openai.client.okhttp.OpenAIOkHttpClient;
719import com.openai.models.beta.agents.automations.AutomationCreateParams;
720import com.openai.models.beta.agents.automations.AutomationScheduleParam;
721import com.openai.models.beta.agents.automations.AutomationTargetParam;
722
723OpenAIClient client = OpenAIOkHttpClient.fromEnv();
724var automation =
725 client
726 .beta()
727 .agents()
728 .automations()
729 .create(
730 AutomationCreateParams.builder()
731 .automationScheduleParam(
732 AutomationScheduleParam.Periodic.builder()
733 .name("Check restaurant reservations")
734 .expression("0 */2 * * *")
735 .timezone("America/New_York")
736 .target(
737 AutomationTargetParam.ExistingSession.builder()
738 .sessionId("sess_123")
739 .instructions(
740 "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables.")
741 .build())
742 .build())
743 .build());
744System.out.println(automation);
745```
746
747```csharp
748using OpenAI;
749using OpenAI.Agents;
750#pragma warning disable OPENAI001
751
752string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
753AgentClient client = new OpenAIClient(key).GetAgentClient();
754AgentAutomation automation = await client.CreateAutomationAsync(
755 new AgentAutomationCreationOptions
756 {
757 Type = AgentAutomationType.Periodic,
758 Name = "Check restaurant reservations",
759 Expression = "0 */2 * * *",
760 Timezone = "America/New_York",
761 Target = new ExistingSessionAutomationTarget
762 {
763 SessionId = "sess_123",
764 Instructions = "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables.",
765 },
766 }
767);
768Console.WriteLine(automation.Id);
769```
770
771```ruby
772require "openai"
773
774client = OpenAI::Client.new
775automation = client.beta.agents.automations.create(
776 body: {
777 type: "periodic",
778 name: "Check restaurant reservations",
779 expression: "0 */2 * * *",
780 timezone: "America/New_York",
781 target: {
782 type: "existing_session",
783 session_id: "sess_123",
784 instructions: "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables."
785 }
786 }
787)
788puts automation
789```
790
791```bash
792curl https://api.openai.com/v1/agents/automations \
793 -H "OpenAI-Beta: agents=v1" \
794 -H "Authorization: Bearer $OPENAI_API_KEY" \
795 -H "Content-Type: application/json" \
796 -d '{
797 "type": "periodic",
798 "name": "Check restaurant reservations",
799 "expression": "0 */2 * * *",
800 "timezone": "America/New_York",
801 "target": {
802 "type": "existing_session",
803 "session_id": "sess_123",
804 "instructions": "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables."
805 }
806 }'
807```
808
809### Monthly spending
810
811```javascript
812import OpenAI from "openai";
813
814const client = new OpenAI();
815const automation = await client.beta.agents.automations.create({
816 type: "periodic",
817 name: "Monthly spending review",
818 expression: "0 9 1 * *",
819 timezone: "America/New_York",
820 target: {
821 type: "new_session",
822 agent_id: "agt_123",
823 environment: { type: "openai_hosted" },
824 input: [
825 {
826 role: "user",
827 content: [
828 {
829 type: "input_text",
830 text: "Review my spending for the previous month. Flag unused subscriptions, price increases, and other potential savings for me to review.",
831 },
832 ],
833 },
834 ],
835 },
836});
837console.log(automation);
838```
839
840```python
841from openai import OpenAI
842
843client = OpenAI()
844automation = client.beta.agents.automations.create(
845 type="periodic",
846 name="Monthly spending review",
847 expression="0 9 1 * *",
848 timezone="America/New_York",
849 target={
850 "type": "new_session",
851 "agent_id": "agt_123",
852 "environment": {"type": "openai_hosted"},
853 "input": [
854 {
855 "role": "user",
856 "content": [
857 {
858 "type": "input_text",
859 "text": (
860 "Review my spending for the previous month. Flag unused "
861 "subscriptions, price increases, and other potential "
862 "savings for me to review."
863 ),
864 }
865 ],
866 }
867 ],
868 },
869)
870print(automation.to_json())
871```
872
873```go
874import (
875 "context"
876 "fmt"
877
878 "github.com/openai/openai-go/v3"
879)
880
881ctx := context.Background()
882client := openai.NewClient()
883automation, err := client.Beta.Agents.Automations.New(ctx,
884 openai.BetaAgentAutomationNewParams{
885 CreateAutomationParams: openai.AutomationScheduleParamUnion{
886 OfParamPeriodic: &openai.AutomationScheduleParamPeriodic{
887 Name: "Monthly spending review",
888 Expression: "0 9 1 * *",
889 Timezone: "America/New_York",
890 Target: openai.AutomationTargetParamUnion{
891 OfParamNewSession: &openai.AutomationTargetParamNewSession{
892 AgentID: openai.String("agt_123"),
893 Environment: openai.EnvironmentParamUnion{
894 OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{},
895 },
896 Input: []openai.AgentSessionInputMessageParam{
897 {
898 Content: []openai.InputContentParamUnion{
899 {
900 OfParamInputText: &openai.InputContentParamInputText{
901 Text: "Review my spending for the previous month. Flag unused subscriptions, price increases, and other potential savings for me to review.",
902 },
903 },
904 },
905 },
906 },
907 },
908 },
909 },
910 },
911 })
912if err != nil {
913 panic(err)
914}
915fmt.Println(automation)
916```
917
918```java
919import com.openai.client.OpenAIClient;
920import com.openai.client.okhttp.OpenAIOkHttpClient;
921import com.openai.models.beta.agents.AgentSessionInputMessageParam;
922import com.openai.models.beta.agents.EnvironmentParam;
923import com.openai.models.beta.agents.automations.AutomationCreateParams;
924import com.openai.models.beta.agents.automations.AutomationScheduleParam;
925import com.openai.models.beta.agents.automations.AutomationTargetParam;
926
927OpenAIClient client = OpenAIOkHttpClient.fromEnv();
928var automation =
929 client
930 .beta()
931 .agents()
932 .automations()
933 .create(
934 AutomationCreateParams.builder()
935 .automationScheduleParam(
936 AutomationScheduleParam.Periodic.builder()
937 .name("Monthly spending review")
938 .expression("0 9 1 * *")
939 .timezone("America/New_York")
940 .target(
941 AutomationTargetParam.NewSession.builder()
942 .agentId("agt_123")
943 .environment(EnvironmentParam.OpenAIHosted.builder().build())
944 .addInput(
945 AgentSessionInputMessageParam.builder()
946 .addInputTextContent(
947 "Review my spending for the previous month. Flag unused subscriptions, price increases, and other potential savings for me to review.")
948 .build())
949 .build())
950 .build())
951 .build());
952System.out.println(automation);
953```
954
955```csharp
956using OpenAI;
957using OpenAI.Agents;
958#pragma warning disable OPENAI001
959
960string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
961AgentClient client = new OpenAIClient(key).GetAgentClient();
962AgentAutomation automation = await client.CreateAutomationAsync(
963 new AgentAutomationCreationOptions
964 {
965 Type = AgentAutomationType.Periodic,
966 Name = "Monthly spending review",
967 Expression = "0 9 1 * *",
968 Timezone = "America/New_York",
969 Target = new NewSessionAutomationTarget
970 {
971 AgentId = "agt_123",
972 Environment = new EnvironmentParamOpenaiHosted(),
973 Input =
974 [
975 new InputMessageParam(
976 [new InputContentParamInputText("Review my spending for the previous month. Flag unused subscriptions, price increases, and other potential savings for me to review.")]
977 ),
978 ],
979 },
980 }
981);
982Console.WriteLine(automation.Id);
983```
984
985```ruby
986require "openai"
987
988client = OpenAI::Client.new
989automation = client.beta.agents.automations.create(
990 body: {
991 type: "periodic",
992 name: "Monthly spending review",
993 expression: "0 9 1 * *",
994 timezone: "America/New_York",
995 target: {
996 type: "new_session",
997 agent_id: "agt_123",
998 environment: { type: "openai_hosted" },
999 input: [
1000 {
1001 role: "user",
1002 content: [
1003 {
1004 type: "input_text",
1005 text: "Review my spending for the previous month. Flag unused subscriptions, price increases, and other potential savings for me to review."
1006 }
1007 ]
1008 }
1009 ]
1010 }
1011 }
1012)
1013puts automation
1014```
1015
1016```bash
1017curl https://api.openai.com/v1/agents/automations \
1018 -H "OpenAI-Beta: agents=v1" \
1019 -H "Authorization: Bearer $OPENAI_API_KEY" \
1020 -H "Content-Type: application/json" \
1021 -d '{
1022 "type": "periodic",
1023 "name": "Monthly spending review",
1024 "expression": "0 9 1 * *",
1025 "timezone": "America/New_York",
1026 "target": {
1027 "type": "new_session",
1028 "agent_id": "agt_123",
1029 "environment": {
1030 "type": "openai_hosted"
1031 },
1032 "input": [
1033 {
1034 "role": "user",
1035 "content": [
1036 {
1037 "type": "input_text",
1038 "text": "Review my spending for the previous month. Flag unused subscriptions, price increases, and other potential savings for me to review."
1039 }
1040 ]
1041 }
1042 ]
1043 }
1044 }'
1045```
1046
1047### Daily actions
1048
1049```javascript
1050import OpenAI from "openai";
1051
1052const client = new OpenAI();
1053const automation = await client.beta.agents.automations.create({
1054 type: "periodic",
1055 name: "Daily suggestions",
1056 expression: "0 10 * * *",
1057 timezone: "America/New_York",
1058 target: {
1059 type: "new_session",
1060 agent_id: "agt_123",
1061 environment: { type: "openai_hosted" },
1062 input: [
1063 {
1064 role: "user",
1065 content: [
1066 {
1067 type: "input_text",
1068 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.",
1069 },
1070 ],
1071 },
1072 ],
1073 },
1074});
1075console.log(automation);
1076```
1077
1078```python
1079from openai import OpenAI
1080
1081client = OpenAI()
1082automation = client.beta.agents.automations.create(
1083 type="periodic",
1084 name="Daily suggestions",
1085 expression="0 10 * * *",
1086 timezone="America/New_York",
1087 target={
1088 "type": "new_session",
1089 "agent_id": "agt_123",
1090 "environment": {"type": "openai_hosted"},
1091 "input": [
1092 {
1093 "role": "user",
1094 "content": [
1095 {
1096 "type": "input_text",
1097 "text": (
1098 "Review my calendar, tasks, and recent messages for today. "
1099 "Suggest the most useful actions I could take today, "
1100 "with a short reason for each."
1101 ),
1102 }
1103 ],
1104 }
1105 ],
1106 },
1107)
1108print(automation.to_json())
1109```
1110
1111```go
1112import (
1113 "context"
1114 "fmt"
1115
1116 "github.com/openai/openai-go/v3"
1117)
1118
1119ctx := context.Background()
1120client := openai.NewClient()
1121automation, err := client.Beta.Agents.Automations.New(ctx,
1122 openai.BetaAgentAutomationNewParams{
1123 CreateAutomationParams: openai.AutomationScheduleParamUnion{
1124 OfParamPeriodic: &openai.AutomationScheduleParamPeriodic{
1125 Name: "Daily suggestions",
1126 Expression: "0 10 * * *",
1127 Timezone: "America/New_York",
1128 Target: openai.AutomationTargetParamUnion{
1129 OfParamNewSession: &openai.AutomationTargetParamNewSession{
1130 AgentID: openai.String("agt_123"),
1131 Environment: openai.EnvironmentParamUnion{
1132 OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{},
1133 },
1134 Input: []openai.AgentSessionInputMessageParam{
1135 {
1136 Content: []openai.InputContentParamUnion{
1137 {
1138 OfParamInputText: &openai.InputContentParamInputText{
1139 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.",
1140 },
1141 },
1142 },
1143 },
1144 },
1145 },
1146 },
1147 },
1148 },
1149 })
1150if err != nil {
1151 panic(err)
1152}
1153fmt.Println(automation)
1154```
1155
1156```java
1157import com.openai.client.OpenAIClient;
1158import com.openai.client.okhttp.OpenAIOkHttpClient;
1159import com.openai.models.beta.agents.AgentSessionInputMessageParam;
1160import com.openai.models.beta.agents.EnvironmentParam;
1161import com.openai.models.beta.agents.automations.AutomationCreateParams;
1162import com.openai.models.beta.agents.automations.AutomationScheduleParam;
1163import com.openai.models.beta.agents.automations.AutomationTargetParam;
1164
1165OpenAIClient client = OpenAIOkHttpClient.fromEnv();
1166var automation =
1167 client
1168 .beta()
1169 .agents()
1170 .automations()
1171 .create(
1172 AutomationCreateParams.builder()
1173 .automationScheduleParam(
1174 AutomationScheduleParam.Periodic.builder()
1175 .name("Daily suggestions")
1176 .expression("0 10 * * *")
1177 .timezone("America/New_York")
1178 .target(
1179 AutomationTargetParam.NewSession.builder()
1180 .agentId("agt_123")
1181 .environment(EnvironmentParam.OpenAIHosted.builder().build())
1182 .addInput(
1183 AgentSessionInputMessageParam.builder()
1184 .addInputTextContent(
1185 "Review my calendar, tasks, and recent messages for today. Suggest the most useful actions I could take today, with a short reason for each.")
1186 .build())
1187 .build())
1188 .build())
1189 .build());
1190System.out.println(automation);
1191```
1192
1193```csharp
1194using OpenAI;
1195using OpenAI.Agents;
1196#pragma warning disable OPENAI001
1197
1198string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
1199AgentClient client = new OpenAIClient(key).GetAgentClient();
1200AgentAutomation automation = await client.CreateAutomationAsync(
1201 new AgentAutomationCreationOptions
1202 {
1203 Type = AgentAutomationType.Periodic,
1204 Name = "Daily suggestions",
1205 Expression = "0 10 * * *",
1206 Timezone = "America/New_York",
1207 Target = new NewSessionAutomationTarget
1208 {
1209 AgentId = "agt_123",
1210 Environment = new EnvironmentParamOpenaiHosted(),
1211 Input =
1212 [
1213 new InputMessageParam(
1214 [new InputContentParamInputText("Review my calendar, tasks, and recent messages for today. Suggest the most useful actions I could take today, with a short reason for each.")]
1215 ),
1216 ],
1217 },
1218 }
1219);
1220Console.WriteLine(automation.Id);
1221```
1222
1223```ruby
1224require "openai"
1225
1226client = OpenAI::Client.new
1227automation = client.beta.agents.automations.create(
1228 body: {
1229 type: "periodic",
1230 name: "Daily suggestions",
1231 expression: "0 10 * * *",
1232 timezone: "America/New_York",
1233 target: {
1234 type: "new_session",
1235 agent_id: "agt_123",
1236 environment: { type: "openai_hosted" },
1237 input: [
1238 {
1239 role: "user",
1240 content: [
1241 {
1242 type: "input_text",
1243 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."
1244 }
1245 ]
1246 }
1247 ]
1248 }
1249 }
1250)
1251puts automation
1252```
1253
1254```bash
1255curl https://api.openai.com/v1/agents/automations \
1256 -H "OpenAI-Beta: agents=v1" \
1257 -H "Authorization: Bearer $OPENAI_API_KEY" \
1258 -H "Content-Type: application/json" \
1259 -d '{
1260 "type": "periodic",
1261 "name": "Daily suggestions",
1262 "expression": "0 10 * * *",
1263 "timezone": "America/New_York",
1264 "target": {
1265 "type": "new_session",
1266 "agent_id": "agt_123",
1267 "environment": {
1268 "type": "openai_hosted"
1269 },
1270 "input": [
1271 {
1272 "role": "user",
1273 "content": [
1274 {
1275 "type": "input_text",
1276 "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."
1277 }
1278 ]
1279 }
1280 ]
1281 }
1282 }'
1283```
1284
1285
1286
1287## How it works
1288
1289An automation is a saved schedule for agent work. The Agents API stores the schedule and sends each task to its target session:
1290
12911. **Define the work.** Choose when it should run and whether each run starts a new session or continues an existing one.
12922. **Send the task.** Each run creates an **invocation**, a record of the attempt to send the task to its target session. If that session is busy, the task waits.
12933. **Follow the result.** The agent works with the session's tools and context. Follow session events to track progress and collect results. The session receiving the task doesn't mean the agent has finished the work.
1294
1295Your application can create, update, pause, or delete schedules through the API. With the `automations` tool enabled, an agent can also schedule its own next check in its current session.
1296
1297## Choose the session and schedule
1298
1299Choose a target based on whether the task needs earlier conversation history:
1300
1301| Target | Use it for | Required configuration |
1302| ------------------ | ---------------------------------------------------------- | ----------------------------------------------------------------- |
1303| `new_session` | Independent work, such as a monthly spending review. | An agent, an environment, and initial messages in `target.input`. |
1304| `existing_session` | Follow-up work that needs the session's previous findings. | A session ID and reminder text in `target.instructions`. |
1305
1306Choose timing independently of the target:
1307
1308| Type | Timing fields | Example |
1309| ---------- | --------------------------- | -------------------------------------------------------------------- |
1310| `periodic` | `expression` and `timezone` | Every day at 10 AM in `America/New_York`. |
1311| `once` | `run_at` | One check at a future time specified as a Unix timestamp in seconds. |
1312
1313Both schedule types work with either target. Creating an automation saves it with status `active`; it doesn't run the task immediately. A periodic automation's first occurrence is scheduled for the next matching time.
1314
1315## Schedule daily suggestions
1316
1317Before creating the automation, create an agent with instructions and tools for the task, including access to the user's calendar, tasks, and messages. See [Reuse an agent across sessions](https://developers.openai.com/api/docs/guides/agents-api/configuration#reuse-an-agent-across-sessions).
1318
1319The SDKs include the `OpenAI-Beta: agents=v1` header; include it when calling the API with cURL.
1320
1321Here's an example of how to create an automation to start a new session for 10 AM each day in New York:
1322
1323Schedule daily suggestions
1324
1325```javascript
1326import OpenAI from "openai";
1327
1328const client = new OpenAI();
1329const automation = await client.beta.agents.automations.create({
1330 type: "periodic",
1331 name: "Daily suggestions",
1332 expression: "0 10 * * *",
1333 timezone: "America/New_York",
1334 target: {
1335 type: "new_session",
1336 agent_id: "agt_123",
1337 environment: { type: "openai_hosted" },
1338 input: [
1339 {
1340 role: "user",
1341 content: [
1342 {
1343 type: "input_text",
1344 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.",
1345 },
1346 ],
1347 },
1348 ],
1349 },
1350});
1351console.log(automation);
1352```
1353
1354```python
1355from openai import OpenAI
1356
1357client = OpenAI()
1358automation = client.beta.agents.automations.create(
1359 type="periodic",
1360 name="Daily suggestions",
1361 expression="0 10 * * *",
1362 timezone="America/New_York",
1363 target={
1364 "type": "new_session",
1365 "agent_id": "agt_123",
1366 "environment": {"type": "openai_hosted"},
1367 "input": [
1368 {
1369 "role": "user",
1370 "content": [
1371 {
1372 "type": "input_text",
1373 "text": (
1374 "Review my calendar, tasks, and recent messages for today. "
1375 "Suggest the most useful actions I could take today, "
1376 "with a short reason for each."
1377 ),
1378 }
1379 ],
1380 }
1381 ],
1382 },
1383)
1384print(automation.to_json())
1385```
1386
1387```go
1388import (
1389 "context"
1390 "fmt"
1391
1392 "github.com/openai/openai-go/v3"
1393)
1394
1395ctx := context.Background()
1396client := openai.NewClient()
1397automation, err := client.Beta.Agents.Automations.New(ctx,
1398 openai.BetaAgentAutomationNewParams{
1399 CreateAutomationParams: openai.AutomationScheduleParamUnion{
1400 OfParamPeriodic: &openai.AutomationScheduleParamPeriodic{
1401 Name: "Daily suggestions",
1402 Expression: "0 10 * * *",
1403 Timezone: "America/New_York",
1404 Target: openai.AutomationTargetParamUnion{
1405 OfParamNewSession: &openai.AutomationTargetParamNewSession{
1406 AgentID: openai.String("agt_123"),
1407 Environment: openai.EnvironmentParamUnion{
1408 OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{},
1409 },
1410 Input: []openai.AgentSessionInputMessageParam{
1411 {
1412 Content: []openai.InputContentParamUnion{
1413 {
1414 OfParamInputText: &openai.InputContentParamInputText{
1415 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.",
1416 },
1417 },
1418 },
1419 },
1420 },
1421 },
1422 },
1423 },
1424 },
1425 })
1426if err != nil {
1427 panic(err)
1428}
1429fmt.Println(automation)
1430```
1431
1432```java
1433import com.openai.client.OpenAIClient;
1434import com.openai.client.okhttp.OpenAIOkHttpClient;
1435import com.openai.models.beta.agents.AgentSessionInputMessageParam;
1436import com.openai.models.beta.agents.EnvironmentParam;
1437import com.openai.models.beta.agents.automations.AutomationCreateParams;
1438import com.openai.models.beta.agents.automations.AutomationScheduleParam;
1439import com.openai.models.beta.agents.automations.AutomationTargetParam;
1440
1441OpenAIClient client = OpenAIOkHttpClient.fromEnv();
1442var automation =
1443 client
1444 .beta()
1445 .agents()
1446 .automations()
1447 .create(
1448 AutomationCreateParams.builder()
1449 .automationScheduleParam(
1450 AutomationScheduleParam.Periodic.builder()
1451 .name("Daily suggestions")
1452 .expression("0 10 * * *")
1453 .timezone("America/New_York")
1454 .target(
1455 AutomationTargetParam.NewSession.builder()
1456 .agentId("agt_123")
1457 .environment(EnvironmentParam.OpenAIHosted.builder().build())
1458 .addInput(
1459 AgentSessionInputMessageParam.builder()
1460 .addInputTextContent(
1461 "Review my calendar, tasks, and recent messages for today. Suggest the most useful actions I could take today, with a short reason for each.")
1462 .build())
1463 .build())
1464 .build())
1465 .build());
1466System.out.println(automation);
1467```
1468
1469```csharp
1470using OpenAI;
1471using OpenAI.Agents;
1472#pragma warning disable OPENAI001
1473
1474string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
1475AgentClient client = new OpenAIClient(key).GetAgentClient();
1476AgentAutomation automation = await client.CreateAutomationAsync(
1477 new AgentAutomationCreationOptions
1478 {
1479 Type = AgentAutomationType.Periodic,
1480 Name = "Daily suggestions",
1481 Expression = "0 10 * * *",
1482 Timezone = "America/New_York",
1483 Target = new NewSessionAutomationTarget
1484 {
1485 AgentId = "agt_123",
1486 Environment = new EnvironmentParamOpenaiHosted(),
1487 Input =
1488 [
1489 new InputMessageParam(
1490 [new InputContentParamInputText("Review my calendar, tasks, and recent messages for today. Suggest the most useful actions I could take today, with a short reason for each.")]
1491 ),
1492 ],
1493 },
1494 }
1495);
1496Console.WriteLine(automation.Id);
1497```
1498
1499```ruby
1500require "openai"
1501
1502client = OpenAI::Client.new
1503automation = client.beta.agents.automations.create(
1504 body: {
1505 type: "periodic",
1506 name: "Daily suggestions",
1507 expression: "0 10 * * *",
1508 timezone: "America/New_York",
1509 target: {
1510 type: "new_session",
1511 agent_id: "agt_123",
1512 environment: { type: "openai_hosted" },
1513 input: [
1514 {
1515 role: "user",
1516 content: [
1517 {
1518 type: "input_text",
1519 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."
1520 }
1521 ]
1522 }
1523 ]
1524 }
1525 }
1526)
1527puts automation
1528```
1529
1530```bash
1531curl https://api.openai.com/v1/agents/automations \
1532 -H "OpenAI-Beta: agents=v1" \
1533 -H "Authorization: Bearer $OPENAI_API_KEY" \
1534 -H "Content-Type: application/json" \
1535 -d '{
1536 "type": "periodic",
1537 "name": "Daily suggestions",
1538 "expression": "0 10 * * *",
1539 "timezone": "America/New_York",
1540 "target": {
1541 "type": "new_session",
1542 "agent_id": "agt_123",
1543 "environment": {
1544 "type": "openai_hosted"
1545 },
1546 "input": [
1547 {
1548 "role": "user",
1549 "content": [
1550 {
1551 "type": "input_text",
1552 "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."
1553 }
1554 ]
1555 }
1556 ]
1557 }
1558 }'
1559```
1560
1561
1562Save the returned automation `id` to inspect or manage the schedule later. Each invocation starts a new conversation. The environment configuration above provisions an [OpenAI-hosted sandbox](https://developers.openai.com/api/docs/guides/agents-api/environments/openai-hosted) for that session.
1563
1564You can supply inline agent configuration in `target.agent` instead of a saved `target.agent_id`. Supply exactly one of these fields. Put the initial messages inside `target.input`, not at the top level of the request. Include at least one message with nonempty text or an image URL.
1565
1566### Review spending each month
1567
1568The same approach works for a monthly spending review. Give the saved agent access to the user's financial records, then schedule a new session for 9 AM on the first day of each month:
1569
1570Schedule a monthly spending review
1571
1572```javascript
1573import OpenAI from "openai";
1574
1575const client = new OpenAI();
1576const automation = await client.beta.agents.automations.create({
1577 type: "periodic",
1578 name: "Monthly spending review",
1579 expression: "0 9 1 * *",
1580 timezone: "America/New_York",
1581 target: {
1582 type: "new_session",
1583 agent_id: "agt_123",
1584 environment: { type: "openai_hosted" },
1585 input: [
1586 {
1587 role: "user",
1588 content: [
1589 {
1590 type: "input_text",
1591 text: "Review my spending for the previous month. Flag unused subscriptions, price increases, and other potential savings for me to review.",
1592 },
1593 ],
1594 },
1595 ],
1596 },
1597});
1598console.log(automation);
1599```
1600
1601```python
1602from openai import OpenAI
1603
1604client = OpenAI()
1605automation = client.beta.agents.automations.create(
1606 type="periodic",
1607 name="Monthly spending review",
1608 expression="0 9 1 * *",
1609 timezone="America/New_York",
1610 target={
1611 "type": "new_session",
1612 "agent_id": "agt_123",
1613 "environment": {"type": "openai_hosted"},
1614 "input": [
1615 {
1616 "role": "user",
1617 "content": [
1618 {
1619 "type": "input_text",
1620 "text": (
1621 "Review my spending for the previous month. Flag unused "
1622 "subscriptions, price increases, and other potential "
1623 "savings for me to review."
1624 ),
1625 }
1626 ],
1627 }
1628 ],
1629 },
1630)
1631print(automation.to_json())
1632```
1633
1634```go
1635import (
1636 "context"
1637 "fmt"
1638
1639 "github.com/openai/openai-go/v3"
1640)
1641
1642ctx := context.Background()
1643client := openai.NewClient()
1644automation, err := client.Beta.Agents.Automations.New(ctx,
1645 openai.BetaAgentAutomationNewParams{
1646 CreateAutomationParams: openai.AutomationScheduleParamUnion{
1647 OfParamPeriodic: &openai.AutomationScheduleParamPeriodic{
1648 Name: "Monthly spending review",
1649 Expression: "0 9 1 * *",
1650 Timezone: "America/New_York",
1651 Target: openai.AutomationTargetParamUnion{
1652 OfParamNewSession: &openai.AutomationTargetParamNewSession{
1653 AgentID: openai.String("agt_123"),
1654 Environment: openai.EnvironmentParamUnion{
1655 OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{},
1656 },
1657 Input: []openai.AgentSessionInputMessageParam{
1658 {
1659 Content: []openai.InputContentParamUnion{
1660 {
1661 OfParamInputText: &openai.InputContentParamInputText{
1662 Text: "Review my spending for the previous month. Flag unused subscriptions, price increases, and other potential savings for me to review.",
1663 },
1664 },
1665 },
1666 },
1667 },
1668 },
1669 },
1670 },
1671 },
1672 })
1673if err != nil {
1674 panic(err)
1675}
1676fmt.Println(automation)
1677```
1678
1679```java
1680import com.openai.client.OpenAIClient;
1681import com.openai.client.okhttp.OpenAIOkHttpClient;
1682import com.openai.models.beta.agents.AgentSessionInputMessageParam;
1683import com.openai.models.beta.agents.EnvironmentParam;
1684import com.openai.models.beta.agents.automations.AutomationCreateParams;
1685import com.openai.models.beta.agents.automations.AutomationScheduleParam;
1686import com.openai.models.beta.agents.automations.AutomationTargetParam;
1687
1688OpenAIClient client = OpenAIOkHttpClient.fromEnv();
1689var automation =
1690 client
1691 .beta()
1692 .agents()
1693 .automations()
1694 .create(
1695 AutomationCreateParams.builder()
1696 .automationScheduleParam(
1697 AutomationScheduleParam.Periodic.builder()
1698 .name("Monthly spending review")
1699 .expression("0 9 1 * *")
1700 .timezone("America/New_York")
1701 .target(
1702 AutomationTargetParam.NewSession.builder()
1703 .agentId("agt_123")
1704 .environment(EnvironmentParam.OpenAIHosted.builder().build())
1705 .addInput(
1706 AgentSessionInputMessageParam.builder()
1707 .addInputTextContent(
1708 "Review my spending for the previous month. Flag unused subscriptions, price increases, and other potential savings for me to review.")
1709 .build())
1710 .build())
1711 .build())
1712 .build());
1713System.out.println(automation);
1714```
1715
1716```csharp
1717using OpenAI;
1718using OpenAI.Agents;
1719#pragma warning disable OPENAI001
1720
1721string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
1722AgentClient client = new OpenAIClient(key).GetAgentClient();
1723AgentAutomation automation = await client.CreateAutomationAsync(
1724 new AgentAutomationCreationOptions
1725 {
1726 Type = AgentAutomationType.Periodic,
1727 Name = "Monthly spending review",
1728 Expression = "0 9 1 * *",
1729 Timezone = "America/New_York",
1730 Target = new NewSessionAutomationTarget
1731 {
1732 AgentId = "agt_123",
1733 Environment = new EnvironmentParamOpenaiHosted(),
1734 Input =
1735 [
1736 new InputMessageParam(
1737 [new InputContentParamInputText("Review my spending for the previous month. Flag unused subscriptions, price increases, and other potential savings for me to review.")]
1738 ),
1739 ],
1740 },
1741 }
1742);
1743Console.WriteLine(automation.Id);
1744```
1745
1746```ruby
1747require "openai"
1748
1749client = OpenAI::Client.new
1750automation = client.beta.agents.automations.create(
1751 body: {
1752 type: "periodic",
1753 name: "Monthly spending review",
1754 expression: "0 9 1 * *",
1755 timezone: "America/New_York",
1756 target: {
1757 type: "new_session",
1758 agent_id: "agt_123",
1759 environment: { type: "openai_hosted" },
1760 input: [
1761 {
1762 role: "user",
1763 content: [
1764 {
1765 type: "input_text",
1766 text: "Review my spending for the previous month. Flag unused subscriptions, price increases, and other potential savings for me to review."
1767 }
1768 ]
1769 }
1770 ]
1771 }
1772 }
1773)
1774puts automation
1775```
1776
1777```bash
1778curl https://api.openai.com/v1/agents/automations \
1779 -H "OpenAI-Beta: agents=v1" \
1780 -H "Authorization: Bearer $OPENAI_API_KEY" \
1781 -H "Content-Type: application/json" \
1782 -d '{
1783 "type": "periodic",
1784 "name": "Monthly spending review",
1785 "expression": "0 9 1 * *",
1786 "timezone": "America/New_York",
1787 "target": {
1788 "type": "new_session",
1789 "agent_id": "agt_123",
1790 "environment": {
1791 "type": "openai_hosted"
1792 },
1793 "input": [
1794 {
1795 "role": "user",
1796 "content": [
1797 {
1798 "type": "input_text",
1799 "text": "Review my spending for the previous month. Flag unused subscriptions, price increases, and other potential savings for me to review."
1800 }
1801 ]
1802 }
1803 ]
1804 }
1805 }'
1806```
1807
1808
1809### Set recurring timing
1810
1811Use a five-field cron expression with a named time zone:
1812
1813| Expression | Schedule |
1814| ----------------- | ------------------------------- |
1815| `0 10 * * *` | Every day at 10 AM |
1816| `0 */2 * * *` | Every two hours |
1817| `0 9 1 * *` | First day of each month at 9 AM |
1818| `0 9 * * MON-FRI` | Monday through Friday at 9 AM |
1819
1820The time zone determines how to interpret the expression. Use `UTC` for a UTC schedule or an IANA time zone such as `America/New_York` for a local schedule. Don't include `run_at` in a periodic automation.
1821
1822A cron schedule follows clock times in the selected time zone. For example, `0 */3 * * *` schedules runs at midnight, 3 AM, 6 AM, and every three hours after that, rather than every three hours from creation.
1823
1824The schedule specifies the intended time. The Agents API adds a small randomized delay to recurring runs to spread load. The task can wait longer if the target session is busy.
1825
1826## Continue an existing session
1827
1828Use an existing session when the agent needs earlier findings, messages, or saved work. For example, a session planning dinner can keep the restaurant preferences and results from earlier availability checks.
1829
1830Here's how to check for restaurant reservations every two hours in that session:
1831
1832Check restaurant reservations
1833
1834```javascript
1835import OpenAI from "openai";
1836
1837const client = new OpenAI();
1838const automation = await client.beta.agents.automations.create({
1839 type: "periodic",
1840 name: "Check restaurant reservations",
1841 expression: "0 */2 * * *",
1842 timezone: "America/New_York",
1843 target: {
1844 type: "existing_session",
1845 session_id: "sess_123",
1846 instructions:
1847 "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables.",
1848 },
1849});
1850console.log(automation);
1851```
1852
1853```python
1854from openai import OpenAI
1855
1856client = OpenAI()
1857automation = client.beta.agents.automations.create(
1858 type="periodic",
1859 name="Check restaurant reservations",
1860 expression="0 */2 * * *",
1861 timezone="America/New_York",
1862 target={
1863 "type": "existing_session",
1864 "session_id": "sess_123",
1865 "instructions": (
1866 "Check restaurant availability for our dinner plans. "
1867 "Compare with earlier checks and report newly available tables."
1868 ),
1869 },
1870)
1871print(automation.to_json())
1872```
1873
1874```go
1875import (
1876 "context"
1877 "fmt"
1878
1879 "github.com/openai/openai-go/v3"
1880)
1881
1882ctx := context.Background()
1883client := openai.NewClient()
1884automation, err := client.Beta.Agents.Automations.New(ctx,
1885 openai.BetaAgentAutomationNewParams{
1886 CreateAutomationParams: openai.AutomationScheduleParamUnion{
1887 OfParamPeriodic: &openai.AutomationScheduleParamPeriodic{
1888 Name: "Check restaurant reservations",
1889 Expression: "0 */2 * * *",
1890 Timezone: "America/New_York",
1891 Target: openai.AutomationTargetParamUnion{
1892 OfParamExistingSession: &openai.AutomationTargetParamExistingSession{
1893 SessionID: "sess_123",
1894 Instructions: "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables.",
1895 },
1896 },
1897 },
1898 },
1899 })
1900if err != nil {
1901 panic(err)
1902}
1903fmt.Println(automation)
1904```
1905
1906```java
1907import com.openai.client.OpenAIClient;
1908import com.openai.client.okhttp.OpenAIOkHttpClient;
1909import com.openai.models.beta.agents.automations.AutomationCreateParams;
1910import com.openai.models.beta.agents.automations.AutomationScheduleParam;
1911import com.openai.models.beta.agents.automations.AutomationTargetParam;
1912
1913OpenAIClient client = OpenAIOkHttpClient.fromEnv();
1914var automation =
1915 client
1916 .beta()
1917 .agents()
1918 .automations()
1919 .create(
1920 AutomationCreateParams.builder()
1921 .automationScheduleParam(
1922 AutomationScheduleParam.Periodic.builder()
1923 .name("Check restaurant reservations")
1924 .expression("0 */2 * * *")
1925 .timezone("America/New_York")
1926 .target(
1927 AutomationTargetParam.ExistingSession.builder()
1928 .sessionId("sess_123")
1929 .instructions(
1930 "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables.")
1931 .build())
1932 .build())
1933 .build());
1934System.out.println(automation);
1935```
1936
1937```csharp
1938using OpenAI;
1939using OpenAI.Agents;
1940#pragma warning disable OPENAI001
1941
1942string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
1943AgentClient client = new OpenAIClient(key).GetAgentClient();
1944AgentAutomation automation = await client.CreateAutomationAsync(
1945 new AgentAutomationCreationOptions
1946 {
1947 Type = AgentAutomationType.Periodic,
1948 Name = "Check restaurant reservations",
1949 Expression = "0 */2 * * *",
1950 Timezone = "America/New_York",
1951 Target = new ExistingSessionAutomationTarget
1952 {
1953 SessionId = "sess_123",
1954 Instructions = "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables.",
1955 },
1956 }
1957);
1958Console.WriteLine(automation.Id);
1959```
1960
1961```ruby
1962require "openai"
1963
1964client = OpenAI::Client.new
1965automation = client.beta.agents.automations.create(
1966 body: {
1967 type: "periodic",
1968 name: "Check restaurant reservations",
1969 expression: "0 */2 * * *",
1970 timezone: "America/New_York",
1971 target: {
1972 type: "existing_session",
1973 session_id: "sess_123",
1974 instructions: "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables."
1975 }
1976 }
1977)
1978puts automation
1979```
1980
1981```bash
1982curl https://api.openai.com/v1/agents/automations \
1983 -H "OpenAI-Beta: agents=v1" \
1984 -H "Authorization: Bearer $OPENAI_API_KEY" \
1985 -H "Content-Type: application/json" \
1986 -d '{
1987 "type": "periodic",
1988 "name": "Check restaurant reservations",
1989 "expression": "0 */2 * * *",
1990 "timezone": "America/New_York",
1991 "target": {
1992 "type": "existing_session",
1993 "session_id": "sess_123",
1994 "instructions": "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables."
1995 }
1996 }'
1997```
1998
1999
2000Each invocation delivers the saved instructions as an automation notification to the same session, using its current agent configuration and saved state. The notification is separate from a new user message.
2001
2002If the session is working, delivery waits for it to become available. A scheduled run doesn't interrupt the active turn or supply a missing tool result or approval. Your application must still [handle required actions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage#handle-required-actions).
2003
2004### Schedule one check
2005
2006For a single follow-up, use `type: "once"` with `run_at`. The value must be an integer Unix timestamp in **seconds** that is in the future. Don't include `expression` or `timezone`.
2007
2008Schedule a check at **January 1, 2027, at 9 AM UTC**:
2009
2010Schedule an agent to run once
2011
2012```javascript
2013import OpenAI from "openai";
2014
2015const client = new OpenAI();
2016const automation = await client.beta.agents.automations.create({
2017 type: "once",
2018 name: "Check restaurant reply",
2019 run_at: 1798794000,
2020 target: {
2021 type: "existing_session",
2022 session_id: "sess_123",
2023 instructions:
2024 "Check whether the restaurant replied about our booking. Summarize any changes to the dinner plans.",
2025 },
2026});
2027console.log(automation);
2028```
2029
2030```python
2031from openai import OpenAI
2032
2033client = OpenAI()
2034automation = client.beta.agents.automations.create(
2035 type="once",
2036 name="Check restaurant reply",
2037 run_at=1798794000,
2038 target={
2039 "type": "existing_session",
2040 "session_id": "sess_123",
2041 "instructions": (
2042 "Check whether the restaurant replied about our booking. "
2043 "Summarize any changes to the dinner plans."
2044 ),
2045 },
2046)
2047print(automation.to_json())
2048```
2049
2050```go
2051import (
2052 "context"
2053 "fmt"
2054
2055 "github.com/openai/openai-go/v3"
2056)
2057
2058ctx := context.Background()
2059client := openai.NewClient()
2060automation, err := client.Beta.Agents.Automations.New(ctx,
2061 openai.BetaAgentAutomationNewParams{
2062 CreateAutomationParams: openai.AutomationScheduleParamUnion{
2063 OfParamOnce: &openai.AutomationScheduleParamOnce{
2064 Name: "Check restaurant reply",
2065 RunAt: 1798794000,
2066 Target: openai.AutomationTargetParamUnion{
2067 OfParamExistingSession: &openai.AutomationTargetParamExistingSession{
2068 SessionID: "sess_123",
2069 Instructions: "Check whether the restaurant replied about our booking. Summarize any changes to the dinner plans.",
2070 },
2071 },
2072 },
2073 },
2074 })
2075if err != nil {
2076 panic(err)
2077}
2078fmt.Println(automation)
2079```
2080
2081```java
2082import com.openai.client.OpenAIClient;
2083import com.openai.client.okhttp.OpenAIOkHttpClient;
2084import com.openai.models.beta.agents.automations.AutomationCreateParams;
2085import com.openai.models.beta.agents.automations.AutomationScheduleParam;
2086import com.openai.models.beta.agents.automations.AutomationTargetParam;
2087
2088OpenAIClient client = OpenAIOkHttpClient.fromEnv();
2089var automation =
2090 client
2091 .beta()
2092 .agents()
2093 .automations()
2094 .create(
2095 AutomationCreateParams.builder()
2096 .automationScheduleParam(
2097 AutomationScheduleParam.Once.builder()
2098 .name("Check restaurant reply")
2099 .runAt(1798794000L)
2100 .target(
2101 AutomationTargetParam.ExistingSession.builder()
2102 .sessionId("sess_123")
2103 .instructions(
2104 "Check whether the restaurant replied about our booking. Summarize any changes to the dinner plans.")
2105 .build())
2106 .build())
2107 .build());
2108System.out.println(automation);
2109```
2110
2111```csharp
2112using OpenAI;
2113using OpenAI.Agents;
2114#pragma warning disable OPENAI001
2115
2116string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
2117AgentClient client = new OpenAIClient(key).GetAgentClient();
2118AgentAutomation automation = await client.CreateAutomationAsync(
2119 new AgentAutomationCreationOptions
2120 {
2121 Type = AgentAutomationType.Once,
2122 Name = "Check restaurant reply",
2123 RunAt = 1798794000,
2124 Target = new ExistingSessionAutomationTarget
2125 {
2126 SessionId = "sess_123",
2127 Instructions = "Check whether the restaurant replied about our booking. Summarize any changes to the dinner plans.",
2128 },
2129 }
2130);
2131Console.WriteLine(automation.Id);
2132```
2133
2134```ruby
2135require "openai"
2136
2137client = OpenAI::Client.new
2138automation = client.beta.agents.automations.create(
2139 body: {
2140 type: "once",
2141 name: "Check restaurant reply",
2142 run_at: 1798794000,
2143 target: {
2144 type: "existing_session",
2145 session_id: "sess_123",
2146 instructions: "Check whether the restaurant replied about our booking. Summarize any changes to the dinner plans."
2147 }
2148 }
2149)
2150puts automation
2151```
2152
2153```bash
2154curl https://api.openai.com/v1/agents/automations \
2155 -H "OpenAI-Beta: agents=v1" \
2156 -H "Authorization: Bearer $OPENAI_API_KEY" \
2157 -H "Content-Type: application/json" \
2158 -d '{
2159 "type": "once",
2160 "name": "Check restaurant reply",
2161 "run_at": 1798794000,
2162 "target": {
2163 "type": "existing_session",
2164 "session_id": "sess_123",
2165 "instructions": "Check whether the restaurant replied about our booking. Summarize any changes to the dinner plans."
2166 }
2167 }'
2168```
2169
2170
2171A completed one-time schedule has no more scheduled runs. You can still invoke it manually or create another automation for another scheduled follow-up.
2172
2173## Let the agent schedule follow-ups
2174
2175Add `automations` to the agent's tools so it can schedule work requested by the user. This example also enables subagents, so the main agent can delegate each scheduled task and keep a concise summary of the result:
2176
2177Let agents schedule tasks
2178
2179```javascript
2180import OpenAI from "openai";
2181
2182const client = new OpenAI();
2183const session = await client.beta.agents.sessions.create({
2184 agent: {
2185 model: "gpt-6-astra",
2186 instructions:
2187 "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.",
2188 tools: [{ type: "automations" }],
2189 multi_agent: { enabled: true },
2190 },
2191 environment: { type: "openai_hosted" },
2192 input:
2193 "Every day at 10 AM in America/New_York, review the goals we discuss here and suggest the next actions I could take.",
2194});
2195console.log(session.id);
2196```
2197
2198```python
2199from openai import OpenAI
2200
2201client = OpenAI()
2202session = client.beta.agents.sessions.create(
2203 agent={
2204 "model": "gpt-6-astra",
2205 "instructions": (
2206 "Use automations to schedule tasks requested by the user. "
2207 "Delegate each scheduled task to a subagent and ask for a concise result. "
2208 "Keep the goal, schedule, and useful summaries in the main session. "
2209 "Adjust or stop schedules when the user asks."
2210 ),
2211 "multi_agent": {"enabled": True},
2212 "tools": [{"type": "automations"}],
2213 },
2214 environment={"type": "openai_hosted"},
2215 input=(
2216 "Every day at 10 AM in America/New_York, review the goals we discuss here "
2217 "and suggest the next actions I could take."
2218 ),
2219)
2220print(session.id)
2221```
2222
2223```go
2224import (
2225 "context"
2226 "fmt"
2227
2228 "github.com/openai/openai-go/v3"
2229)
2230
2231ctx := context.Background()
2232client := openai.NewClient()
2233session, err := client.Beta.Agents.Sessions.New(ctx,
2234 openai.BetaAgentSessionNewParams{
2235 Agent: openai.BetaAgentSessionNewParamsAgent{
2236 Model: openai.String("gpt-6-astra"),
2237 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."),
2238 MultiAgent: openai.MultiAgentConfigParam{
2239 Enabled: true,
2240 },
2241 Tools: []openai.AgentToolParamUnion{
2242 {OfParamAutomations: &openai.AgentToolParamAutomations{}},
2243 },
2244 },
2245 Environment: openai.EnvironmentParamUnion{
2246 OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{},
2247 },
2248 Input: openai.BetaAgentSessionNewParamsInputUnion{
2249 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."),
2250 },
2251 })
2252if err != nil {
2253 panic(err)
2254}
2255fmt.Println(session.ID)
2256```
2257
2258```java
2259import com.openai.client.OpenAIClient;
2260import com.openai.client.okhttp.OpenAIOkHttpClient;
2261import com.openai.models.beta.agents.EnvironmentParam;
2262import com.openai.models.beta.agents.MultiAgentConfigParam;
2263import com.openai.models.beta.agents.sessions.SessionCreateParams;
2264
2265OpenAIClient client = OpenAIOkHttpClient.fromEnv();
2266var session =
2267 client
2268 .beta()
2269 .agents()
2270 .sessions()
2271 .create(
2272 SessionCreateParams.builder()
2273 .agent(
2274 SessionCreateParams.Agent.builder()
2275 .model("gpt-6-astra")
2276 .instructions(
2277 "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.")
2278 .multiAgent(MultiAgentConfigParam.builder().enabled(true).build())
2279 .addToolAutomations()
2280 .build())
2281 .environment(EnvironmentParam.OpenAIHosted.builder().build())
2282 .input(
2283 "Every day at 10 AM in America/New_York, review the goals we discuss here and suggest the next actions I could take.")
2284 .build());
2285System.out.println(session.id());
2286```
2287
2288```csharp
2289using OpenAI;
2290using OpenAI.Agents;
2291#pragma warning disable OPENAI001
2292
2293string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
2294AgentClient client = new OpenAIClient(key).GetAgentClient();
2295AgentSession session = await client.CreateAgentSessionAsync(
2296 new AgentSessionCreationOptions
2297 {
2298 Agent = new SessionAgentConfigParam
2299 {
2300 Model = "gpt-6-astra",
2301 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.",
2302 MultiAgent = new MultiAgentConfigParam { Enabled = true },
2303 Tools = [new AgentToolConfigParamAutomations()],
2304 },
2305 Environment = new EnvironmentParamOpenaiHosted(),
2306 Input =
2307 [
2308 new InputMessageParam(
2309 [new InputContentParamInputText("Every day at 10 AM in America/New_York, review the goals we discuss here and suggest the next actions I could take.")]
2310 ),
2311 ],
2312 }
2313);
2314Console.WriteLine(session.Id);
2315```
2316
2317```ruby
2318require "openai"
2319
2320client = OpenAI::Client.new
2321session = client.beta.agents.sessions.create(
2322 agent: {
2323 model: "gpt-6-astra",
2324 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.",
2325 multi_agent: { enabled: true },
2326 tools: [{ type: "automations" }]
2327 },
2328 environment: { type: "openai_hosted" },
2329 input: "Every day at 10 AM in America/New_York, review the goals we discuss here and suggest the next actions I could take."
2330)
2331puts session.id
2332```
2333
2334```bash
2335curl https://api.openai.com/v1/agents/sessions \
2336 -H "OpenAI-Beta: agents=v1" \
2337 -H "Authorization: Bearer $OPENAI_API_KEY" \
2338 -H "Content-Type: application/json" \
2339 -d '{
2340 "agent": {
2341 "model": "gpt-6-astra",
2342 "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.",
2343 "tools": [{ "type": "automations" }],
2344 "multi_agent": { "enabled": true }
2345 },
2346 "environment": {
2347 "type": "openai_hosted"
2348 },
2349 "input": "Every day at 10 AM in America/New_York, review the goals we discuss here and suggest the next actions I could take."
2350 }'
2351```
2352
2353
2354This lets the agent create, list, get, update, pause, resume, and delete its own automations. The Agents API sets the current session as the target. The agent can create one-time or periodic runs, but it can't use these tools to start a new session or manage another session's automations.
2355
2356The tools can access only automations created by the agent in the current session. Your application can manage those automations through the API, alongside automations it created itself. The Agents API records the creator in `created_by`; don't send that field in a create request.
2357
2358The tool is absent by default. Your application can schedule work without enabling it. Removing the tool from an agent's configuration doesn't delete saved schedules; pause or delete them through the API when needed.
2359
2360### Keep repeated work out of the main context
2361
2362For ongoing goals, [enable multi-agent orchestration](https://developers.openai.com/api/docs/guides/agents-api/multi-agent#enable-multi-agent-orchestration) with `agent.multi_agent.enabled: true`. Ask the main agent to keep the goal and schedule, delegate each task to a subagent, and retain a short result. This keeps detailed tool output from repeated checks out of the main session's context window.
2363
2364For example, include this in the main agent's instructions:
2365
2366> Delegate each scheduled task to a subagent. Give it the goal and relevant prior findings, and ask for a concise result. Review that result, keep the useful summary, and decide whether to continue, change, or stop the schedule.
2367
2368The `automations` tool manages schedules. Keep the other tools and data access the agent needs to do the scheduled work.
2369
2370## Schedule onboarding follow-ups from your app
2371
2372Your application can also create schedules in response to its own events. For example, when a user signs up, start an onboarding session and schedule its first follow-up for 48 hours later:
2373
2374Schedule an onboarding follow-up
2375
2376```javascript
2377import OpenAI from "openai";
2378
2379const client = new OpenAI();
2380const automation = await client.beta.agents.automations.create({
2381 type: "once",
2382 name: "Onboarding follow-up",
2383 run_at: Math.floor(Date.now() / 1000) + 48 * 60 * 60,
2384 target: {
2385 type: "existing_session",
2386 session_id: "sess_123",
2387 instructions:
2388 "Review onboarding progress and send the next onboarding message if the user has not completed onboarding.",
2389 },
2390});
2391console.log(automation);
2392```
2393
2394```python
2395import time
2396
2397from openai import OpenAI
2398
2399client = OpenAI()
2400automation = client.beta.agents.automations.create(
2401 type="once",
2402 name="Onboarding follow-up",
2403 run_at=int(time.time()) + 48 * 60 * 60,
2404 target={
2405 "type": "existing_session",
2406 "session_id": "sess_123",
2407 "instructions": (
2408 "Review onboarding progress and send the next onboarding message "
2409 "if the user has not completed onboarding."
2410 ),
2411 },
2412)
2413print(automation.to_json())
2414```
2415
2416```go
2417import (
2418 "context"
2419 "fmt"
2420 "time"
2421
2422 "github.com/openai/openai-go/v3"
2423)
2424
2425ctx := context.Background()
2426client := openai.NewClient()
2427automation, err := client.Beta.Agents.Automations.New(ctx,
2428 openai.BetaAgentAutomationNewParams{
2429 CreateAutomationParams: openai.AutomationScheduleParamUnion{
2430 OfParamOnce: &openai.AutomationScheduleParamOnce{
2431 Name: "Onboarding follow-up",
2432 RunAt: time.Now().Add(48 * time.Hour).Unix(),
2433 Target: openai.AutomationTargetParamUnion{
2434 OfParamExistingSession: &openai.AutomationTargetParamExistingSession{
2435 SessionID: "sess_123",
2436 Instructions: "Review onboarding progress and send the next onboarding message if the user has not completed onboarding.",
2437 },
2438 },
2439 },
2440 },
2441 })
2442if err != nil {
2443 panic(err)
2444}
2445fmt.Println(automation)
2446```
2447
2448```java
2449import com.openai.client.OpenAIClient;
2450import com.openai.client.okhttp.OpenAIOkHttpClient;
2451import com.openai.models.beta.agents.automations.AutomationCreateParams;
2452import com.openai.models.beta.agents.automations.AutomationScheduleParam;
2453import com.openai.models.beta.agents.automations.AutomationTargetParam;
2454import java.time.Duration;
2455import java.time.Instant;
2456
2457OpenAIClient client = OpenAIOkHttpClient.fromEnv();
2458var automation =
2459 client
2460 .beta()
2461 .agents()
2462 .automations()
2463 .create(
2464 AutomationCreateParams.builder()
2465 .automationScheduleParam(
2466 AutomationScheduleParam.Once.builder()
2467 .name("Onboarding follow-up")
2468 .runAt(Instant.now().plus(Duration.ofHours(48)).getEpochSecond())
2469 .target(
2470 AutomationTargetParam.ExistingSession.builder()
2471 .sessionId("sess_123")
2472 .instructions(
2473 "Review onboarding progress and send the next onboarding message if the user has not completed onboarding.")
2474 .build())
2475 .build())
2476 .build());
2477System.out.println(automation);
2478```
2479
2480```csharp
2481using OpenAI;
2482using OpenAI.Agents;
2483#pragma warning disable OPENAI001
2484
2485string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
2486AgentClient client = new OpenAIClient(key).GetAgentClient();
2487AgentAutomation automation = await client.CreateAutomationAsync(
2488 new AgentAutomationCreationOptions
2489 {
2490 Type = AgentAutomationType.Once,
2491 Name = "Onboarding follow-up",
2492 RunAt = DateTimeOffset.UtcNow.AddHours(48).ToUnixTimeSeconds(),
2493 Target = new ExistingSessionAutomationTarget
2494 {
2495 SessionId = "sess_123",
2496 Instructions = "Review onboarding progress and send the next onboarding message if the user has not completed onboarding.",
2497 },
2498 }
2499);
2500Console.WriteLine(automation.Id);
2501```
2502
2503```ruby
2504require "openai"
2505
2506client = OpenAI::Client.new
2507automation = client.beta.agents.automations.create(
2508 body: {
2509 type: "once",
2510 name: "Onboarding follow-up",
2511 run_at: Time.now.to_i + 48 * 60 * 60,
2512 target: {
2513 type: "existing_session",
2514 session_id: "sess_123",
2515 instructions: "Review onboarding progress and send the next onboarding message if the user has not completed onboarding."
2516 }
2517 }
2518)
2519puts automation
2520```
2521
2522```bash
2523RUN_AT=$(($(date +%s) + 48 * 60 * 60))
2524
2525curl https://api.openai.com/v1/agents/automations \
2526 -H "OpenAI-Beta: agents=v1" \
2527 -H "Authorization: Bearer $OPENAI_API_KEY" \
2528 -H "Content-Type: application/json" \
2529 -d @- <<EOF
2530{
2531 "type": "once",
2532 "name": "Onboarding follow-up",
2533 "run_at": $RUN_AT,
2534 "target": {
2535 "type": "existing_session",
2536 "session_id": "sess_123",
2537 "instructions": "Review onboarding progress and send the next onboarding message if the user has not completed onboarding."
2538 }
2539 }
2540EOF
2541```
2542
2543
2544After each completed follow-up, your application can schedule another one 48 hours later. Stop when onboarding is complete or the user opts out, and delete any pending follow-up. Use one-time schedules for this interval; a cron day-of-month expression doesn't represent a repeating 48-hour interval across month boundaries.
2545
2546The onboarding agent needs access to onboarding progress and the application's messaging tools. Creating the automation schedules the work; it doesn't send the message immediately.
2547
2548## Try a run and inspect delivery
2549
2550To test a saved automation immediately, send `POST /v1/agents/automations/auto_123/invocations` with no request body. A manual invocation doesn't change the saved schedule or consume a one-time scheduled run. It also works while the schedule is paused.
2551
2552Save the returned invocation ID. Retrieve it with `GET /v1/agents/automations/auto_123/invocations/ainv_123`, or list delivery history with `GET /v1/agents/automations/auto_123/invocations`.
2553
2554For an overview of past runs, list the automation's invocations:
2555
2556Monitor automation invocations
2557
2558```javascript
2559import OpenAI from "openai";
2560
2561const client = new OpenAI();
2562for await (const invocation of client.beta.agents.automations.invocations.list(
2563 "auto_123"
2564)) {
2565 console.log(invocation.id, invocation.status, invocation.session_id);
2566}
2567```
2568
2569```python
2570from openai import OpenAI
2571
2572client = OpenAI()
2573invocations = client.beta.agents.automations.invocations.list(automation_id="auto_123")
2574for invocation in invocations:
2575 print(invocation.id, invocation.status, invocation.session_id)
2576```
2577
2578```go
2579import (
2580 "context"
2581 "fmt"
2582
2583 "github.com/openai/openai-go/v3"
2584)
2585
2586ctx := context.Background()
2587client := openai.NewClient()
2588invocations := client.Beta.Agents.Automations.Invocations.ListAutoPaging(ctx, "auto_123",
2589 openai.BetaAgentAutomationInvocationListParams{})
2590for invocations.Next() {
2591 invocation := invocations.Current()
2592 fmt.Println(invocation.ID, invocation.Status, invocation.SessionID)
2593}
2594if err := invocations.Err(); err != nil {
2595 panic(err)
2596}
2597```
2598
2599```java
2600import com.openai.client.OpenAIClient;
2601import com.openai.client.okhttp.OpenAIOkHttpClient;
2602import com.openai.models.beta.agents.automations.invocations.InvocationListParams;
2603
2604OpenAIClient client = OpenAIOkHttpClient.fromEnv();
2605var invocations =
2606 client
2607 .beta()
2608 .agents()
2609 .automations()
2610 .invocations()
2611 .list(InvocationListParams.builder().automationId("auto_123").build());
2612for (var invocation : invocations.autoPager()) {
2613 System.out.println(
2614 invocation.id() + " " + invocation.status() + " " + invocation.sessionId());
2615}
2616```
2617
2618```csharp
2619using OpenAI;
2620using OpenAI.Agents;
2621#pragma warning disable OPENAI001
2622
2623string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
2624AgentClient client = new OpenAIClient(key).GetAgentClient();
2625await foreach (AgentAutomationInvocation invocation in client.GetAutomationInvocationsAsync("auto_123"))
2626{
2627 Console.WriteLine($"{invocation.Id} {invocation.Status} {invocation.SessionId}");
2628}
2629```
2630
2631```ruby
2632require "openai"
2633
2634client = OpenAI::Client.new
2635invocations = client.beta.agents.automations.invocations.list("auto_123")
2636invocations.auto_paging_each do |invocation|
2637 puts "#{invocation.id} #{invocation.status} #{invocation.session_id}"
2638end
2639```
2640
2641```bash
2642curl https://api.openai.com/v1/agents/automations/auto_123/invocations \
2643 -H "OpenAI-Beta: agents=v1" \
2644 -H "Authorization: Bearer $OPENAI_API_KEY"
2645```
2646
2647
2648The history contains invocations already created, but it does not include every future occurrence. Inspect these fields:
2649
2650| Field | What to check |
2651| -------------- | ---------------------------------------------------------------------------------------------------------- |
2652| `status` | Starts as `queued`; becomes `completed` when delivery succeeds. |
2653| `session_id` | The value identifies the session to follow after delivery and can be `null` before a session is available. |
2654| `source.type` | `manual` for a manual invocation or `automation` for a scheduled run. |
2655| `scheduled_at` | The intended scheduled time, or `null` for a manual invocation. |
2656
2657**A completed delivery doesn't mean the agent has completed its work.** For a new session, it means the session accepted its initial input. For an existing session, it means the session accepted the notification and the request to start work.
2658
2659Use the invocation's `session_id` to [follow session events](https://developers.openai.com/api/docs/guides/agents-api/sessions/events) and inspect the turn's outcome.
2660
2661The automation schedules the work. Your application displays session output and sends any notifications to the user.
2662
2663## Change or stop a schedule
2664
2665Retrieve an automation with `GET /v1/agents/automations/auto_123`. List your project's automations with `GET /v1/agents/automations`; add `session_id=sess_123` to find automations targeting an existing session.
2666
2667Update the cron expression to move a recurring check to 11 AM:
2668
2669Change a schedule
2670
2671```javascript
2672import OpenAI from "openai";
2673
2674const client = new OpenAI();
2675const automation = await client.beta.agents.automations.update("auto_123", {
2676 expression: "0 11 * * *",
2677});
2678console.log(automation);
2679```
2680
2681```python
2682from openai import OpenAI
2683
2684client = OpenAI()
2685automation = client.beta.agents.automations.update(
2686 automation_id="auto_123",
2687 expression="0 11 * * *",
2688)
2689print(automation.to_json())
2690```
2691
2692```go
2693import (
2694 "context"
2695 "fmt"
2696
2697 "github.com/openai/openai-go/v3"
2698)
2699
2700ctx := context.Background()
2701client := openai.NewClient()
2702automation, err := client.Beta.Agents.Automations.Update(ctx, "auto_123",
2703 openai.BetaAgentAutomationUpdateParams{
2704 Expression: openai.String("0 11 * * *"),
2705 })
2706if err != nil {
2707 panic(err)
2708}
2709fmt.Println(automation)
2710```
2711
2712```java
2713import com.openai.client.OpenAIClient;
2714import com.openai.client.okhttp.OpenAIOkHttpClient;
2715import com.openai.models.beta.agents.automations.AutomationUpdateParams;
2716
2717OpenAIClient client = OpenAIOkHttpClient.fromEnv();
2718var automation =
2719 client
2720 .beta()
2721 .agents()
2722 .automations()
2723 .update(
2724 AutomationUpdateParams.builder()
2725 .automationId("auto_123")
2726 .expression("0 11 * * *")
2727 .build());
2728System.out.println(automation);
2729```
2730
2731```csharp
2732using OpenAI;
2733using OpenAI.Agents;
2734#pragma warning disable OPENAI001
2735
2736string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
2737AgentClient client = new OpenAIClient(key).GetAgentClient();
2738AgentAutomation automation = await client.UpdateAutomationAsync(
2739 "auto_123",
2740 new AgentAutomationUpdateOptions { Expression = "0 11 * * *" }
2741);
2742Console.WriteLine(automation.Id);
2743```
2744
2745```ruby
2746require "openai"
2747
2748client = OpenAI::Client.new
2749automation = client.beta.agents.automations.update(
2750 "auto_123",
2751 expression: "0 11 * * *"
2752)
2753puts automation
2754```
2755
2756```bash
2757curl https://api.openai.com/v1/agents/automations/auto_123 \
2758 -H "OpenAI-Beta: agents=v1" \
2759 -H "Authorization: Bearer $OPENAI_API_KEY" \
2760 -H "Content-Type: application/json" \
2761 -d '{
2762 "expression": "0 11 * * *"
2763 }'
2764```
2765
2766
2767Omitted fields stay unchanged. A supplied `target` replaces the whole target, so include all its required fields and retain its type. Update reminder text in `target.instructions` or initial messages in `target.input`. An agent-created automation must retain its creator session as the target.
2768
2769Make changes before the next scheduled time. Updates apply to future invocations; an invocation that is already queued keeps the target and input saved when it was created.
2770
2771Use the following operations without a request body:
2772
2773| Goal | Operation | Effect |
2774| ---------------------- | --------------------------------------------- | ------------------------------------------------------------------------ |
2775| Pause scheduled work. | `POST /v1/agents/automations/auto_123/pause` | Holds pending scheduled deliveries; manual invocation remains available. |
2776| Resume scheduled work. | `POST /v1/agents/automations/auto_123/resume` | Reactivates the saved schedule. |
2777| Remove the schedule. | `DELETE /v1/agents/automations/auto_123` | Prevents future scheduled and manual invocations. |
2778
2779Pausing or deleting an automation doesn't stop work already accepted by a session or delete the session. A delivery already in progress may still reach its session. To stop current work, [cancel its active turn](https://developers.openai.com/api/docs/guides/agents-api/sessions#cancel-an-active-turn).
2780
2781If a one-time automation's scheduled time passes while it is paused, set a new future `run_at` before resuming. A completed one-time automation can't be paused or resumed; create another automation for another scheduled follow-up.
