工作階段會持續保留智慧體的設定、對話和已儲存的工作成果。使用同一個工作階段傳送後續訊息,即可接續先前的工作。
回合是智慧體在工作階段中執行一次工作的週期。傳送訊息時,如果工作階段處於閒置狀態,就會開始新回合。如果回合正在執行,訊息就會引導該回合的工作方向。
回合會以非同步方式執行。應用程式可以透過串流追蹤進度,也可以透過 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"}]}'