> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wandb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Koog

> Tracez des agents Koog écrits en Kotlin avec Weave à l'aide d'OpenTelemetry afin de capturer les appels aux outils, les prompts et les complétions pour les applications d'IA.

[Koog](https://docs.koog.ai/) 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.

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541/fD1bUyy5aNOhG-mQ/weave/guides/integrations/imgs/koog.png?fit=max&auto=format&n=fD1bUyy5aNOhG-mQ&q=85&s=fba4e39044527fa713f69e97886035c4" alt="Koog" width="3451" height="1985" data-path="weave/guides/integrations/imgs/koog.png" />
</Frame>

<div id="prerequisites">
  ## Prérequis
</div>

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.

```bash theme={null}
export WEAVE_API_KEY="[YOUR-API-KEY]"
export WEAVE_ENTITY="[YOUR-ENTITY]"
export WEAVE_PROJECT_NAME="koog-tracing"
```

<div id="install-koog-gradle">
  ## Installer Koog (Gradle)
</div>

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) :

```kotlin theme={null}
dependencies {
    implementation("ai.koog:koog-agents:LATEST_VERSION")
}
```

Voir la documentation de Koog pour [plus d’informations sur l’installation](https://docs.koog.ai/).

<div id="enable-weave-export-opentelemetry">
  ## Activer l’export Weave (OpenTelemetry)
</div>

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` :

```kotlin theme={null}
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](https://api.koog.ai/agents/agents-features/agents-features-opentelemetry/ai.koog.agents.features.opentelemetry.integration.weave/add-weave-exporter.html?query=fun%20OpenTelemetryConfig.addWeaveExporter\(weaveOtelBaseUrl:%20String?%20=%20null,%20weaveEntity:%20String?%20=%20null,%20weaveProjectName:%20String?%20=%20null,%20weaveApiKey:%20String?%20=%20null,%20timeout:%20Duration%20=%2010.seconds\)) pour l’exportateur, comme dans l’exemple suivant :

```kotlin theme={null}
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](https://docs.koog.ai/opentelemetry-weave-exporter/) pour plus d’informations sur l’exportateur
* [Guide de prise en charge d’OpenTelemetry par Koog](https://docs.koog.ai/opentelemetry-support/) pour les concepts de base sur le fonctionnement d’OpenTelemetry avec Koog
* [Documentation OTEL de Weave](../tracking/otel) pour savoir comment Weave ingère les données OTLP

<div id="what-gets-traced">
  ## Ce qui est tracé
</div>

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](../tracking/tracing) pour une introduction à la capture de traces avec Weave.

<div id="example-notebook">
  ## Notebook d’exemple
</div>

Voir la documentation de Koog pour un [notebook exécutable](https://docs.koog.ai/examples/Weave/) qui transmet des traces à Weave.

<div id="troubleshooting">
  ## Dépannage
</div>

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](https://docs.koog.ai/opentelemetry-support/).