使用定时自动化,按 cron 计划启动智能体会话。您也可以为智能体启用 automations 工具,让它们在执行任务时安排后续工作。
按 cron 计划自动运行会话
指定 cron 表达式和时区,即可定时启动新会话或继续现有会话。
允许智能体创建自动化
添加 automations 工具,让智能体在当前会话中安排后续任务。
监控自动化调用
每条调用记录都对应一次向会话投递任务的尝试。您可以查看调用状态和会话 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 import OpenAI from "openai" ;
const client = new OpenAI ();
const automation = await client.beta.agents.automations. create ({
type: "periodic" ,
name: "Daily session" ,
expression: "0 10 * * *" ,
timezone: "America/New_York" ,
target: {
type: "new_session" ,
agent_id: "agt_123" ,
environment: { type: "openai_hosted" },
input: [
{
role: "user" ,
content: [
{
type: "input_text" ,
text: "Summarize the current status and next steps." ,
},
],
},
],
},
});
console. log (automation); 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 from openai import OpenAI
client = OpenAI()
automation = client.beta.agents.automations.create(
type="periodic",
name="Daily session",
expression="0 10 * * *",
timezone="America/New_York",
target={
"type": "new_session",
"agent_id": "agt_123",
"environment": {"type": "openai_hosted"},
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Summarize the current status and next steps.",
}
],
}
],
},
)
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
42 import (
"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 session",
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: "Summarize the current status and next steps.",
},
},
},
},
},
},
},
},
},
})
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
34 import 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 session")
.expression("0 10 * * *")
.timezone("America/New_York")
.target(
AutomationTargetParam.NewSession.builder()
.agentId("agt_123")
.environment(EnvironmentParam.OpenAIHosted.builder().build())
.addInput(
AgentSessionInputMessageParam.builder()
.addInputTextContent(
"Summarize the current status and next steps.")
.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
28 require "openai"
client = OpenAI::Client.new
automation = client.beta.agents.automations.create(
create_automation_params: {
type: "periodic",
name: "Daily session",
expression: "0 10 * * *",
timezone: "America/New_York",
target: {
type: "new_session",
agent_id: "agt_123",
environment: { type: "openai_hosted" },
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "Summarize the current status and next steps."
}
]
}
]
}
}
)
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
28 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 '{
"type": "periodic",
"name": "Daily session",
"expression": "0 10 * * *",
"timezone": "America/New_York",
"target": {
"type": "new_session",
"agent_id": "agt_123",
"environment": {
"type": "openai_hosted"
},
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Summarize the current status and next steps."
}
]
}
]
}
}' 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 import 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
22 from openai import OpenAI
client = OpenAI()
session = client.beta.agents.sessions.create(
agent={
"model": "gpt-6-astra",
"instructions": (
"Use automations to schedule tasks requested by the user. "
"Delegate each scheduled task to a subagent and ask for a concise result. "
"Keep the goal, schedule, and useful summaries in the main session. "
"Adjust or stop schedules when the user asks."
),
"multi_agent": {"enabled": True},
"tools": [{"type": "automations"}],
},
environment={"type": "openai_hosted"},
input=(
"Every day at 10 AM in America/New_York, review the goals we discuss here "
"and suggest the next actions I could take."
),
)
print(session.id) 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 import (
"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
27 import 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
14 require "openai"
client = OpenAI::Client.new
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."
)
puts session.id 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 curl 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."
}' 1
2
3
4
5
6
7
8 import OpenAI from "openai" ;
const client = new OpenAI ();
for await ( const invocation of client.beta.agents.automations.invocations. list (
"auto_123"
)) {
console. log (invocation.id, invocation.status, invocation.session_id);
} 1
2
3
4
5
6 from openai import OpenAI
client = OpenAI()
invocations = client.beta.agents.automations.invocations.list(automation_id="auto_123")
for invocation in invocations:
print(invocation.id, invocation.status, invocation.session_id) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
invocations := client.Beta.Agents.Automations.Invocations.ListAutoPaging(ctx, "auto_123",
openai.BetaAgentAutomationInvocationListParams{})
for invocations.Next() {
invocation := invocations.Current()
fmt.Println(invocation.ID, invocation.Status, invocation.SessionID)
}
if err := invocations.Err(); err != nil {
panic(err)
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.automations.invocations.InvocationListParams;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var invocations =
client
.beta()
.agents()
.automations()
.invocations()
.list(InvocationListParams.builder().automationId("auto_123").build());
for (var invocation : invocations.autoPager()) {
System.out.println(
invocation.id() + " " + invocation.status() + " " + invocation.sessionId());
} 1
2
3
4
5
6
7 require "openai"
client = OpenAI::Client.new
invocations = client.beta.agents.automations.invocations.list("auto_123")
invocations.auto_paging_each do |invocation|
puts "#{invocation.id} #{invocation.status} #{invocation.session_id}"
end 1
2
3 curl https://api.openai.com/v1/agents/automations/auto_123/invocations \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY"
自动化
/v1/agents/automations
调用记录
/v1/agents/automations/{automation_id}/invocations
会话事件
/v1/agents/sessions/{session_id}/events
餐厅订位 每月支出分析 每日行动建议
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 import OpenAI from "openai" ;
const client = new OpenAI ();
const automation = await client.beta.agents.automations. create ({
type: "periodic" ,
name: "Check restaurant reservations" ,
expression: "0 */2 * * *" ,
timezone: "America/New_York" ,
target: {
type: "existing_session" ,
session_id: "sess_123" ,
instructions:
"Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables." ,
},
});
console. log (automation); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 from openai import OpenAI
client = OpenAI()
automation = client.beta.agents.automations.create(
type="periodic",
name="Check restaurant reservations",
expression="0 */2 * * *",
timezone="America/New_York",
target={
"type": "existing_session",
"session_id": "sess_123",
"instructions": (
"Check restaurant availability for our dinner plans. "
"Compare with earlier checks and report newly available tables."
),
},
)
print(automation.to_json()) 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 import (
"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: "Check restaurant reservations",
Expression: "0 */2 * * *",
Timezone: "America/New_York",
Target: openai.AutomationTargetParamUnion{
OfParamExistingSession: &openai.AutomationTargetParamExistingSession{
SessionID: "sess_123",
Instructions: "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables.",
},
},
},
},
})
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 import 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;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var automation =
client
.beta()
.agents()
.automations()
.create(
AutomationCreateParams.builder()
.automationScheduleParam(
AutomationScheduleParam.Periodic.builder()
.name("Check restaurant reservations")
.expression("0 */2 * * *")
.timezone("America/New_York")
.target(
AutomationTargetParam.ExistingSession.builder()
.sessionId("sess_123")
.instructions(
"Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables.")
.build())
.build())
.build());
System.out.println(automation); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 require "openai"
client = OpenAI::Client.new
automation = client.beta.agents.automations.create(
create_automation_params: {
type: "periodic",
name: "Check restaurant reservations",
expression: "0 */2 * * *",
timezone: "America/New_York",
target: {
type: "existing_session",
session_id: "sess_123",
instructions: "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables."
}
}
)
puts automation.id 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15 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 '{
"type": "periodic",
"name": "Check restaurant reservations",
"expression": "0 */2 * * *",
"timezone": "America/New_York",
"target": {
"type": "existing_session",
"session_id": "sess_123",
"instructions": "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables."
}
}'
自动化是为智能体任务保存的运行计划。Agents API 存储计划,并将每项任务投递到目标会话:
定义任务。 指定运行时间,并决定每次运行是启动新会话还是继续现有会话。
投递任务。 每次运行都会创建一条调用记录 ,记录这次向目标会话投递任务的尝试。如果会话正忙,任务将等待投递。
跟踪结果。 智能体利用会话的工具和上下文执行任务。跟踪会话事件即可查看进度并获取结果。会话收到任务并不代表智能体已完成工作。
您的应用可以通过 API 创建、更新、暂停或删除计划。启用 automations 工具后,智能体也可以在当前会话中自行安排下一次检查。
根据任务是否需要参考之前的对话选择目标:
目标
适用场景
必需配置
new_session
独立执行的任务,例如每月支出分析。
指定智能体和环境,并在 target.input 中提供初始消息。
existing_session
需要参考会话已有结果的后续任务。
提供会话 ID,并在 target.instructions 中填写提醒文本。
运行时间可独立于目标设置:
类型
时间字段
示例
periodic
expression 和 timezone
每天上午 10 点(America/New_York 时区)。
once
run_at
在未来的某个时间检查一次,用以秒为单位的 Unix 时间戳指定该时间。
两种计划类型均可与任一目标搭配使用。创建自动化时,系统会以 active 状态保存自动化,不会立即运行任务。周期性自动化的首次运行安排在下一个符合计划条件的时间点。
创建自动化前,请先创建智能体,为其配置执行任务所需的指令和工具,确保它可以访问用户的日历、任务和消息。请参阅跨会话复用智能体 。
SDK 已包含 OpenAI-Beta: agents=v1 请求头。使用 cURL 调用 API 时,请添加此请求头。
以下示例创建一个自动化,在纽约时间每天上午 10 点启动新会话:
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 import 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
30 from openai import OpenAI
client = OpenAI()
automation = client.beta.agents.automations.create(
type = "periodic" ,
name = "Daily suggestions" ,
expression = "0 10 * * *" ,
timezone = "America/New_York" ,
target = {
"type" : "new_session" ,
"agent_id" : "agt_123" ,
"environment" : { "type" : "openai_hosted" },
"input" : [
{
"role" : "user" ,
"content" : [
{
"type" : "input_text" ,
"text" : (
"Review my calendar, tasks, and recent messages for today. "
"Suggest the most useful actions I could take today, "
"with a short reason for each."
),
}
],
}
],
},
)
print (automation.to_json()) 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
42 import (
"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
34 import 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
28 require "openai"
client = OpenAI::Client.new
automation = 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
28 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 '{
"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."
}
]
}
]
}
}'
请保存返回的自动化 id,以便日后查看或管理计划。每次调用都会启动新的对话。上述环境配置会为该会话创建一个 OpenAI 托管的沙盒 。
您可以在 target.agent 中直接提供智能体配置,也可以用 target.agent_id 指定已保存的智能体。这两个字段必须且只能提供一个。请将初始消息放在 target.input 中,不要放在请求的顶层。至少提供一条包含非空文本或图片 URL 的消息。
您可以用同样的方法安排每月支出分析。允许已保存的智能体访问用户的财务记录,然后安排在每月 1 日上午 9 点启动新会话:
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 import 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
30 from openai import OpenAI
client = OpenAI()
automation = client.beta.agents.automations.create(
type = "periodic" ,
name = "Monthly spending review" ,
expression = "0 9 1 * *" ,
timezone = "America/New_York" ,
target = {
"type" : "new_session" ,
"agent_id" : "agt_123" ,
"environment" : { "type" : "openai_hosted" },
"input" : [
{
"role" : "user" ,
"content" : [
{
"type" : "input_text" ,
"text" : (
"Review my spending for the previous month. Flag unused "
"subscriptions, price increases, and other potential "
"savings for me to review."
),
}
],
}
],
},
)
print (automation.to_json()) 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
42 import (
"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: "Monthly spending review",
Expression: "0 9 1 * *",
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 spending for the previous month. Flag unused subscriptions, price increases, and other potential savings for me to review.",
},
},
},
},
},
},
},
},
},
})
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
34 import 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("Monthly spending review")
.expression("0 9 1 * *")
.timezone("America/New_York")
.target(
AutomationTargetParam.NewSession.builder()
.agentId("agt_123")
.environment(EnvironmentParam.OpenAIHosted.builder().build())
.addInput(
AgentSessionInputMessageParam.builder()
.addInputTextContent(
"Review my spending for the previous month. Flag unused subscriptions, price increases, and other potential savings for me to review.")
.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
28 require "openai"
client = OpenAI::Client.new
automation = client.beta.agents.automations.create(
create_automation_params: {
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."
}
]
}
]
}
}
)
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
28 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 '{
"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."
}
]
}
]
}
}'
使用包含五个字段的 cron 表达式,并指定时区名称:
表达式
运行时间
0 10 * * *
每天上午 10 点
0 */2 * * *
每两小时一次
0 9 1 * *
每月 1 日上午 9 点
0 9 * * MON-FRI
周一至周五上午 9 点
时区决定了如何解释表达式。按 UTC 时间运行时,使用 UTC;按当地时间运行时,使用 America/New_York 等 IANA 时区。不要在周期性自动化中包含 run_at。
cron 计划按所选时区的当地时间运行。例如,0 */3 * * * 会安排在零点、凌晨 3 点、早上 6 点及之后每隔三小时运行一次,而不是从创建时刻起每隔三小时运行一次。
计划指定的是预定运行时间。为分散负载,Agents API 会为周期性运行添加短暂的随机延迟。如果目标会话正忙,任务可能需要等待更久。
如果智能体需要参考之前的结果、消息或已保存的工作成果,请使用现有会话。例如,用来安排晚餐的会话可以保留餐厅偏好和之前查询可订餐位的结果。
以下示例在该会话中每两小时查询一次可订餐位:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 import OpenAI from "openai";
const client = new OpenAI();
const automation = await client.beta.agents.automations.create({
type: "periodic",
name: "Check restaurant reservations",
expression: "0 */2 * * *",
timezone: "America/New_York",
target: {
type: "existing_session",
session_id: "sess_123",
instructions:
"Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables.",
},
});
console.log(automation); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 from openai import OpenAI
client = OpenAI()
automation = client.beta.agents.automations.create(
type = "periodic" ,
name = "Check restaurant reservations" ,
expression = "0 */2 * * *" ,
timezone = "America/New_York" ,
target = {
"type" : "existing_session" ,
"session_id" : "sess_123" ,
"instructions" : (
"Check restaurant availability for our dinner plans. "
"Compare with earlier checks and report newly available tables."
),
},
)
print (automation.to_json()) 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 import (
"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: "Check restaurant reservations",
Expression: "0 */2 * * *",
Timezone: "America/New_York",
Target: openai.AutomationTargetParamUnion{
OfParamExistingSession: &openai.AutomationTargetParamExistingSession{
SessionID: "sess_123",
Instructions: "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables.",
},
},
},
},
})
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 import 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;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var automation =
client
.beta()
.agents()
.automations()
.create(
AutomationCreateParams.builder()
.automationScheduleParam(
AutomationScheduleParam.Periodic.builder()
.name("Check restaurant reservations")
.expression("0 */2 * * *")
.timezone("America/New_York")
.target(
AutomationTargetParam.ExistingSession.builder()
.sessionId("sess_123")
.instructions(
"Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables.")
.build())
.build())
.build());
System.out.println(automation); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 require "openai"
client = OpenAI::Client.new
automation = client.beta.agents.automations.create(
create_automation_params: {
type: "periodic",
name: "Check restaurant reservations",
expression: "0 */2 * * *",
timezone: "America/New_York",
target: {
type: "existing_session",
session_id: "sess_123",
instructions: "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables."
}
}
)
puts automation.id 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15 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 '{
"type": "periodic",
"name": "Check restaurant reservations",
"expression": "0 */2 * * *",
"timezone": "America/New_York",
"target": {
"type": "existing_session",
"session_id": "sess_123",
"instructions": "Check restaurant availability for our dinner plans. Compare with earlier checks and report newly available tables."
}
}'
每次调用都会将已保存的指令作为自动化通知投递到同一个会话。该会话使用当前的智能体配置和已保存的状态执行任务。自动化通知与新的用户消息彼此独立。
如果会话正在执行任务,系统会等到会话可用时再投递。定时运行不会中断当前轮次,也不会补上缺少的工具结果或审批。您的应用仍须处理所需操作 。
要安排一次后续检查,请将 type: "once" 与 run_at 搭配使用。后者的值必须是以秒 为单位的整数 Unix 时间戳,且必须指向未来的时间。不要包含 expression 或 timezone。
安排在 2027 年 1 月 1 日上午 9 点(UTC) 执行一次检查:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15 import 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
17 from openai import OpenAI
client = OpenAI()
automation = client.beta.agents.automations.create(
type = "once" ,
name = "Check restaurant reply" ,
run_at = 1798794000 ,
target = {
"type" : "existing_session" ,
"session_id" : "sess_123" ,
"instructions" : (
"Check whether the restaurant replied about our booking. "
"Summarize any changes to the dinner plans."
),
},
)
print (automation.to_json()) 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 import (
"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{
OfParamOnce: &openai.AutomationScheduleParamOnce{
Name: "Check restaurant reply",
RunAt: 1798794000,
Target: openai.AutomationTargetParamUnion{
OfParamExistingSession: &openai.AutomationTargetParamExistingSession{
SessionID: "sess_123",
Instructions: "Check whether the restaurant replied about our booking. Summarize any changes to the dinner plans.",
},
},
},
},
})
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 import 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;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var automation =
client
.beta()
.agents()
.automations()
.create(
AutomationCreateParams.builder()
.automationScheduleParam(
AutomationScheduleParam.Once.builder()
.name("Check restaurant reply")
.runAt(1798794000L)
.target(
AutomationTargetParam.ExistingSession.builder()
.sessionId("sess_123")
.instructions(
"Check whether the restaurant replied about our booking. Summarize any changes to the dinner plans.")
.build())
.build())
.build());
System.out.println(automation); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 require "openai"
client = OpenAI::Client.new
automation = client.beta.agents.automations.create(
create_automation_params: {
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."
}
}
)
puts automation.id 1
2
3
4
5
6
7
8
9
10
11
12
13
14 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 '{
"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."
}
}'
一次性计划完成后,不会再定时运行。您仍可手动调用它,也可以创建另一个自动化来安排下一次跟进。
将 automations 添加到智能体的工具中,使其能够安排用户要求的任务。此示例还启用了子智能体,以便主智能体将每项定时任务委派给子智能体,并保留简要结果:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 import 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
22 from openai import OpenAI
client = OpenAI()
session = client.beta.agents.sessions.create(
agent = {
"model" : "gpt-6-astra" ,
"instructions" : (
"Use automations to schedule tasks requested by the user. "
"Delegate each scheduled task to a subagent and ask for a concise result. "
"Keep the goal, schedule, and useful summaries in the main session. "
"Adjust or stop schedules when the user asks."
),
"multi_agent" : { "enabled" : True },
"tools" : [{ "type" : "automations" }],
},
environment = { "type" : "openai_hosted" },
input = (
"Every day at 10 AM in America/New_York, review the goals we discuss here "
"and suggest the next actions I could take."
),
)
print (session.id) 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 import (
"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
27 import 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
14 require "openai"
client = OpenAI::Client.new
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."
)
puts session.id 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 curl 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."
}'
这样,智能体就可以创建、列出、获取、更新、暂停、恢复和删除自己的自动化。Agents API 会将当前会话设为目标。智能体可以安排一次性或周期性运行,但不能使用这些工具启动新会话或管理其他会话的自动化。
这些工具只能访问智能体在当前会话中创建的自动化。您的应用可以通过 API 管理这些自动化,也可以管理应用自身创建的自动化。Agents API 会在 created_by 中记录创建者,请勿在创建请求中发送该字段。
默认情况下,智能体没有此工具。您的应用无需启用此工具也能安排任务。从智能体配置中移除工具不会删除已保存的计划。如有需要,请通过 API 暂停或删除这些计划。
对于需要持续跟进的目标,请启用多智能体编排 ,配置为 agent.multi_agent.enabled: true。让主智能体保留目标和计划,将每项任务委派给子智能体,并保留简要结果。这样,反复检查产生的详细工具输出就不会占用主会话的上下文窗口。
例如,您可以在主智能体的指令中加入以下内容:
将每项定时任务委派给子智能体。向它说明目标和之前获得的相关结果,并要求它简要报告本次结果。查看结果,保留有用信息的摘要,并决定是继续、调整还是停止计划。
automations 工具用于管理计划。请保留智能体执行定时任务所需的其他工具和数据访问权限。
您的应用也可以根据自身事件创建计划。例如,当用户注册时,启动新用户引导会话,并将首次跟进安排在 48 小时后:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15 import 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
19 import time
from openai import OpenAI
client = OpenAI()
automation = client.beta.agents.automations.create(
type = "once" ,
name = "Onboarding follow-up" ,
run_at = int (time.time()) + 48 * 60 * 60 ,
target = {
"type" : "existing_session" ,
"session_id" : "sess_123" ,
"instructions" : (
"Review onboarding progress and send the next onboarding message "
"if the user has not completed onboarding."
),
},
)
print (automation.to_json()) 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 import (
"context"
"fmt"
"time"
"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{
OfParamOnce: &openai.AutomationScheduleParamOnce{
Name: "Onboarding follow-up",
RunAt: time.Now().Add(48 * time.Hour).Unix(),
Target: openai.AutomationTargetParamUnion{
OfParamExistingSession: &openai.AutomationTargetParamExistingSession{
SessionID: "sess_123",
Instructions: "Review onboarding progress and send the next onboarding message if the user has not completed onboarding.",
},
},
},
},
})
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 import 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
16 require "openai"
client = OpenAI::Client.new
automation = 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
18 RUN_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
每次跟进完成后,应用都可以将下一次跟进安排在 48 小时后。如果用户已完成引导流程或选择退出,请停止跟进,并删除所有待执行的跟进任务。请使用一次性计划来安排这一间隔,因为 cron 表达式中指定每月几号的字段无法保证跨月时仍按 48 小时的间隔运行。
负责引导的智能体需要能够查看用户的引导进度,并使用应用的消息发送工具。创建自动化只会安排任务,不会立即发送消息。
要立即测试已保存的自动化,请发送 POST /v1/agents/automations/auto_123/invocations,不要附带请求体。手动调用不会更改已保存的计划,也不会用掉一次性计划的定时运行机会。计划暂停期间也可以手动调用。
请保存返回的调用 ID。使用 GET /v1/agents/automations/auto_123/invocations/ainv_123 获取该调用记录,或使用 GET /v1/agents/automations/auto_123/invocations 列出投递历史。
要了解以往的运行情况,可以列出该自动化的调用记录:
1
2
3
4
5
6
7
8 import OpenAI from "openai" ;
const client = new OpenAI ();
for await ( const invocation of client.beta.agents.automations.invocations. list (
"auto_123"
)) {
console. log (invocation.id, invocation.status, invocation.session_id);
} 1
2
3
4
5
6 from openai import OpenAI
client = OpenAI()
invocations = client.beta.agents.automations.invocations.list(automation_id="auto_123")
for invocation in invocations:
print(invocation.id, invocation.status, invocation.session_id) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
invocations := client.Beta.Agents.Automations.Invocations.ListAutoPaging(ctx, "auto_123",
openai.BetaAgentAutomationInvocationListParams{})
for invocations.Next() {
invocation := invocations.Current()
fmt.Println(invocation.ID, invocation.Status, invocation.SessionID)
}
if err := invocations.Err(); err != nil {
panic(err)
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.automations.invocations.InvocationListParams;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var invocations =
client
.beta()
.agents()
.automations()
.invocations()
.list(InvocationListParams.builder().automationId("auto_123").build());
for (var invocation : invocations.autoPager()) {
System.out.println(
invocation.id() + " " + invocation.status() + " " + invocation.sessionId());
} 1
2
3
4
5
6
7 require "openai"
client = OpenAI::Client.new
invocations = client.beta.agents.automations.invocations.list("auto_123")
invocations.auto_paging_each do |invocation|
puts "#{invocation.id} #{invocation.status} #{invocation.session_id}"
end 1
2
3 curl https://api.openai.com/v1/agents/automations/auto_123/invocations \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY"
历史记录包含已经创建的调用,但不会列出今后的每一次定时运行。请查看以下字段:
字段
查看内容
status
初始值为 queued,投递成功后变为 completed。
session_id
标识投递后应跟踪的会话。在会话可用之前,值可能为 null。
source.type
manual 表示手动调用,automation 表示定时运行。
scheduled_at
预定运行时间。对于手动调用,值为 null。
投递完成并不代表智能体已完成任务。 对于新会话,投递完成表示会话已接收初始输入。对于现有会话,则表示会话已接收通知和开始执行任务的请求。
使用调用记录中的 session_id 跟踪会话事件 ,查看该轮次的执行结果。
自动化负责安排任务。您的应用负责显示会话输出,并向用户发送相应通知。
使用 GET /v1/agents/automations/auto_123 获取自动化。使用 GET /v1/agents/automations 列出项目中的自动化。添加 session_id=sess_123 即可查找以指定的现有会话为目标的自动化。
更新 cron 表达式,将周期性检查的时间改为上午 11 点:
1
2
3
4
5
6
7 import OpenAI from "openai";
const client = new OpenAI();
const automation = await client.beta.agents.automations.update("auto_123", {
expression: "0 11 * * *",
});
console.log(automation); 1
2
3
4
5
6
7
8 from openai import OpenAI
client = OpenAI()
automation = client.beta.agents.automations.update(
automation_id = "auto_123" ,
expression = "0 11 * * *" ,
)
print (automation.to_json()) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
automation, err := client.Beta.Agents.Automations.Update(ctx, "auto_123",
openai.BetaAgentAutomationUpdateParams{
Expression: openai.String("0 11 * * *"),
})
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 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.automations.AutomationUpdateParams;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var automation =
client
.beta()
.agents()
.automations()
.update(
AutomationUpdateParams.builder()
.automationId("auto_123")
.expression("0 11 * * *")
.build());
System.out.println(automation); 1
2
3
4
5
6
7
8 require "openai"
client = OpenAI::Client.new
automation = client.beta.agents.automations.update(
"auto_123",
expression: "0 11 * * *"
)
puts automation.id 1
2
3
4
5
6
7 curl https://api.openai.com/v1/agents/automations/auto_123 \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"expression": "0 11 * * *"
}'
省略的字段保持不变。如果提供 target,它会替换整个目标配置,因此请包含所有必需字段,并保留原有的目标类型。要更新提醒文本,请修改 target.instructions;要更新初始消息,请修改 target.input。对于智能体创建的自动化,目标必须始终是创建该自动化的会话。
请在下一次预定运行时间之前完成更改。更新适用于后续调用。已经进入队列的调用仍使用创建时保存的目标和输入。
执行以下操作时,请勿附带请求体:
目标
操作
效果
暂停定时任务。
POST /v1/agents/automations/auto_123/pause
暂缓尚未投递的定时任务,仍可手动调用。
恢复定时任务。
POST /v1/agents/automations/auto_123/resume
重新启用已保存的计划。
移除计划。
DELETE /v1/agents/automations/auto_123
阻止今后的定时调用和手动调用。
暂停或删除自动化不会停止会话已接收的任务,也不会删除会话。已经开始投递的任务仍可能送达目标会话。要停止当前任务,请取消正在执行的轮次 。
如果一次性自动化的预定运行时间在暂停期间已过,请先将 run_at 设为新的未来时间,再恢复运行。已完成的一次性自动化无法暂停或恢复。如需再安排一次跟进,请创建另一个自动化。