Nutzungserfassung

CodeCourier bietet eine umfassende Nutzungserfassung, die jede während des KI-Agentenbetriebs verbrauchte Ressource aufzeichnet. Von einzelnen Token-Zählungen bis zur Sandbox-Laufzeit, von der Zuordnung pro Schritt bis zu täglichen Kostentrends - das Nutzungssystem bietet vollständige Transparenz darüber, was Ihre KI-Workflows kosten und wohin das Geld fließt. Diese Seite erklärt, was erfasst wird, wie das Analyse-Dashboard funktioniert und wie Sie Ihre Nutzung optimieren.

Was erfasst wird

Jede Operation, die externe Ressourcen verbraucht, wird als usageRecord in der Convex-Datenbank festgehalten. Jeder Datensatz erfasst:

• Projekt -- Welches Projekt die Nutzung erzeugt hat.
• Dienst -- Welcher Dienst verbraucht wurde (anthropic, openai, openrouter, e2b, trigger_dev, convex).
• Datum -- Der ISO-Datumsstring (YYYY-MM-DD), an dem die Nutzung stattfand.
• Menge -- Die verbrauchte Menge (Tokens, Sekunden, Bytes usw.).
• Einheit-- Was verbraucht wurde (z. B. "input_tokens", "output_tokens", "sandbox_seconds").
• Kosten (USD) -- Die berechneten Dollar-Kosten basierend auf den anwendbaren Tarifen.

Erfasste Metriken nach Dienst

Anthropic / OpenAI / OpenRouter

• Input-Tokens -- An das KI-Modell als Kontext gesendete Tokens (System-Prompt, Konversationsverlauf, Code-Dateien).
• Output-Tokens -- Vom KI-Modell als Antwort erzeugte Tokens.
• Total-Tokens -- Falls keine Input/Output-Aufteilung verfügbar ist, wird die kombinierte Summe erfasst.

E2B-Sandboxes

• Sandbox-Sekunden -- Aktive VM-Laufzeit von der Erstellung bis zur Beendigung.

Trigger.dev

• Task-Ausführungszeit -- Dauer der Hintergrundjob-Ausführung.

Zuordnungsfelder

Jeder Nutzungsdatensatz kann optional detaillierte Zuordnungsinformationen enthalten:

• runId -- Welcher Workflow-Run diese Nutzung erzeugt hat.
• sandboxId -- Welche Sandbox beteiligt war.
• chainId -- Welche Sprint-Chain, falls zutreffend.
• issueSessionId -- Welche Issue-Sitzung, falls zutreffend.
• toolId -- Welches CLI-Tool verwendet wurde (claude, opencode, codex).
• modelId -- Die exakt verwendete KI-Modell-ID.
• stepType -- Welcher Pipeline-Schritt (Designer, Checker, Optimizer usw.).
• stepIndex -- Die Iterationsnummer innerhalb des Schritts.
• userId -- Welches Teammitglied die Operation ausgelöst hat.
• personaId -- Welche Persona dafür verantwortlich war.
• durationMs -- Ausführungszeit des Schritts in Millisekunden.

Nutzungs-Dashboard

Die Nutzungsanalysen sind über Ihr Projekt-Dashboard erreichbar. Das Analyse-System bietet mehrere Query-Endpunkte für verschiedene Ansichten:

Projektnutzungs-Zusammenfassung

Die Query usage.getProjectUsageSummary liefert die aggregierte Nutzung für ein Projekt über einen Zeitraum. Sie speist die Übersichtskarten mit Gesamtkosten, Gesamt-Tokens und Gesamt-Sandbox-Stunden.

Nutzungs-Zusammenfassung mit Vergleich

Die Query usage.getProjectUsageSummaryWithComparison gibt die Zusammenfassung des aktuellen Zeitraums zusammen mit dem vorherigen für eine Trendanalyse zurück. So kann das Dashboard prozentuale Änderungen (auf- oder abwärts) gegenüber dem äquivalenten Vorzeitraum anzeigen.

Nutzung pro Tag

Die Query usage.getProjectUsageByDay liefert tägliche Kostensummen und ermöglicht Zeitreihen-Diagramme, die Ausgabenmuster im Zeitverlauf zeigen. Damit lassen sich Spitzen und Trends identifizieren.

Nutzung nach Dienst

Die Query usage.getProjectUsageByService schlüsselt die Kosten nach Dienstkategorie auf (Claude Code, E2B, Trigger.dev usw.) und zeigt, welche Dienste die meisten Ressourcen verbrauchen.

Aggregierte Nutzung

Die Query usage.getProjectUsageAggregated bietet eine flexible Aggregation, die die Nutzung nach verschiedenen Dimensionen gruppieren kann (Dienst, Modell, Tool, Schritttyp) und so detaillierte Analysen ermöglicht.

Analysen auf Run-Ebene

Für einzelne Runs bietet das Analyse-System:

• runAnalytics.getRunCostsBatch -- Batch-Kostenabruf für mehrere Runs (wird in Run-Listenansichten verwendet).
• runAnalytics.getRunDetailAnalytics -- Detaillierte Kostenaufschlüsselung für einen einzelnen Run, inklusive Token-Zählungen und Kosten pro Schritt.
• runAnalytics.getRunContextAnalytics -- Kontextuelle Analysen, die die Kosten eines Runs mit den Projekt-Durchschnitten vergleichen.

Projekt-Counter

Zusätzlich zu detaillierten Nutzungsdatensätzen pflegt CodeCourier denormalisierte Counter in der Tabelle projectCounters für ein schnelles Dashboard-Rendering:

• totalSandboxes / activeSandboxes -- Gesamtanzahl und aktuell laufende Sandboxes.
• totalRuns / completedRuns / failedRuns -- Run-Zählungen nach Status.
• totalWorkflows -- Anzahl der Workflow-Blueprints.
• totalMembers / pendingInvitations -- Teamgröße und ausstehende Einladungen.

Tagesstatistiken

Die Tabelle dailyStats liefert pro Projekt voraggregierte tägliche Aktivitätsmetriken:

• Pro Tag erstellte Sandboxes
• Pro Tag erstellte, abgeschlossene und fehlgeschlagene Runs
• Gesamte Iterationen über alle Runs pro Tag
• Pro Tag erstellte Workflows

Diese Counter werden inkrementell aktualisiert, sobald Operationen erfolgen, und vermeiden so teure Aggregationsabfragen auf großen Datenmengen.

Benachrichtigungen und Limits

Das Benachrichtigungssystem von CodeCourier erzeugt Benachrichtigungen für wichtige Ereignisse, die Ihre Kosten beeinflussen können:

• Run abgeschlossen / fehlgeschlagen -- Benachrichtigungen, wenn Workflow-Runs enden, damit Sie laufende Operationen im Blick behalten.
• Sprint abgeschlossen / fehlgeschlagen -- Benachrichtigungen zum Fortschritt von Sprint-Chains, die mehrere aufeinanderfolgende Runs umfassen können.
• PR erstellt / gemergt / fehlgeschlagen -- Benachrichtigungen zu Lebenszyklus-Ereignissen von Pull Requests.

Da die tatsächliche Abrechnung über Ihre externen Anbieterkonten erfolgt, empfehlen wir, zusätzlich Ausgaben-Benachrichtigungen direkt einzurichten bei:

• E2B -- Sandbox-Nutzung im E2B-Dashboard überwachen.
• Anthropic -- Nutzungslimits in der Anthropic-Konsole festlegen.
• OpenAI -- Ausgabengrenzen im OpenAI-Dashboard konfigurieren.

Nutzung optimieren

Token-Optimierung

• Fokussierte Prompts schreiben. Spezifische, klar umrissene Prompts reduzieren sowohl Input- als auch Output-Token-Verbrauch im Vergleich zu vagen Anweisungen.
• Passende Modelle einsetzen. Weisen Sie über das Persona-System kleinere, schnellere Modelle (wie Sonnet oder Haiku) einfachen Aufgaben zu. Reservieren Sie größere Modelle für komplexe Architekturarbeit.
• Iterationen begrenzen. Setzen Sie sinnvolle maxIterations in Designer-Checker-Workflows. Drei bis fünf Iterationen reichen meist aus.
• Learnings kuratieren. Gut kuratierte Learnings reduzieren verschwendete Iterationen, indem sie Agenten beibringen, häufige Fehler zu vermeiden.

Sandbox-Optimierung

• Passende Timeouts setzen. Kürzere Timeouts verhindern, dass vergessene Sandboxes endlos weiterlaufen.
• „Alle beenden“ nach Sitzungen verwenden. Wenn Sie fertig sind, beenden Sie alle laufenden Sandboxes, um keine weiteren Rechenkosten anfallen zu lassen.
• Eigene Templates nutzen. Templates mit vorinstallierten Abhängigkeiten ersparen die wiederholte Installationszeit (und die Token-Kosten, wenn der Agent Pakete installiert).

Workflow-Optimierung

• Single Designer für einfache Aufgaben verwenden. Nicht jede Aufgabe braucht einen Checker. Einfache, klar definierte Aufgaben können den Workflow-Typ „Single Designer“ nutzen.
• Run-Analysen prüfen. Nach Abschluss einer Reihe von Runs prüfen Sie die Kostenaufschlüsselung pro Run im Analyse-Dashboard. Identifizieren Sie ungewöhnlich teure Runs und passen Sie Ihre Workflow-Konfiguration entsprechend an.
• Issue-Sitzungen effektiv nutzen. Ein gut strukturierter Discovery-Prompt kann den Token-Verbrauch pro Issue reduzieren, indem er klarere, fokussiertere Vorschlags-Prompts erzeugt.

Datenaufbewahrung

Nutzungsdatensätze werden in der Convex-Datenbank unbegrenzt aufbewahrt. Tagesstatistiken werden voraggregiert und ebenfalls unbegrenzt aufbewahrt. Damit können Sie historische Trends analysieren und Kosten über beliebige Zeiträume vergleichen. Wenn Sie Nutzungsdaten für externe Buchhaltungssysteme exportieren möchten, können Sie die Nutzungs-Endpunkte programmatisch über die Convex-Client-Bibliothek abfragen.