Observabilité et consommation de tokens

Suivez l’activité des agents en temps réel, examinez le travail effectué et consultez les traces détaillées de chaque tour :

Consultez les journaux de session dans le tableau de bord de la plateforme.
Suivez la session à partir de ses événements et de son historique enregistré.
Examinez les tours pour repérer les commandes dont l’exécution a été déléguée.
Consultez la consommation de tokens enregistrée pour les tours de l’agent racine et des sous-agents.

Consulter la session dans le tableau de bord

Accédez à platform.openai.com/logs?api=agents et ouvrez l’onglet Agents.

Recherchez une session par son identifiant pour examiner ses tours, ses appels d’outils et ses sous-agents.

Consultez le guide de traçage pour examiner dans le tableau de bord les enregistrements des réponses du modèle, des appels d’outils et de l’activité des sous-agents, ou exportez les traces de session au format JSON OTLP via l’API publique.

Suivre les événements et consulter l’historique de session

Chaque session fournit un flux d’événements qui indique ce que fait l’agent en temps réel. Définissez OPENAI_API_KEY et remplacez l’identifiant de session donné dans ces exemples par celui que vous avez enregistré :

Suivre les événements de session en temps réel

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.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"

Le flux reste ouvert même lorsque la session signale qu’elle est inactive, ce qui vous permet de suivre les tâches en attente. Appuyez sur Ctrl+C pour arrêter le suivi.

Au cours de la session, vous verrez des événements tels que :

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

Pour examiner le travail déjà effectué, récupérez les éléments enregistrés de la session :

Examiner les éléments enregistrés de la session

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"

Examiner les tours et repérer les commandes déléguées

L’API publique donne accès aux tours de session. Utilisez le turn_id d’un élément de commande avec l’identifiant de session que vous avez enregistré. L’exemple en Go parcourt les tours de l’agent racine et des sous-agents grâce à la pagination intégrée au SDK, puis récupère le tour correspondant auprès de l’agent auquel il appartient. Remplacez les identifiants donnés en exemple par ceux de votre session. L’exemple cURL nécessite jq :

Identifier l’agent qui a exécuté une commande déléguée

JavaScript

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'

Pour paginer manuellement, utilisez le last_id renvoyé comme valeur de after pour la page suivante lorsque has_more vaut true. L’exemple en Go parcourt ces pages automatiquement.

Chaque élément de commande contient un turn_id. Récupérez le tour correspondant et consultez son subagent_id pour identifier le sous-agent qui a exécuté la commande. Si l’identifiant du sous-agent vaut null, c’est l’agent racine qui a exécuté la commande. L’API ne signale pas si la sortie de la commande a été tronquée.

Examiner la trace d’un tour

Dans le tableau de bord de la plateforme, examinez un tour terminé et l’activité des agents pendant ce tour. Pour récupérer les traces enregistrées via l’API publique, utilisez le point de terminaison d’exportation des traces de session avec une clé API de projet. Les points de terminaison de traçage du tableau de bord sont distincts de ceux de l’API prise en charge pour les clients.

Les ressources de tour comprennent un champ usage renseigné selon les données disponibles et un champ subagent_id qui permet d’identifier le travail délégué. Si la consommation est inconnue, sa valeur peut être null. La valeur enregistrée peut évoluer. Consultez la section Consulter la consommation de tokens des sous-agents.

Pour identifier l’agent qui a exécuté une commande shell, récupérez le tour indiqué par le champ turn_id de l’élément de commande, puis consultez turn.subagent_id. L’API destinée aux clients n’indique pas si la sortie de la commande a été tronquée.

Erreurs et reprise

Consultez la section Erreurs et reprise pour analyser un échec, choisir une méthode de reprise et relancer l’opération en toute sécurité.

Utilisation du modèle et coût

Un agent peut appeler le modèle plusieurs fois pour accomplir une tâche. Comme dans l’API Responses, chaque appel est soumis à la tarification des tokens et aux règles de mise en cache des prompts du modèle. Pour estimer le coût d’une tâche, tenez compte de tous les appels nécessaires à son exécution.

Quels éléments entrent dans le calcul du coût ?

Chaque appel au modèle peut consommer les catégories de tokens suivantes :

Tokens d’entrée : instructions de l’agent, définitions d’outils, historique de conversation, saisie de l’utilisateur, fichiers ou images et résultats des outils.
Tokens d’entrée mis en cache : tokens réutilisés lorsque le préfixe du prompt correspond à celui d’un appel précédent. Ils sont facturés au tarif du modèle pour les entrées mises en cache.
Tokens de sortie : texte généré, arguments des appels d’outils et raisonnement.

Les tokens de raisonnement sont facturés comme des tokens de sortie.

Les sous-agents peuvent eux aussi appeler le modèle. Pour analyser les coûts du modèle, consultez leur consommation enregistrée par tour en plus de celle de l’agent racine.

Tenez compte du travail de l’agent racine et des sous-agents, y compris des nouvelles tentatives. Ajoutez les frais éventuels liés aux outils, aux ressources de calcul du bac à sable et aux services tiers. Certains modèles facturent également l’écriture des données d’entrée dans le cache. Les champs de consommation de l’API Agents décrits ci-dessous ne fournissent pas de décompte distinct des tokens écrits dans le cache. Ils ne permettent donc pas de déterminer le montant exact facturé pour le modèle lorsque ce tarif s’applique.

Mise en cache des prompts

Les agents conservent le contexte d’un tour à l’autre au sein d’une session. Lorsque des appels successifs au modèle partagent le même préfixe de prompt, la mise en cache des prompts permet de réutiliser le résultat du traitement de ce préfixe. Le modèle génère une nouvelle réponse à chaque appel, même lorsqu’il utilise le cache. Garder une session ouverte ne garantit pas que le cache sera utilisé. La réutilisation dépend de la correspondance des préfixes ainsi que des règles du modèle concernant l’admissibilité à la mise en cache et la durée de conservation.

Dans la mesure du possible, conservez les mêmes instructions initiales et définitions d’outils, et précisez les nouveaux détails de la tâche dans les messages suivants. Avec la recherche d’outils, les définitions des outils trouvés sont ajoutées à la fin de la conversation. Le contenu précédent reste ainsi disponible pour une réutilisation depuis le cache. Consultez la section Mise en cache des prompts pour connaître les règles propres à chaque modèle.

Une proportion élevée de tokens d’entrée mis en cache ne permet pas de mesurer les économies réalisées sur le coût total de la tâche. Les entrées mises en cache restent facturées et les appels successifs peuvent traiter un historique volumineux. Comparez les coûts d’exécution d’une même tâche pour la qualité et la latence requises par votre application.

Comprendre la consommation de tokens

Les ressources de session et de tour fournissent un champ usage, renseigné selon les données disponibles. Sa valeur peut être null lorsque la consommation est inconnue, et les décomptes enregistrés peuvent évoluer à mesure que les données de consommation sont comptabilisées. L’absence de données ne signifie pas que la consommation est nulle. Ces décomptes ne constituent pas une facture définitive.

Un objet de consommation enregistré contient les catégories de tokens suivantes :

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

Dans cet exemple, l’agent a traité 5 000 tokens d’entrée et généré 900 tokens de sortie. Parmi les tokens d’entrée, 1 500 étaient mis en cache. Parmi les tokens de sortie, 200 étaient des tokens de raisonnement.

Les tokens mis en cache sont inclus dans input_tokens et les tokens de raisonnement dans output_tokens.

Consulter la consommation de tokens des sous-agents

Listez ou récupérez les tours de session et consultez le champ usage de chaque tour. Le champ subagent_id identifie le sous-agent. Il vaut null pour les tours de l’agent racine. Lorsque has_more vaut true, passez last_id comme valeur de after en conservant la même valeur de order pour lire les tours restants.

La consommation est enregistrée selon les données disponibles. Sa valeur peut être null lorsqu’elle est inconnue, et les valeurs enregistrées peuvent évoluer. Vous pouvez également consulter la consommation enregistrée pour chaque agent dans le tableau de bord de traçage.

Suggestions

Premiers pas

Notions fondamentales

SDK et CLI

Fournisseurs de services cloud

Ressources

Anciennes API

Choisissez un modèle

Texte et code

Rédaction de prompts

Raisonnement

Images

Temps réel et audio

Modèles spécialisés

API Agents

Agents SDK

ChatKit

Recherche et récupération d’informations

Connectez des outils et des sources de données

Créez des workflows qui font appel à des outils

Ordinateur et code

Médias

GPT-Live

Realtime API

Créer des applications vocales

Connexions

Traitement audio

Mise en production

Performances et qualité

Évaluation

Coût et débit

Sécurité et gouvernance

Infrastructure et accès

Opérations

Concepts clés

Planification

Développement

Tests et publication

Spécifications de conversion

Guides

Ressources

Identité

Utilisation du forfait ChatGPT

Guides

Envoi de fichiers

API

Mesure des performances

API pour les annonceurs

Référence de l’API

Premiers pas

Premiers pas

Notions de base

Explorer

Disponible sur

Versions

Workflows

Capacités

Sites

dots

Espace ChatGPT

Référence

Personnalisation

Fichier de configuration

Configuration des agents

Étendre les fonctionnalités de ChatGPT et de Codex

Linux

Windows

Workflows de développement

Extensions et automatisation

Environnements

Codex Cloud

Développer avec Codex

Intégrations tierces

Référence

Autorisations

Codex Security

Cybersécurité

Premiers pas

Configuration des fonctionnalités

Identité et accès