Sessions untersuchen und Nutzung verfolgen

Verwende den Session-Viewer in der Claude Console, um zu untersuchen, was ein Agent in einer Session getan hat, ohne Code schreiben zu müssen. Verwende die usage-Summen der Session, um zu sehen, was diese Arbeit verbraucht hat.

Eine Session in der Console untersuchen

Der Session-Viewer ist nur für Developer und Admins zugänglich. Um ihn zu öffnen, gehe zur Seitenleiste der Console und wähle Sessions unter Managed Agents aus. Die Liste zeigt jede Session im Workspace mit ihrem Status, Agenten, ihrer Token-Nutzung, ihren Kosten und ihrem Erstellungszeitpunkt. Wähle eine Session aus, um sie zu öffnen.

Der Session-Viewer zeigt:

• Timeline-Minimap: Eine zoombare Übersicht über die Aktivität der Session im Zeitverlauf, mit einer Spur pro Thread in Multiagent-Sessions. Wähle eine Spur aus, um diesen Thread anzuzeigen, oder wähle eine Markierung aus, um zu ihrem Event zu springen.
• Transkript: Die Konversation gruppiert nach Modellanfrage, einschließlich Nachdenken, Tool-Aufrufen mit ihren Eingaben und Ergebnissen sowie Nachrichtentext, während er gestreamt wird. Du kannst die Events filtern und sie als JSON kopieren oder herunterladen.
• Inspector: Ein in der Größe veränderbares Seitenpanel mit Details zur Session, in fünf Tabs.

Hänge ?event={event_id} an eine Session-URL an, um die Session bei einem bestimmten Event zu öffnen.

Mit ant beta:sessions connect kannst du denselben Viewer über die ant-CLI öffnen oder die Session in deinem Terminal verfolgen. Siehe Von deinem Terminal aus eine Verbindung zu einer Managed-Agents-Session herstellen.

Nutzung verfolgen

Das Session-Objekt enthält ein Feld usage mit der kumulierten Nutzung der Session: Token-Zählungen, Server-Tool-Nutzung, aktive Zeit und die nachverfolgten Listenkosten. Rufe die Session ab, nachdem sie in den Leerlauf gegangen ist, um die neuesten Gesamtwerte zu lesen.

{
  "id": "sesn_01...",
  "status": "idle",
  "usage": {
    "input_tokens": 5000,
    "output_tokens": 3200,
    "cache_read_input_tokens": 20000,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 2000,
      "ephemeral_1h_input_tokens": 0
    },
    "list_cost": {
      "amount": "187",
      "currency": "USD"
    },
    "active_seconds": 342.5,
    "server_tool_use": {
      "web_search_requests": 3,
      "web_fetch_requests": 0
    }
  }
}

Cache-Einträge verwenden standardmäßig eine TTL von 5 Minuten, sodass direkt aufeinanderfolgende Turns innerhalb dieses Zeitfensters von Cache-Lesevorgängen profitieren, die die Kosten pro Token senken.

Das stats-Objekt der Session hat ein eigenes active_seconds, das die eigene aktive Zeit jedes Threads summiert, anstatt überlappende Aktivität einmal zu zählen.

Nutzung pro Thread

Auch die eigene usage jedes Session-Threads enthält list_cost und active_seconds. Die Werte pro Thread werden unabhängig voneinander gerundet und schließen die Laufzeitkosten der Session aus, sodass sie sich nicht exakt zum list_cost der Session summieren. Der Wert der Session ist maßgeblich.

Nutzung aus dem Stream lesen

Du musst die Session nicht abfragen, um diese Summen zu beobachten. Das session.usage-Event enthält denselben kumulativen Snapshot im Session-Stream und im Event-Verlauf. Der Snapshot enthält das usage-Objekt sowie das budget der Session, das null ist, wenn die Session keines hat.

Das Event wird bei Übergängen in den Leerlauf ausgegeben, nicht nach einem Timer:

• Die Session gibt eines unmittelbar aus, bevor sie in den Leerlauf wechselt, unabhängig vom Stop-Grund.
• Die Session gibt eines aus, wenn ein Thread bei einem Session-Budget pausiert.

Ein Ausgabenlimit durchsetzen

Um ein Ausgabenlimit durchzusetzen, lege ein Session-Budget fest, anstatt die Nutzung abzufragen und die Session selbst zu stoppen. Die Plattform bepreist den Verbrauch der Session kontinuierlich und pausiert jeden Thread vor seiner nächsten Modellanfrage, sobald die Listenkosten die Obergrenze erreichen. Siehe Wenn eine Sitzung ihr Budget erreicht, um zu sehen, wie das im Stream aussieht.

Tipps zum Debugging

• Session-Events prüfen: Die Session meldet Fehler über session.error-Events.
• Tool-Ergebnisse überprüfen: Fehlschläge bei der Tool-Ausführung erklären oft unerwartetes Agentenverhalten. Der Tools-Tab des Inspectors zeigt die Fehlschläge jedes Tools.
• System-Prompts verwenden: Füge dem System-Prompt Logging-Anweisungen hinzu, damit der Agent zusammenfasst, was er getan und was er gefunden hat.
• Fehlerbehebung bei Vorschauen: Wenn sich ein Stream, der Event-Deltas aktiviert, nicht wie erwartet verhält, siehe Fehlerbehebung bei Vorschauen.

Nächste Schritte