에이전트 활동을 실시간으로 추적하고, 완료된 작업과 각 턴의 상세 트레이스를 확인할 수 있습니다.
- 플랫폼 대시보드에서 세션 로그를 확인할 수 있습니다.
- 이벤트와 저장된 기록을 통해 세션의 진행 상황을 추적할 수 있습니다.
- 턴을 조회해 위임된 명령어를 어느 에이전트가 실행했는지 확인할 수 있습니다.
- 루트 에이전트와 하위 에이전트의 턴별 토큰 사용량 기록을 확인할 수 있습니다.
platform.openai.com/logs?api=agents로 이동해 에이전트 탭을 여세요.
세션 ID로 검색하면 해당 세션의 턴, 도구 호출, 하위 에이전트를 확인할 수 있습니다.
트레이싱 가이드를 참고해 대시보드에서 기록된 모델 응답, 도구 호출, 하위 에이전트 활동을 확인하세요. 공개 API를 통해 OTLP JSON 형식으로 세션 트레이스를 내보낼 수도 있습니다.
각 세션은 에이전트가 어떤 작업을 수행하는지 실시간으로 보여 주는 이벤트 스트림을 제공합니다. OPENAI_API_KEY를 설정하고 다음 예시의 세션 ID를 저장해 둔 세션 ID로 바꾸세요.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";
const client = new OpenAI();
const events = await client.beta.agents.sessions.events.stream("sess_123");
try {
for await (const event of events) {
if (
[
"agent.session.turn.failed",
"agent.session.turn.cancelled",
"agent.session.failed",
"agent.session.environment.failed",
"error",
].includes(event.type)
) {
throw new Error(`Agent lifecycle failure: ${event.type}`);
}
console.log(JSON.stringify(event));
}
} finally {
events.controller.abort();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI
client = OpenAI()
session_id = "sess_123"
with client.beta.agents.sessions.events.stream(session_id) as events:
for event in events:
if event.type in {
"agent.session.turn.failed",
"agent.session.turn.cancelled",
"agent.session.failed",
"agent.session.environment.failed",
"error",
}:
raise RuntimeError(f"Agent lifecycle failure: {event.type}")
print(event.to_json(indent=None))
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// Replace the illustrative IDs and URLs below with your own resource values.
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
events := client.Beta.Agents.Sessions.Events.StreamStreaming(ctx, "sess_123")
defer events.Close()
if events.Err() != nil {
panic(events.Err())
}
for events.Next() {
event := events.Current()
switch event.Type {
case "agent.session.turn.failed", "agent.session.turn.cancelled", "agent.session.failed", "agent.session.environment.failed", "error":
panic(event.RawJSON())
}
fmt.Println(event.RawJSON())
}
if err := events.Err(); err != nil {
panic(err)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24// Replace the illustrative IDs and URLs below with your own resource values.
import 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;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var json = ObjectMappers.jsonMapper();
try (StreamResponse<AgentSessionEvent> events =
client.beta().agents().sessions().events().streamStreaming("sess_123")) {
var iterator = events.stream().iterator();
while (iterator.hasNext()) {
var event = iterator.next();
if (event.turnFailed().isPresent()
|| event.turnCancelled().isPresent()
|| event.failed().isPresent()
|| event.environmentFailed().isPresent()
|| event.error().isPresent()) {
throw new IllegalStateException("Agent failed: " + event);
}
System.out.println(json.writeValueAsString(event));
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17# Replace the illustrative IDs and URLs below with your own resource values.
require "openai"
require "json"
client = OpenAI::Client.new
events = client.beta.agents.sessions.events.stream_streaming("sess_123")
begin
events.each do |event|
case event.type.to_s
when "agent.session.turn.failed", "agent.session.turn.cancelled", "agent.session.failed", "agent.session.environment.failed", "error"
raise "Agent failed: #{event.to_h}"
end
puts JSON.generate(event.to_h)
end
ensure
events.close
end
1
2
3
4
5curl -N \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Accept: text/event-stream" \
"https://api.openai.com/v1/agents/sessions/sess_123/events?stream=true"
유휴 상태를 알리는 이벤트가 발생해도 스트림은 열린 상태로 유지되므로 대기열에 있는 작업을 놓치지 않습니다. 모니터링을 중지하려면 Ctrl+C를 누르세요.
세션이 실행되는 동안 다음과 같은 이벤트가 표시됩니다.
agent.session.environment.connected
agent.session.turn.created
agent.session.turn.in_progress
agent.session.turn.item.added
agent.session.turn.output_text.delta
agent.session.turn.completed
agent.session.idle
이미 수행된 작업을 확인하려면 세션에 저장된 항목을 조회하세요.
1
2
3
4
5
6
7
8
9
10// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";
const client = new OpenAI();
const sessionId = "sess_123";
const items = await client.beta.agents.sessions.items.list(sessionId, {
order: "asc",
limit: 100,
});
console.log(items.data);
1
2
3
4
5
6
7
8# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI
client = OpenAI()
session_id = "sess_123"
items = client.beta.agents.sessions.items.list(session_id, order="asc", limit=100)
print(items.to_json())
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20// Replace the illustrative IDs and URLs below with your own resource values.
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.Items.List(ctx,
"sess_123",
openai.BetaAgentSessionItemListParams{
Order: "asc",
Limit: openai.Int(100),
})
if err != nil {
panic(err)
}
fmt.Println(result.Data)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19// Replace the illustrative IDs and URLs below with your own resource values.
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.items.ItemListParams;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
client
.beta()
.agents()
.sessions()
.items()
.list(
ItemListParams.builder()
.sessionId("sess_123")
.order(ItemListParams.Order.of("asc"))
.limit(100L)
.build());
System.out.println(result.items());
1
2
3
4
5
6
7
8
9
10# Replace the illustrative IDs and URLs below with your own resource values.
require "openai"
client = OpenAI::Client.new
result = client.beta.agents.sessions.items.list(
"sess_123",
order: "asc",
limit: 100
)
puts result.data
1
2
3
4curl \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
"https://api.openai.com/v1/agents/sessions/sess_123/items?order=asc&limit=100"
공개 API로 세션의 턴을 조회할 수 있습니다. 명령어 항목의 turn_id와 저장해 둔 세션 ID를 함께 사용하세요. Go 예시는 SDK에 내장된 페이지네이션 기능으로 루트 에이전트와 하위 에이전트의 턴을 검색한 다음, ID가 일치하는 턴을 해당 턴의 소유 에이전트에서 조회합니다. 예시의 ID를 실제 세션에서 가져온 ID로 바꾸세요. cURL 예시를 실행하려면 jq가 필요합니다.
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// Replace the illustrative session and turn IDs with values from your command item.
import OpenAI from "openai";
const client = new OpenAI();
async function findTurn(sessionId, turnId) {
for await (const turn of client.beta.agents.sessions.turns.list(sessionId, {
limit: 100,
})) {
if (turn.id === turnId) {
return client.beta.agents.sessions.turns.retrieve(turnId, {
session_id: sessionId,
});
}
}
for await (const subagent of client.beta.agents.sessions.subagents.list(
sessionId,
{ limit: 100 }
)) {
for await (const turn of client.beta.agents.sessions.subagents.turns.list(
subagent.id,
{ session_id: sessionId, limit: 100 }
)) {
if (turn.id === turnId) {
return client.beta.agents.sessions.subagents.turns.retrieve(turnId, {
session_id: sessionId,
subagent_id: subagent.id,
});
}
}
}
throw new Error(`Turn ${turnId} not found in session ${sessionId}`);
}
const turn = await findTurn("sess_123", "turn_123");
console.log(turn.subagent_id || "main agent");
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# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI
def find_turn(client, session_id, turn_id):
# Native SDK pagination searches every page for the owning agent.
for turn in client.beta.agents.sessions.turns.list(session_id, limit=100):
if turn.id == turn_id:
return client.beta.agents.sessions.turns.retrieve(
turn_id, session_id=session_id
)
for subagent in client.beta.agents.sessions.subagents.list(session_id, limit=100):
turns = client.beta.agents.sessions.subagents.turns.list(
subagent.id, session_id=session_id, limit=100
)
for turn in turns:
if turn.id == turn_id:
return client.beta.agents.sessions.subagents.turns.retrieve(
turn_id, session_id=session_id, subagent_id=subagent.id
)
raise ValueError(f"Turn {turn_id} not found in session {session_id}")
turn = find_turn(OpenAI(), "sess_123", "turn_123")
print(turn.subagent_id or "main agent")
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
43
44
45
46
47
48
49
50
51
52// Replace the illustrative session and turn IDs with values from your command item.
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
turn, err := findTurn(ctx, &client, "sess_123", "turn_123")
if err != nil {
panic(err)
}
if turn.SubagentID == "" {
fmt.Println("main agent")
} else {
fmt.Println(turn.SubagentID)
}
// findTurn discovers the owning agent using native SDK pagination.
func findTurn(ctx context.Context, client *openai.Client, sessionID, turnID string) (*openai.Turn, error) {
turns := client.Beta.Agents.Sessions.Turns.ListAutoPaging(ctx, sessionID,
openai.BetaAgentSessionTurnListParams{Limit: openai.Int(100)})
for turns.Next() {
if turns.Current().ID == turnID {
return client.Beta.Agents.Sessions.Turns.Get(ctx, sessionID, turnID)
}
}
if err := turns.Err(); err != nil {
return nil, err
}
subagents := client.Beta.Agents.Sessions.Subagents.ListAutoPaging(ctx, sessionID,
openai.BetaAgentSessionSubagentListParams{Limit: openai.Int(100)})
for subagents.Next() {
subagent := subagents.Current()
childTurns := client.Beta.Agents.Sessions.Subagents.Turns.ListAutoPaging(ctx, sessionID, subagent.ID,
openai.BetaAgentSessionSubagentTurnListParams{Limit: openai.Int(100)})
for childTurns.Next() {
if childTurns.Current().ID == turnID {
return client.Beta.Agents.Sessions.Subagents.Turns.Get(ctx, sessionID, subagent.ID, turnID)
}
}
if err := childTurns.Err(); err != nil {
return nil, err
}
}
if err := subagents.Err(); err != nil {
return nil, err
}
return nil, fmt.Errorf("turn %s not found in session %s", turnID, 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
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56// Replace the illustrative session and turn IDs with values from your command item.
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.subagents.SubagentListParams;
import com.openai.models.beta.agents.sessions.turns.Turn;
import com.openai.models.beta.agents.sessions.turns.TurnListParams;
import com.openai.models.beta.agents.sessions.turns.TurnRetrieveParams;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var turn = findTurn(client, "sess_123", "turn_123");
System.out.println(turn.subagentId().orElse("main agent"));
// Discover the owning agent using native SDK pagination before retrieving the turn.
static Turn findTurn(OpenAIClient client, String sessionId, String turnId) {
var sessions = client.beta().agents().sessions();
var turns =
sessions.turns().list(TurnListParams.builder().sessionId(sessionId).limit(100L).build());
for (var turn : turns.autoPager()) {
if (turn.id().equals(turnId)) {
return sessions
.turns()
.retrieve(TurnRetrieveParams.builder().sessionId(sessionId).turnId(turnId).build());
}
}
var subagents =
sessions
.subagents()
.list(SubagentListParams.builder().sessionId(sessionId).limit(100L).build());
for (var subagent : subagents.autoPager()) {
var childTurns =
sessions
.subagents()
.turns()
.list(
com.openai.models.beta.agents.sessions.subagents.turns.TurnListParams.builder()
.sessionId(sessionId)
.subagentId(subagent.id())
.limit(100L)
.build());
for (var turn : childTurns.autoPager()) {
if (turn.id().equals(turnId)) {
return sessions
.subagents()
.turns()
.retrieve(
com.openai.models.beta.agents.sessions.subagents.turns.TurnRetrieveParams
.builder()
.sessionId(sessionId)
.subagentId(subagent.id())
.turnId(turnId)
.build());
}
}
}
throw new IllegalArgumentException("Turn " + turnId + " not found in 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# Replace the illustrative IDs below with values from your command item.
require "openai"
# Discover the owning agent before retrieving the turn.
def find_turn(client, session_id, turn_id)
turns = client.beta.agents.sessions.turns.list(session_id, limit: 100)
turns.auto_paging_each do |turn|
if turn.id == turn_id
return client.beta.agents.sessions.turns.retrieve(turn_id, session_id: session_id)
end
end
subagents = client.beta.agents.sessions.subagents.list(session_id, limit: 100)
subagents.auto_paging_each do |subagent|
turns = client.beta.agents.sessions.subagents.turns.list(
subagent.id, session_id: session_id, limit: 100
)
turns.auto_paging_each do |turn|
if turn.id == turn_id
return client.beta.agents.sessions.subagents.turns.retrieve(
turn_id, session_id: session_id, subagent_id: subagent.id
)
end
end
end
raise "Turn #{turn_id} not found in session #{session_id}"
end
turn = find_turn(OpenAI::Client.new, "sess_123", "turn_123")
puts(turn.subagent_id || "main agent")
1
2
3
4
5
6
7curl "https://api.openai.com/v1/agents/sessions/sess_123/turns?limit=20&order=desc" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY"
curl "https://api.openai.com/v1/agents/sessions/sess_123/turns/turn_123" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" | jq '.subagent_id'
페이지를 직접 조회할 때는 응답의 last_id를 다음 페이지 요청의 after 값으로 사용하세요. 이때 has_more가 true인 경우에만 다음 페이지를 요청합니다. Go 예시에서는 다음 페이지를 자동으로 조회합니다.
명령어 항목에는 turn_id가 포함됩니다. 해당 턴을 조회하고 subagent_id를 확인하면 위임된 명령어를 실행한 에이전트를 식별할 수 있습니다. 하위 에이전트 ID가 null이면 루트 에이전트가 실행한 작업입니다. 명령어 출력이 잘렸는지는 표시되지 않습니다.
플랫폼 대시보드에서 완료된 턴과 해당 턴의 에이전트 활동을 확인하세요.
공개 API로 기록된 트레이스를 조회하려면 프로젝트 API 키로 세션 트레이스 내보내기 엔드포인트를 호출하세요. 대시보드용 트레이스 엔드포인트는 고객용으로 지원되는 API와 별개입니다.
턴 리소스에는 집계 가능한 범위에서 제공되는 usage와 위임된 작업을 식별하는 subagent_id가 포함됩니다. 사용량을 알 수 없으면 값이 null일 수 있으며, 기록된 값은 달라질 수 있습니다. 하위 에이전트의 토큰 사용량 확인을 참고하세요.
셸 명령어를 어느 에이전트가 실행했는지 알아보려면 명령어 항목의 turn_id로 턴을 조회한 다음 turn.subagent_id를 확인하세요. 고객용 API에서는 명령어 출력이 잘렸는지 알 수 없습니다.
실패 원인을 확인하고 적절한 복구 방법을 선택해 안전하게 재시도하려면 오류 및 복구를 참고하세요.
에이전트는 작업 하나를 완료하는 동안 모델을 여러 번 호출할 수 있습니다. Responses API와 마찬가지로 각 호출에는 해당 모델의 토큰 요금과 프롬프트 캐싱 규칙이 적용됩니다. 작업 완료에 필요한 모든 호출을 포함해 비용을 추산하세요.
모델을 호출할 때마다 다음 토큰이 사용될 수 있습니다.
- 입력 토큰: 에이전트 지침, 도구 정의, 대화 기록, 사용자 입력, 파일이나 이미지, 도구 실행 결과에 해당하는 토큰입니다.
- 캐시된 입력 토큰: 프롬프트 접두부가 일치해 재사용된 입력 토큰입니다. 해당 모델의 캐시된 입력 요율이 적용됩니다.
- 출력 토큰: 생성된 텍스트, 도구 호출 인수, 추론에 해당하는 토큰입니다.
추론 토큰에는 출력 토큰 요금이 적용됩니다.
하위 에이전트도 모델을 호출할 수 있습니다. 모델 비용을 분석할 때는 루트 에이전트의 작업과 함께 하위 에이전트의 턴별 사용량 기록을 확인하세요.
재시도를 포함해 루트 에이전트와 하위 에이전트가 수행한 작업을 모두 계산에 넣고, 도구, 샌드박스 컴퓨팅, 타사 서비스에 요금이 부과된다면 이 비용도 포함하세요. 캐시 쓰기 요금이 있는 모델은 입력을 캐시에 기록할 때도 비용이 발생합니다. 아래의 Agents API 사용량 필드는 캐시에 쓴 토큰 수를 별도로 제공하지 않으므로, 캐시 쓰기 요금이 적용될 때는 이 필드만으로 정확한 모델 요금을 계산할 수 없습니다.
에이전트는 같은 세션 안에서 이전 컨텍스트를 이어서 사용합니다. 연속된 모델 호출에서 프롬프트 접두부가 일치하면 프롬프트 캐싱을 통해 해당 접두부의 이전 처리 결과를 재사용할 수 있습니다. 캐싱을 사용해도 모델은 이전 답변을 그대로 반환하지 않고 새 응답을 생성합니다. 세션을 유지한다고 해서 항상 캐시가 적중하는 것은 아닙니다. 캐시 재사용 여부는 접두부 일치 여부와 모델별 캐싱 조건 및 캐시 유효 기간에 따라 달라집니다.
가능하면 초기 지침과 도구 정의를 일정하게 유지하고, 새로운 작업 세부 정보는 후속 메시지에 넣으세요. 도구 검색을 사용하면 검색된 도구 정의가 대화 끝에 추가되므로 이전 내용을 그대로 유지해 캐시를 재사용할 수 있습니다. 모델별 규칙은 프롬프트 캐싱을 참고하세요.
캐시된 입력 토큰의 비율이 높더라도 이 비율만으로 전체 작업 비용이 얼마나 절감되었는지는 알 수 없습니다. 캐시된 입력에도 요금이 부과되며, 모델을 반복해서 호출하면 매번 긴 대화 기록을 처리할 수 있습니다. 애플리케이션에 필요한 품질과 지연 시간 조건에서 동일한 작업을 완료하는 데 드는 비용을 비교하세요.
세션 및 턴 리소스는 집계 가능한 범위에서 usage를 제공합니다. 사용량을 알 수 없으면 값이 null일 수 있으며, 추가 집계 내역이 반영되면 기록된 수치가 달라질 수 있습니다. 사용량 기록이 없다고 해서 사용량이 0인 것은 아닙니다. 이 수치는 최종 청구 내역이 아닙니다.
기록된 사용량 객체에는 다음과 같이 유형별 토큰 수가 포함됩니다.
1234567891011{
"input_tokens": 5000,
"input_tokens_details": {
"cached_tokens": 1500
},
"output_tokens": 900,
"output_tokens_details": {
"reasoning_tokens": 200
},
"total_tokens": 5900
}
이 예시에서 에이전트는 입력 토큰 5,000개를 처리하고 출력 토큰 900개를 생성했습니다. 입력 토큰 중 1,500개는 캐시된 토큰이고, 출력 토큰 중 200개는 추론 토큰입니다.
캐시된 토큰은 input_tokens에 포함되고 추론 토큰은 output_tokens에 포함됩니다.
세션 턴 목록을 가져오거나 개별 턴을 조회해 각 턴의 usage를 확인하세요. subagent_id는 하위 에이전트를 식별하며, 루트 에이전트의 턴에서는 값이 null입니다. has_more가 true이면 last_id를 after 값으로 전달하고 order 값을 그대로 유지해 나머지 턴을 조회하세요.
사용량은 집계 가능한 범위에서 제공됩니다. 사용량을 알 수 없으면 값이 null일 수 있으며, 기록된 값도 달라질 수 있습니다. 트레이싱 대시보드에서도 각 에이전트의 사용량 기록을 확인할 수 있습니다.
