Observabilidade e uso

Acompanhe a atividade dos agentes em tempo real, inspecione o trabalho concluído e revise rastreamentos detalhados dos turnos:

Você pode visualizar os logs da sessão no painel da plataforma.
Você pode acompanhar a sessão por meio de seus eventos e do histórico salvo.
Você pode inspecionar os turnos e identificar a execução delegada de comandos.
Você pode inspecionar o uso de tokens registrado nos turnos do agente raiz e dos subagentes.

Visualize a sessão no painel

Acesse platform.openai.com/logs?api=agents e abra a aba Agentes .

Pesquise uma sessão pelo ID para inspecionar seus turnos, chamadas de ferramentas e subagentes.

Use o guia de rastreamento para inspecionar no painel as respostas do modelo, chamadas de ferramentas e atividades de subagentes registradas, ou exporte rastreamentos de sessão em formato OTLP JSON pela API pública.

Acompanhe os eventos e inspecione o histórico da sessão

Cada sessão disponibiliza um fluxo de eventos que mostra o que o agente está fazendo em tempo real. Defina OPENAI_API_KEY e substitua o ID de sessão ilustrativo nestes exemplos pelo ID da sessão que você salvou:

Acompanhe os eventos da sessão em tempo real

JavaScript

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.fasterxml.jackson.databind.json.JsonMapper;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.http.StreamResponse;
import com.openai.models.beta.agents.AgentSessionEvent;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var json = new 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"

O fluxo permanece aberto mesmo durante eventos de inatividade para que você não perca o trabalho na fila. Pressione Ctrl+C para parar de acompanhar.

Durante a execução da sessão, você verá eventos como:

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

Para inspecionar o trabalho já realizado, recupere os itens salvos da sessão:

Inspecione os itens salvos da sessão

JavaScript

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"

Inspecione os turnos e identifique comandos delegados

Os turnos da sessão estão disponíveis pela API pública. Use o turn_id de um item de comando com o ID da sessão que você salvou. O exemplo com cURL requer jq:

Identifique a execução delegada de comandos

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15// 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 turns = await client.beta.agents.sessions.turns.list(sessionId, {
  limit: 20,
  order: "desc",
});
console.log(turns.data);
const turnId = "turn_123";
const turn = await client.beta.agents.sessions.turns.retrieve(turnId, {
  session_id: sessionId,
});
console.log(turn.subagent_id);

1
2
3
4
5
6
7
8
9
10
11# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI

client = OpenAI()

session_id = "sess_123"
turns = client.beta.agents.sessions.turns.list(session_id, limit=20, order="desc")
print(turns.to_json())
turn_id = "turn_123"
turn = client.beta.agents.sessions.turns.retrieve(turn_id, session_id=session_id)
print(turn.subagent_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// 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.Turns.List(ctx,
	"sess_123",
	openai.BetaAgentSessionTurnListParams{
		Limit: openai.Int(20),
		Order: "desc",
	})
if err != nil {
	panic(err)
}
fmt.Println(result.Data)
turn, err := client.Beta.Agents.Sessions.Turns.Get(ctx,
	"sess_123",
	"turn_123")
if err != nil {
	panic(err)
}
fmt.Println(turn.SubagentID)

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// 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.turns.TurnListParams;
import com.openai.models.beta.agents.sessions.turns.TurnRetrieveParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .turns()
        .list(
            TurnListParams.builder()
                .sessionId("sess_123")
                .limit(20L)
                .order(TurnListParams.Order.of("desc"))
                .build());
System.out.println(result.items());
var turn =
    client
        .beta()
        .agents()
        .sessions()
        .turns()
        .retrieve(
            TurnRetrieveParams.builder().turnId("turn_123").sessionId("sess_123").build());
System.out.println(turn.subagentId());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15# Replace the illustrative IDs and URLs below with your own resource values.
require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.turns.list(
  "sess_123",
  limit: 20,
  order: "desc"
)
puts result.data
turn = client.beta.agents.sessions.turns.retrieve(
  "turn_123",
  session_id: "sess_123"
)
puts turn.subagent_id

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'

Use o last_id retornado como valor de after da próxima página quando has_more for true.

Os itens de comando contêm turn_id. Recupere esse turno e leia subagent_id para identificar o agente delegado que executou o comando. Um ID de subagente com valor null identifica o trabalho do agente raiz. O truncamento da saída do comando não é informado.

Inspecione o rastreamento de um turno

Use o painel da plataforma para inspecionar um turno concluído e a atividade do agente nesse turno. Para recuperar rastreamentos registrados pela API pública, use o endpoint de exportação de rastreamentos de sessão com uma chave de API de projeto. Os endpoints de rastreamento do painel permanecem separados da API para clientes que conta com suporte.

Os recursos de turno incluem usage, registrado na medida do possível, e um subagent_id que identifica o trabalho delegado. O uso pode ser null quando desconhecido e pode mudar. Consulte Inspecione o uso de tokens dos subagentes.

Para identificar quem executou um comando de shell, recupere o turno identificado pelo turn_id do item de comando e inspecione turn.subagent_id. A API para clientes não indica se a saída do comando foi truncada.

Uso e custo do modelo

Um agente pode fazer várias chamadas ao modelo ao executar uma tarefa. Cada chamada segue os preços de tokens e as regras de cache de prompts do modelo, assim como na API Responses. Estime o custo considerando todas as chamadas necessárias para concluir a tarefa.

O que compõe o custo?

Cada chamada ao modelo pode consumir:

Tokens de entrada: instruções do agente, definições de ferramentas, histórico da conversa, entrada do usuário, arquivos ou imagens e resultados de ferramentas.
Tokens de entrada em cache: entrada reutilizada de um prefixo de prompt correspondente, cobrada pela tarifa de entrada em cache do modelo.
Tokens de saída: texto gerado, argumentos de chamadas de ferramentas e raciocínio.

Os tokens de raciocínio são cobrados como tokens de saída.

Os subagentes também podem fazer chamadas ao modelo. Ao investigar os custos do modelo, inspecione o uso por turno registrado para eles junto com o trabalho do agente raiz.

Considere o trabalho do agente raiz e dos subagentes, incluindo novas tentativas, além de quaisquer cobranças aplicáveis por ferramentas, computação no sandbox e serviços de terceiros. Para modelos com cobrança por gravação em cache, gravar a entrada no cache também tem um custo. Os campos de uso da API de Agentes abaixo não disponibilizam uma contagem separada de gravação em cache, portanto não permitem determinar o valor exato cobrado pelo modelo quando essa cobrança se aplica.

Cache de prompts

Os agentes mantêm o contexto ao longo de uma sessão. Quando chamadas sucessivas ao modelo compartilham o mesmo prefixo de prompt, o cache de prompts pode reutilizar o processamento anterior desse prefixo. O modelo gera uma nova resposta; o cache não reproduz uma resposta antiga. Manter uma sessão não garante que o cache será utilizado. A reutilização depende de um prefixo correspondente e das regras do modelo sobre elegibilidade e tempo de vida do cache.

Sempre que viável, mantenha as instruções iniciais e as definições de ferramentas estáveis e coloque novos detalhes da tarefa em mensagens de acompanhamento. Com a pesquisa de ferramentas, as definições descobertas são adicionadas ao final da conversa, preservando o conteúdo anterior para reutilização do cache. Consulte Cache de prompts para ver as regras específicas de cada modelo.

Um percentual alto de entrada em cache não mede a economia no custo total da tarefa. A entrada em cache continua sendo cobrada, e chamadas repetidas podem processar um histórico extenso. Compare o custo de concluir a mesma tarefa com a qualidade e a latência de que seu aplicativo precisa.

Entenda o uso de tokens

Os recursos de sessão e de turno disponibilizam usage, registrado na medida do possível. Esse valor pode ser null quando desconhecido, e as contagens registradas podem mudar à medida que os dados de contabilização chegam. A ausência de dados de uso não significa uso zero. Essas contagens não representam uma fatura final.

Um objeto de uso registrado contém estas categorias de tokens:

1234567891011{
  "input_tokens": 5000,
  "input_tokens_details": {
    "cached_tokens": 1500
  },
  "output_tokens": 900,
  "output_tokens_details": {
    "reasoning_tokens": 200
  },
  "total_tokens": 5900
}

Neste exemplo, o agente processou 5.000 tokens de entrada e gerou 900 tokens de saída. Dos tokens de entrada, 1.500 estavam em cache. Dos tokens de saída, 200 eram tokens de raciocínio.

Os tokens em cache estão incluídos em input_tokens, e os tokens de raciocínio estão incluídos em output_tokens.

Inspecione o uso de tokens dos subagentes

Liste ou recupere os turnos da sessão e inspecione o usage de cada turno. O subagent_id identifica o subagente; seu valor é null nos turnos do agente raiz. Quando has_more for true, passe last_id como after com o mesmo order para ler os turnos restantes.

O uso é registrado na medida do possível: pode ser null quando desconhecido, e os valores registrados podem mudar. Você também pode inspecionar o uso registrado de cada agente no painel de rastreamento.

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Recursos

APIs legadas

Escolha um modelo

Texto e código

Criação de prompts

Raciocínio

Imagens e vídeo

Tempo real e áudio

Modelos especializados

API de Agentes

SDK de Agentes

ChatKit

Pesquisa e recuperação

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolva com voz

Conexões

Processamento de áudio

Entre em produção

Desempenho e qualidade

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Plan

Build

Test and publish

Conversion specs

Guias

Recursos

Primeiros passos

Guias

File Upload

API

Measurement

Advertiser API

Referência da API

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Amplie os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Amplie e automatize

Ambientes

Desenvolva com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

ChatGPT Work

Identidade e autenticação

Acesso, política e modelos do workspace

Controles de plug-ins e conectores

Uso, governança e conformidade

Implantação e provedores de modelos

Comunidade

Blog

Comunidade

Blog