Observabilidad y uso

Sigue la actividad del agente en tiempo real, inspecciona el trabajo completado y revisa las trazas detalladas de los turnos:

Puedes ver los registros de la sesión en el panel de la plataforma.
Puedes seguir la sesión a través de sus eventos y su historial guardado.
Puedes inspeccionar los turnos e identificar la ejecución delegada de comandos.
Puedes inspeccionar el uso de tokens registrado para los turnos del agente raíz y de los subagentes.

Ver la sesión en el panel

Ve a platform.openai.com/logs?api=agents y abre la pestaña Agentes .

Busca una sesión por su ID para inspeccionar sus turnos, llamadas a herramientas y subagentes.

Usa la guía de seguimiento de trazas para inspeccionar las respuestas registradas del modelo, las llamadas a herramientas y la actividad de los subagentes en el panel, o exporta las trazas de la sesión en formato OTLP JSON a través de la API pública.

Seguir eventos e inspeccionar el historial de la sesión

Cada sesión ofrece un flujo de eventos que muestra lo que hace el agente en tiempo real. Configura OPENAI_API_KEY y reemplaza el ID de sesión ilustrativo de estos ejemplos por el ID de sesión que guardaste:

Seguir los eventos de la sesión en tiempo 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"

El flujo permanece abierto durante los eventos de inactividad para que no te pierdas el trabajo en cola. Presiona Ctrl+C para dejar de observarlo.

Mientras se ejecuta la sesión, verás eventos como los siguientes:

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 inspeccionar el trabajo que ya se realizó, recupera los elementos guardados de la sesión:

Inspeccionar los elementos guardados de la sesión

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"

Inspeccionar turnos e identificar comandos delegados

Los turnos de la sesión están disponibles a través de la API pública. Usa el turn_id de un elemento de comando junto con el ID de sesión que guardaste. El ejemplo de cURL requiere jq:

Identificar la ejecución 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'

Usa el last_id devuelto como valor de after para la página siguiente cuando has_more sea true.

Los elementos de comando contienen turn_id. Recupera ese turno y consulta subagent_id para identificar al agente delegado que ejecutó el comando. Un ID de subagente con valor null identifica el trabajo del agente raíz. No se informa si se truncó la salida del comando.

Inspeccionar la traza de un turno

Usa el panel de la plataforma para inspeccionar un turno completado y la actividad de sus agentes. Para recuperar las trazas registradas a través de la API pública, usa el punto de acceso para exportar trazas de sesiones con una clave de API del proyecto. Los puntos de acceso de trazas del panel siguen siendo independientes de la API para clientes que cuenta con soporte.

Los recursos de turno incluyen usage según la información disponible y un subagent_id que identifica el trabajo delegado. El uso puede ser null cuando se desconoce y puede cambiar. Consulta Inspeccionar el uso de tokens de los subagentes.

Para atribuir un comando de shell, recupera el turno identificado por el valor turn_id de su elemento de comando y luego inspecciona turn.subagent_id. La API para clientes no indica si se truncó la salida del comando.

Uso del modelo y costo

Un agente puede realizar varias llamadas al modelo para completar una tarea. En cada llamada se aplican los precios por token y las reglas de almacenamiento de prompts en caché del modelo, al igual que en la API Responses. Estima el costo de todas las llamadas necesarias para completar la tarea.

¿Qué contribuye al costo?

Cada llamada al modelo puede consumir:

Tokens de entrada: instrucciones del agente, definiciones de herramientas, historial de la conversación, entradas del usuario, archivos o imágenes y resultados de herramientas.
Tokens de entrada en caché: entrada reutilizada a partir de un prefijo de prompt coincidente, facturada según la tarifa de entrada en caché del modelo.
Tokens de salida: texto generado, argumentos de llamadas a herramientas y razonamiento.

Los tokens de razonamiento se facturan como tokens de salida.

Los subagentes también pueden realizar llamadas al modelo. Al investigar los costos del modelo, inspecciona su uso registrado por turno junto con el trabajo del agente raíz.

Ten en cuenta el trabajo del agente raíz y de los subagentes, incluidos los reintentos, además de los cargos aplicables por herramientas, recursos de cómputo del sandbox y servicios de terceros. En los modelos con tarifas de escritura en caché, escribir la entrada en la caché también tiene un costo. Los campos de uso de la API de agentes que se muestran a continuación no incluyen un recuento independiente de escritura en caché, por lo que no permiten determinar el cargo exacto del modelo cuando se aplica esa tarifa.

Almacenamiento de prompts en caché

Los agentes conservan el contexto a lo largo de una sesión. Cuando las llamadas sucesivas al modelo comparten el mismo prefijo de prompt, el almacenamiento de prompts en caché permite reutilizar el procesamiento previo de ese prefijo. El modelo genera una respuesta nueva; la caché no reproduce una respuesta anterior. Mantener una sesión no garantiza un acierto de caché. La reutilización depende de que el prefijo coincida y de las reglas del modelo sobre los requisitos y la duración de la caché.

Mantén estables las instrucciones iniciales y las definiciones de herramientas cuando sea práctico, y agrega los nuevos detalles de la tarea en mensajes de seguimiento. Con la búsqueda de herramientas, las definiciones encontradas se agregan al final de la conversación, lo que preserva el contenido anterior para reutilizarlo desde la caché. Consulta Almacenamiento de prompts en caché para conocer las reglas específicas de cada modelo.

Un porcentaje alto de entrada en caché no mide el ahorro en el costo total de la tarea. La entrada en caché se sigue facturando, y las llamadas repetidas pueden procesar un historial extenso. Compara el costo de completar la misma tarea con la calidad y la latencia que necesita tu aplicación.

Comprender el uso de tokens

Los recursos de sesión y de turno ofrecen usage según la información disponible. Puede ser null cuando se desconoce, y los recuentos registrados pueden cambiar a medida que llegan los datos de contabilización. La ausencia de datos de uso no significa que el uso sea cero. Estos recuentos no constituyen una factura final.

Un objeto de uso registrado contiene estas categorías de tokens:

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

En este ejemplo, el agente procesó 5000 tokens de entrada y generó 900 tokens de salida. De los tokens de entrada, 1500 estaban en caché. De los tokens de salida, 200 eran tokens de razonamiento.

Los tokens en caché se incluyen en input_tokens, y los tokens de razonamiento se incluyen en output_tokens.

Inspeccionar el uso de tokens de los subagentes

Enumera o recupera los turnos de la sesión e inspecciona el valor de usage de cada turno. El subagent_id identifica al subagente; su valor es null para los turnos del agente raíz. Cuando has_more sea true, pasa last_id como after con el mismo valor de order para leer los turnos restantes.

El uso se registra según la información disponible: puede ser null cuando se desconoce, y los valores registrados pueden cambiar. También puedes inspeccionar el uso registrado de cada agente en el panel de seguimiento de trazas.

Sugerencias

Primeros pasos

Conceptos fundamentales

SDK y CLI

Recursos

API heredadas

Elige un modelo

Texto y código

Diseño de prompts

Razonamiento

Imágenes y video

Tiempo real y audio

Modelos especializados

API de agentes

SDK de agentes

ChatKit

Búsqueda y recuperación

Conecta herramientas y datos

Crea flujos de trabajo con herramientas

Computadora y código

Contenido multimedia

GPT-Live

Realtime API

Desarrollar con voz

Conexiones

Procesamiento de audio

Pasa a producción

Rendimiento y calidad

Costo y rendimiento

Seguridad y gobernanza

Infraestructura y acceso

Operaciones

Conceptos fundamentales

Plan

Build

Test and publish

Conversion specs

Guías

Recursos

Primeros pasos

Guías

File Upload

API

Measurement

Advertiser API

Referencia de la API

Primeros pasos

Fundamentos

Explorar

Disponible en

Versiones

Flujos de trabajo

Capacidades

Referencia

Personalización

Archivo de configuración

Configuración de agentes

Ampliar las capacidades de ChatGPT y Codex

Linux

Windows

Flujos de trabajo de desarrollo

Extender y automatizar

Entornos

Crear con Codex

Integraciones de terceros

Referencia

Permisos

Codex Security

Seguridad cibernética

Primeros pasos

ChatGPT Work

Identidad y autenticación

Acceso, políticas y modelos del espacio de trabajo

Controles de complementos y conectores

Uso, gobernanza y cumplimiento

Implementación y proveedores de modelos

Comunidad

Blog

Comunidad

Blog