会话会持续保留智能体的配置、对话和已保存的工作成果。您可以在同一会话中发送后续消息,继续之前的工作。
一个轮次是会话中的一个工作周期。向空闲会话发送消息会启动新轮次。在轮次进行期间发送消息,可以引导智能体调整当前轮次的工作方向。
轮次以异步方式运行。您的应用可以通过事件流跟踪进度,也可以通过 Webhook 接收会话状态变更通知。
使用定时自动化任务可以在未来的指定时间或按固定周期启动工作。自动化任务可以在每次运行时创建新会话,也可以继续现有对话。
提供智能体配置和初始 input 来创建会话。将 stream 设为 true,即可在同一请求中接收首轮事件。
配置好 API 密钥和 SDK 后,运行以下示例来创建并执行脚本。脚本的运行环境由 OpenAI 管理。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import OpenAI from "openai";
const client = new OpenAI();
const events = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
instructions: "Write clean code, run it, and report the actual output.",
},
environment: { type: "openai_hosted" },
input:
"Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
stream: true,
});
events.withResultCollection();
try {
for await (const event of events) {
console.log(JSON.stringify(event));
}
const result = await events.finalResult();
console.log(result.output_text);
console.log("Session:", result.session_id);
} finally {
events.controller.abort();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17from openai import OpenAI
with OpenAI() as client:
with client.beta.agents.sessions.create(
agent={
"model": "gpt-6-astra",
"instructions": "Write clean code, run it, and report the actual output.",
},
environment={"type": "openai_hosted"},
input="Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
stream=True,
).with_result_collection() as stream:
for event in stream:
print(event.to_json(indent=None), flush=True)
result = stream.get_final_result()
print(result.output_text)
session_id = result.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
33
34
35import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
events := client.Beta.Agents.Sessions.NewStreaming(ctx, openai.BetaAgentSessionNewParams{
Agent: openai.BetaAgentSessionNewParamsAgent{
Model: openai.String("gpt-6-astra"),
Instructions: openai.String("Write clean code, run it, and report the actual output."),
},
Environment: openai.EnvironmentParamUnion{OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{}},
Input: openai.BetaAgentSessionNewParamsInputUnion{
OfString: openai.String("Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output."),
},
})
defer events.Close()
openai.BetaAgentSessionWithResultCollection(events)
if events.Err() != nil {
panic(events.Err())
}
for events.Next() {
event := events.Current()
fmt.Println(event.RawJSON())
}
result, err := openai.BetaAgentSessionFinalResult(events)
if err != nil {
panic(err)
}
fmt.Println(result.OutputText())
sessionID := result.SessionID()
fmt.Println("Session:", sessionID)
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
39import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.ObjectMappers;
import com.openai.core.http.StreamResponse;
import com.openai.models.beta.agents.AgentSessionEvent;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import com.openai.services.beta.agents.AgentTurnResults;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var json = ObjectMappers.jsonMapper();
try (StreamResponse<AgentSessionEvent> events =
client
.beta()
.agents()
.sessions()
.createStreaming(
SessionCreateParams.builder()
.agent(
SessionCreateParams.Agent.builder()
.model("gpt-6-astra")
.instructions("Write clean code, run it, and report the actual output.")
.build())
.environment(EnvironmentParam.OpenAIHosted.builder().build())
.input(
"Create tree.py, a Python script that prints a readable tree of the files"
+ " in the current directory. Run it and show me the output.")
.build())) {
AgentTurnResults.withResultCollection(events);
var iterator = events.stream().iterator();
while (iterator.hasNext()) {
var event = iterator.next();
System.out.println(json.writeValueAsString(event));
}
var result = AgentTurnResults.getFinalResult(events);
System.out.println(result.outputText());
String sessionId = result.sessionId();
System.out.println(sessionId);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24require "openai"
require "json"
client = OpenAI::Client.new
events = client.beta.agents.sessions.create_streaming(
agent: {
model: "gpt-6-astra",
instructions: "Write clean code, run it, and report the actual output."
},
environment: { type: "openai_hosted" },
input: "Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output."
)
begin
events.with_result_collection
events.each do |event|
puts JSON.generate(event.to_h)
end
result = events.get_final_result
puts result.output_text
session_id = result.session_id
puts "Session: #{session_id}"
ensure
events.close
end
1
2
3
4
5
6
7
8
9
10
11
12
13curl --no-buffer --fail-with-body 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": "Write clean code, run it, and report the actual output."
},
"environment": { "type": "openai_hosted" },
"input": "Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
"stream": true
}'
将 session_id 与应用的对话状态一同保存。使用该 ID 可以向这段对话发送后续消息,并获取已保存的工作成果。
如果项目已启用自动审核,您可以在创建符合条件的会话时,将 review 设为 "auto_review",为该会话启用自动审核模式,以自动审核智能体的操作。主任务处于空闲状态且所有输入提交均已处理完毕时,您可以更改此设置。有关审核模式、环境要求和审批行为,请参阅自动审核。
有关可复用的智能体设置,请参阅配置智能体。有关可选环境,请参阅架构。使用 environment.type: "none" 的会话必须提供初始输入。创建会话 API 参考列出了请求字段。
如果会话使用 Files API 附件,检查文件时可能会收到 HTTP 429 响应,错误代码为 files_api_rate_limit_exceeded。有关恢复步骤,请参阅 Files API 速率限制。
智能体运行时接受的请求最大为 4 MiB(4,194,304 字节)。请确保 input 和输出模式(agent.text.format.schema)的总大小低于此限制,并为 Agents API 添加的元数据预留一些空间。上传到环境中的文件受单独的文件限制约束。
智能体工作期间,事件会报告输出和变化。请检查轮次是已完成、失败还是已取消。仅凭会话处于空闲状态,无法判断该轮次是否成功。
请留意 agent.session.turn.completed、agent.session.turn.failed 或 agent.session.turn.cancelled 事件。还要检查智能体的输出,因为即使轮次已完成,个别工具调用仍可能失败。
如果会话需要函数结果或环境连接,请获取该会话并检查 required_actions。您的代码必须处理函数调用或连接环境,工作才能继续。
有关事件类型和载荷,请参阅事件与条目。
向同一会话再发送一条 agent.session.input.message 消息。如果智能体正在工作,这条消息会引导当前轮次的后续工作。如果会话处于空闲状态,这条消息会基于现有对话启动新轮次。
后续消息也受相同的输入大小限制约束。
对已保存智能体的更新仅适用于新会话。要更改此会话后续轮次使用的模型、推理强度或服务层级,请更新会话设置。
使用该对话的会话 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// Reuse the same submission key when retrying this message.
async function sendMessage(
client: OpenAI,
sessionId: string,
text: string,
submissionKey: string
) {
await client.beta.agents.sessions.events.create(sessionId, {
"Idempotency-Key": submissionKey,
events: [
{
type: "agent.session.input.message",
input: [
{
role: "user",
content: [
{
type: "input_text",
text,
},
],
},
],
},
],
});
}
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
31from uuid import uuid4
# Reuse the same submission key when retrying this message.
def send_message(
client: OpenAI, session_id: str, text: str, submission_key: str
) -> None:
client.beta.agents.sessions.events.create(
session_id,
idempotency_key=submission_key,
events=[
{
"type": "agent.session.input.message",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": text,
}
],
}
],
}
],
)
submission_key = str(uuid4())
# Save this key with the message before submitting it.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23// Reuse the same submission key when retrying this message.
func sendMessage(ctx context.Context, client *openai.Client, sessionID, text, submissionKey string) error {
return client.Beta.Agents.Sessions.Events.New(ctx,
sessionID,
openai.BetaAgentSessionEventNewParams{
IdempotencyKey: openai.String(submissionKey),
Events: []openai.AgentSessionInputParamUnion{
{
OfParamAgentSessionInputMessage: &openai.AgentSessionInputParamAgentSessionInputMessage{
Input: []openai.AgentSessionInputMessageParam{
{
Content: []openai.InputContentParamUnion{
{
OfParamInputText: &openai.InputContentParamInputText{Text: text},
},
},
},
},
},
},
},
})
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21// Reuse the same submission key when retrying this message.
public static void sendMessage(
OpenAIClient client, String sessionId, String text, String submissionKey) {
client
.beta()
.agents()
.sessions()
.events()
.create(
EventCreateParams.builder()
.sessionId(sessionId)
.idempotencyKey(submissionKey)
.addEvent(
AgentSessionInputParam.AgentSessionInputMessage.builder()
.addInput(
AgentSessionInputMessageParam.builder()
.addInputTextContent(text)
.build())
.build())
.build());
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23# Reuse the same submission key when retrying this message.
def send_message(client, session_id, text, submission_key)
client.beta.agents.sessions.events.create(
session_id,
idempotency_key: submission_key,
events: [
{
type: "agent.session.input.message",
input: [
{
role: "user",
content: [
{
type: "input_text",
text: text
}
]
}
]
}
]
)
end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24curl \
"https://api.openai.com/v1/agents/sessions/$session_id/events" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Idempotency-Key: $submission_key" \
-H "Content-Type: application/json" \
-d '{
"events": [
{
"type": "agent.session.input.message",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "List the files in the current directory."
}
]
}
]
}
]
}'
在 Idempotency-Key 请求头中传递幂等键,自动重试时复用该键。如果应用因超时或响应丢失而重试,请使用相同的幂等键、会话 ID 和消息。每次独立提交都要生成不同的幂等键,即使消息文本完全相同。
有关发送消息并流式接收事件的完整示例,请参阅事件与条目。
事件反映实时进度。会话条目记录已保存的消息和工具调用,包括已完成的响应。您可以获取这些条目来展示之前的工作,或在轮次结束后检查结果。
1
2
3
4
5
6
7// Pass your saved session ID to this helper.
async function listItems(client: OpenAI, sessionId: string) {
return client.beta.agents.sessions.items.list(sessionId, {
order: "asc",
limit: 100,
});
}
1
2
3# Pass your saved session ID to this helper.
def list_items(client: OpenAI, session_id: str):
return client.beta.agents.sessions.items.list(session_id, order="asc", limit=100)
1
2
3
4
5
6
7
8
9// Pass your saved session ID to this helper.
func listItems(ctx context.Context, client *openai.Client, sessionID string) (*pagination.CursorPage[openai.AgentSessionItemUnion], error) {
return client.Beta.Agents.Sessions.Items.List(ctx,
sessionID,
openai.BetaAgentSessionItemListParams{
Order: "asc",
Limit: openai.Int(100),
})
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14// Pass your saved session ID to this helper.
public static ItemListPage listItems(OpenAIClient client, String sessionId) {
return client
.beta()
.agents()
.sessions()
.items()
.list(
ItemListParams.builder()
.sessionId(sessionId)
.order(ItemListParams.Order.of("asc"))
.limit(100L)
.build());
}
1
2
3
4
5
6
7
8# Pass your saved session ID to this helper.
def list_items(client, session_id)
client.beta.agents.sessions.items.list(
session_id,
order: "asc",
limit: 100
)
end
1
2
3
4curl \
"https://api.openai.com/v1/agents/sessions/$session_id/items?order=asc&limit=100" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY"
要检查会话状态和轮次结果,请参阅管理会话。要获取文件,请参阅文件与产物。
事件流不会重放错过的事件。连接断开后,请获取会话及其已保存的条目,以恢复工作成果。有关重新连接的步骤,请参阅恢复已断开的事件流。
要让智能体停止工作,请取消当前轮次。取消后,您仍可以访问会话及之前的工作成果。
1
2
3
4
5
6// Pass your saved session ID to this helper.
async function cancelTurn(client: OpenAI, sessionId: string) {
await client.beta.agents.sessions.events.create(sessionId, {
events: [{ type: "agent.session.input.cancel" }],
});
}
1
2
3
4
5# Pass your saved session ID to this helper.
def cancel_turn(client: OpenAI, session_id: str) -> None:
client.beta.agents.sessions.events.create(
session_id, events=[{"type": "agent.session.input.cancel"}]
)
1
2
3
4
5
6
7
8
9
10// Pass your saved session ID to this helper.
func cancelTurn(ctx context.Context, client *openai.Client, sessionID string) error {
return client.Beta.Agents.Sessions.Events.New(ctx,
sessionID,
openai.BetaAgentSessionEventNewParams{
Events: []openai.AgentSessionInputParamUnion{
{OfParamAgentSessionInputCancel: &openai.AgentSessionInputParamAgentSessionInputCancel{}},
},
})
}
1
2
3
4
5
6
7
8
9
10
11
12
13// Pass your saved session ID to this helper.
public static void cancelTurn(OpenAIClient client, String sessionId) {
client
.beta()
.agents()
.sessions()
.events()
.create(
EventCreateParams.builder()
.sessionId(sessionId)
.addEventAgentSessionInputCancel()
.build());
}
1
2
3
4
5
6
7# Pass your saved session ID to this helper.
def cancel_turn(client, session_id)
client.beta.agents.sessions.events.create(
session_id,
events: [{ type: "agent.session.input.cancel" }]
)
end
1
2
3
4
5curl "https://api.openai.com/v1/agents/sessions/$session_id/events" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"events":[{"type":"agent.session.input.cancel"}]}'