Koog - CoreWeave Docs

Koog est un framework basé sur Kotlin permettant de créer des agents à run unique ainsi que des agents à flux de travail complexes. Koog prend en charge nativement OpenTelemetry (OTEL) et peut exporter les traces directement vers Weave, ce qui vous donne une visibilité sur les prompts, les complétions, les appels d’outils et l’exécution de bout en bout de vos agents. Ce guide explique comment configurer l’exportateur Weave de Koog afin que vos agents Kotlin transmettent leurs spans OpenTelemetry à un projet Weave. Une fois l’exportateur activé, vous pouvez déboguer les runs de vos agents, analyser leurs performances et itérer plus rapidement. Ce guide s’adresse aux développeurs Kotlin qui créent déjà des agents avec Koog et souhaitent y ajouter le traçage Weave.

Prérequis

Avant d’exécuter votre agent, vous devez définir les variables d’environnement suivantes pour que l’exportateur Weave puisse s’authentifier et acheminer les traces vers le bon projet : Remplacez [YOUR-API-KEY] par votre clé API CoreWeave Forge et [YOUR-ENTITY] par le nom de votre équipe ou de votre entity CoreWeave Forge. La valeur de WEAVE_PROJECT_NAME peut être n’importe quel nom de projet. Weave crée le projet lors de sa première utilisation.

export WEAVE_API_KEY="[YOUR-API-KEY]"
export WEAVE_ENTITY="[YOUR-ENTITY]"
export WEAVE_PROJECT_NAME="koog-tracing"

Installer Koog (Gradle)

Une fois vos variables d’environnement définies, ajoutez Koog à votre projet Kotlin pour pouvoir configurer l’agent et son exportateur (exemple avec le DSL Kotlin) :

dependencies {
    implementation("ai.koog:koog-agents:LATEST_VERSION")
}

Consultez la documentation de Koog pour plus d’informations sur l’installation.

Activer l’export vers Weave (OpenTelemetry)

Après avoir installé Koog, installez la fonctionnalité OpenTelemetry de Koog et ajoutez l’exportateur Weave. Les spans Koog sont ainsi convertis en traces Weave via le point de terminaison OpenTelemetry de Weave. L’exemple suivant montre comment utiliser addWeaveExporter :

fun main() = runBlocking {
    val apiKey = "api-key"
    val entity = System.getenv()["WEAVE_ENTITY"] ?: throw IllegalArgumentException("WEAVE_ENTITY is not set")
    val projectName = System.getenv()["WEAVE_PROJECT_NAME"] ?: "koog-tracing"

    val agent = AIAgent(
        executor = simpleOpenAIExecutor(apiKey),
        llmModel = OpenAIModels.CostOptimized.GPT4oMini,
        systemPrompt = "You are a code assistant. Provide concise code examples."
    ) {
        install(OpenTelemetry) {
            addWeaveExporter()
        }
    }

    println("Running agent with Weave tracing")

    val result = agent.run("""
        Create a Python function to calculate fibonacci numbers efficiently,
        include error handling, type hints, and unit tests.
        Verify the implementation works for n=50.
    """)

    println("Result: $result\nSee traces on https://forge.coreweave.com/wandb/$entity/$projectName/weave/traces")
}

La fonction lit automatiquement vos variables d’environnement Weave, mais vous pouvez également configurer des paramètres spécifiques pour l’exportateur, comme dans l’exemple suivant :

install(OpenTelemetry) {
    addWeaveExporter(
        weaveOtelBaseUrl = "https://trace.wandb.ai",
        weaveEntity = System.getenv()["WEAVE_ENTITY"],
        weaveProjectName = System.getenv()["WEAVE_PROJECT_NAME"],
        weaveApiKey = System.getenv()["WEAVE_API_KEY"],
        timeout = 10.seconds
    )
}

L’exemple précédent :

Utilise weaveEntity et weaveProjectName pour acheminer les traces vers une équipe et un projet spécifiques.
Définit weaveOtelBaseUrl sur votre point de terminaison de traces (par exemple, https://[YOUR-SUBDOMAIN].wandb.io/[PATH]). Utilisez ce paramètre pour les instances Weave dédiées.

Si vous utilisez Koog avec Weave pour la première fois, consultez la documentation suivante :

Guide de l’exportateur Weave de Koog pour en savoir plus sur l’exportateur
Guide de la prise en charge d’OpenTelemetry dans Koog pour les concepts fondamentaux du fonctionnement d’OpenTelemetry avec Koog
Documentation OTEL de Weave pour comprendre comment Weave ingère les données OTLP

Éléments tracés

Une fois que vous avez exécuté un agent avec l’exportateur activé, Koog transmet les traces à votre projet Weave. L’exportateur Weave de Koog capture les mêmes spans que l’intégration OTEL générale de Koog, notamment :

Les événements du cycle de vie de l’agent (démarrage, arrêt, erreurs)
Les interactions avec le LLM (prompts, complétions, utilisation des jetons, latence)
Les appels d’outils et d’API (appels de fonctions et requêtes externes)
Le contexte système (nom du modèle, version de Koog, métadonnées de l’environnement)

Vous pouvez visualiser ces traces dans l’interface de Weights & Biases pour analyser les performances et la qualité. Consultez l’aperçu du traçage de Weave pour découvrir comment capturer des traces avec Weave.

Notebook d’exemple

Consultez la documentation de Koog pour accéder à un notebook exécutable qui envoie des traces en continu vers Weave.

Dépannage

Si votre agent Koog n’exporte pas les traces comme prévu, vérifiez les points suivants :

Si des traces sont manquantes, vérifiez d’abord que les variables WEAVE_API_KEY, WEAVE_ENTITY et WEAVE_PROJECT_NAME sont correctement définies.
Assurez-vous que votre environnement peut joindre https://trace.wandb.ai et que l’exportateur est configuré comme dans les exemples précédents.
Pour plus de conseils sur le dépannage et l’échantillonnage, consultez la page OpenTelemetry support de la documentation Koog.

​Prérequis

​Installer Koog (Gradle)

​Activer l’export vers Weave (OpenTelemetry)

​Éléments tracés

​Notebook d’exemple

​Dépannage