세션은 에이전트 설정과 대화, 저장된 작업 내용을 유지합니다. 같은 세션에 후속 메시지를 보내 작업을 이어가세요.
턴은 세션 안에서 이루어지는 한 차례의 작업입니다. 대기 중인 세션에 메시지를 보내면 새 턴이 시작됩니다. 턴이 진행 중일 때 메시지를 보내면 해당 턴의 작업 방향을 조정할 수 있습니다.
턴은 비동기로 실행됩니다. 애플리케이션은 스트리밍으로 진행 상황을 확인하거나 웹훅으로 세션 상태 변경 알림을 받을 수 있습니다.
예약 자동화를 사용하면 지정한 시각이나 주기에 맞춰 작업을 시작할 수 있습니다. 자동화는 실행할 때마다 새 세션을 만들거나 기존 대화를 이어갈 수 있습니다.
에이전트 설정과 초기 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// Reuse the same submission key when retrying this message.
async function sendMessage(client, sessionId, text, submissionKey) {
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, sessionId) {
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, sessionId) {
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"}]}'
