Koog

Koog est un framework Kotlin permettant de créer des agents à exécution unique ainsi que des agents pour des flux de travail complexes. Koog inclut une prise en charge native d’OpenTelemetry (OTEL) et peut exporter directement des traces vers Weave, vous offrant une visibilité détaillée sur les prompts, les complétions, les appels aux outils et l’exécution de l’agent de bout en bout. Ce guide vous montre comment configurer l’exportateur Weave de Koog afin que vos agents Kotlin transmettent les spans OpenTelemetry à un projet Weave. Avec l’exportateur activé, vous pouvez déboguer les runs d’agent, analyser les 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 ajouter le tracing Weave.

Prérequis

Vous devez définir les variables d’environnement suivantes avant d’exécuter votre agent afin que l’exportateur Weave puisse s’authentifier et acheminer les traces vers le projet approprié : Remplacez [YOUR-API-KEY] par votre clé API Weave et [YOUR-ENTITY] par le nom de votre équipe ou de votre entité W&B. La valeur de WEAVE_PROJECT_NAME peut être n’importe quel nom de projet. Weave crée le projet lors de la 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 afin de configurer l’agent et son exportateur (exemple en Kotlin DSL) :

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

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

Activer l’export Weave (OpenTelemetry)

Après avoir installé Koog, installez la fonctionnalité OpenTelemetry de Koog et ajoutez l’exportateur Weave. Cela fait correspondre les spans Koog aux traces Weave à l’aide du 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://wandb.ai/$entity/$projectName/weave/traces")
}

La fonction lit automatiquement les variables d’environnement Weave, mais vous pouvez aussi 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 comme point de terminaison de vos traces (par exemple, https://[YOUR-SUBDOMAIN].wandb.io/[PATH]). Utilisez ce paramètre pour les instances Weave dédiées.

Si vous débutez avec Koog et Weave, consultez la documentation suivante :

Guide de l’exportateur Weave de Koog pour plus d’informations sur l’exportateur
Guide de prise en charge d’OpenTelemetry par Koog pour les concepts de base sur le fonctionnement d’OpenTelemetry avec Koog
Documentation OTEL de Weave pour savoir comment Weave ingère les données OTLP

Ce qui est tracé

Après avoir exécuté un agent avec l’exportateur activé, Koog transfère les traces vers votre projet Weave. L’exportateur Weave de Koog capture les mêmes spans que l’intégration OTEL standard de Koog, notamment :

Événements du cycle de vie de l’agent (démarrage, arrêt, erreurs)
Interactions avec le LLM (prompts, complétion, utilisation des tokens, latence)
Appels d’outils et d’API (appels de fonction et requêtes externes)
Contexte système (nom du modèle, version de Koog, métadonnées de l’environnement)

Vous pouvez visualiser ces traces dans la Weave UI pour mieux comprendre les performances et la qualité. Voir l’Aperçu du tracing de Weave pour une introduction à la capture de traces avec Weave.

Notebook d’exemple

Voir la documentation de Koog pour un notebook exécutable qui transmet des traces à Weave.

Dépannage

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

Si des traces manquent, vérifiez d’abord que WEAVE_API_KEY, WEAVE_ENTITY et WEAVE_PROJECT_NAME sont correctement définis.
Vérifiez que votre environnement peut accéder à https://trace.wandb.ai et que l’exportateur est configuré comme indiqué dans les exemples précédents.
Pour plus d’informations sur le dépannage et l’échantillonnage, voir la prise en charge d’OpenTelemetry par Koog.

Premiers pas

Guides

Guides pratiques

Référence

Détails et assistance

Prérequis

Installer Koog (Gradle)

Activer l’export Weave (OpenTelemetry)

Ce qui est tracé

Notebook d’exemple

Dépannage

​Prérequis

​Installer Koog (Gradle)

​Activer l’export Weave (OpenTelemetry)

​Ce qui est tracé

​Notebook d’exemple

​Dépannage

Prérequis

Installer Koog (Gradle)

Activer l’export Weave (OpenTelemetry)

Ce qui est tracé

Notebook d’exemple

Dépannage