您可以通过以下方式实时跟踪智能体活动、查看已完成的工作,并了解每个轮次的详细执行过程:
- 在平台控制台中查看会话日志。
- 通过会话事件和已保存的历史记录跟踪会话进展。
- 查看会话轮次,确定哪些命令由子智能体执行。
- 查看根智能体和子智能体各轮次记录的 Token 用量。
前往 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。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: string, turnId: string) {
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 密钥调用会话追踪记录导出端点。控制台使用的追踪端点独立于面向客户正式提供的 API。
轮次资源通过 usage 提供当前能统计到的用量,并通过 subagent_id 标识委派给子智能体的工作。用量未知时,其值可能为 null,已记录的用量也可能变化。请参阅查看子智能体的 Token 用量。
要确定某个 shell 命令由哪个智能体执行,请根据命令条目中的 turn_id 获取对应的轮次,然后查看 turn.subagent_id。面向客户的 API 不会指明命令输出是否被截断。
请参阅错误与恢复,了解如何排查故障、选择恢复方式并安全重试。
智能体在完成一项任务的过程中可能多次调用模型。与 Responses API 一样,每次调用都遵循该模型的 Token 定价和提示词缓存规则。估算费用时,请计入完成任务所需的全部调用。
每次模型调用都可能消耗以下几类 Token:
- 输入 Token: 智能体指令、工具定义、对话历史记录、用户输入、文件或图像,以及工具结果。
- 缓存输入 Token: 从匹配的提示词前缀中复用的输入,按该模型的缓存输入费率计费。
- 输出 Token: 生成的文本、工具调用参数和推理内容。
推理 Token 按输出 Token 计费。
子智能体也可以调用模型。分析模型费用时,请同时查看子智能体记录的各轮次用量和根智能体的用量。
核算费用时,请计入根智能体和子智能体执行的所有工作,包括重试,以及适用的工具、沙盒计算和第三方服务费用。如果模型对缓存写入收费,将输入写入缓存也会产生费用。下文列出的 Agents API 用量字段不单独提供写入缓存的 Token 数,因此在适用此类定价时,无法仅凭这些字段确定模型调用的确切费用。
智能体会在同一会话中沿用之前的上下文。如果连续的模型调用具有相同的提示词前缀,提示词缓存就可以复用之前对该前缀的处理结果。模型仍会生成新的响应,不会从缓存中返回之前的回答。保持会话并不能保证缓存命中。能否复用缓存,取决于前缀是否匹配,以及模型规定的缓存条件和有效期。
在可行的情况下,请保持初始指令和工具定义稳定,并在后续消息中补充新的任务细节。使用工具搜索时,找到的工具定义会添加到对话末尾,使之前的内容保持原样,以便复用缓存。有关各模型的具体规则,请参阅提示词缓存。
缓存输入占比很高,并不能说明任务总费用节省了多少。缓存输入仍需付费,多次调用也可能反复处理大量历史记录。请在满足应用对质量和延迟要求的前提下,比较完成同一任务的总费用。
会话和轮次资源通过 usage 提供当前能统计到的用量。用量未知时,该字段可能为 null。随着计量数据陆续到达,已记录的数量可能变化。缺少用量数据不代表用量为零。这些统计数字不等同于最终账单。
记录的用量对象包含以下几类 Token:
1234567891011{
"input_tokens": 5000,
"input_tokens_details": {
"cached_tokens": 1500
},
"output_tokens": 900,
"output_tokens_details": {
"reasoning_tokens": 200
},
"total_tokens": 5900
}
在此示例中,智能体处理了 5,000 个输入 Token,并生成了 900 个输出 Token。输入 Token 中有 1,500 个命中了缓存,输出 Token 中有 200 个是推理 Token。
缓存 Token 已计入 input_tokens,推理 Token 已计入 output_tokens。
列出或获取会话轮次,然后查看每个轮次的 usage。字段 subagent_id 标识对应的子智能体,在根智能体的轮次中其值为 null。当 has_more 为 true 时,将 last_id 作为 after 传入,并保持 order 不变,即可读取其余轮次。
用量反映当前能统计到的数据。用量未知时,其值可能为 null,已记录的数值也可能变化。您还可以在追踪控制台中查看每个智能体记录的用量。