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

# Guide : Exécuter Votre Premier Outil

> Apprenez à découvrir, exécuter et récupérer les résultats des puissants outils asynchrones d'UBIK.

Ce guide montre comment tirer parti des outils d'UBIK pour effectuer des tâches complexes. Vous apprendrez à lister les outils disponibles, à en exécuter un avec les entrées requises, puis à interroger les résultats de l'exécution.

<Steps>
  <Step title="Lister les Outils Disponibles">
    D'abord, voyons quels outils sont disponibles. Nous pouvons obtenir une liste de tous les outils qui nous sont accessibles en effectuant une requête `GET` vers l'endpoint `/tools`.

    <CodeGroup title="GET /tools">
      ```bash cURL theme={null}
      curl -X GET "https://app.ubik-agent.com/api/v1/tools" \
           -H "X-API-KEY: VOTRE_CLE_API"
      ```

      ```python Python theme={null}
      import requests

      api_key = "VOTRE_CLE_API"
      headers = {"X-API-KEY": api_key}

      response = requests.get("https://app.ubik-agent.com/api/v1/tools", headers=headers)

      if response.status_code == 200:
          tools = response.json()
          print(tools['items'])
      else:
          print(f"Erreur: {response.status_code}", response.text)
      ```

      ```javascript JavaScript theme={null}
      const apiKey = "VOTRE_CLE_API";
      const url = "https://app.ubik-agent.com/api/v1/tools";

      fetch(url, {
        method: 'GET',
        headers: { 'X-API-KEY': apiKey }
      })
      .then(response => {
        if (!response.ok) {
          throw new Error(`Erreur HTTP: ${response.status}`);
        }
        return response.json();
      })
      .then(data => console.log(data.items))
      .catch(error => console.error('Erreur:', error));
      ```
    </CodeGroup>

    La réponse sera une liste paginée d'outils. Pour ce guide, supposons que nous voulons utiliser un outil nommé **"Extracteur de Données Financières"**. Trouvez-le dans la liste et copiez son `id`.
  </Step>

  <Step title="Exécuter l'Outil">
    Maintenant, nous allons démarrer l'outil en effectuant une requête `POST` vers l'endpoint `/tools/{tool_id}/execute`. Vous aurez besoin de l'`id` de l'étape précédente. Dans le corps de la requête, nous fournirons les `inputs` requis par l'outil.

    <CodeGroup title="POST /tools/{tool_id}/execute">
      ```bash cURL theme={null}
      curl -X POST "https://app.ubik-agent.com/api/v1/tools/VOTRE_ID_OUTIL/execute" \
           -H "X-API-KEY: VOTRE_CLE_API" \
           -H "Content-Type: application/json" \
           -d '{
                "inputs": {
                  "document_id": "VOTRE_ID_DOCUMENT",
                  "data_points": ["revenue", "net_income", "ebitda"]
                }
              }'
      ```

      ```python Python theme={null}
      import requests

      api_key = "VOTRE_CLE_API"
      tool_id = "VOTRE_ID_OUTIL"

      headers = {
          "X-API-KEY": api_key,
          "Content-Type": "application/json"
      }
      payload = {
          "inputs": {
              "document_id": "VOTRE_ID_DOCUMENT",
              "data_points": ["revenue", "net_income", "ebitda"]
          }
      }

      response = requests.post(
          f"https://app.ubik-agent.com/api/v1/tools/{tool_id}/execute",
          headers=headers,
          json=payload
      )

      if response.status_code == 202: # Accepted
          execution_info = response.json()
          print(execution_info)
          # Sauvegardez l'execution_id pour vérifier le statut plus tard
      else:
          print(f"Erreur: {response.status_code}", response.text)
      ```

      ```javascript JavaScript theme={null}
      const apiKey = "VOTRE_CLE_API";
      const toolId = "VOTRE_ID_OUTIL";
      const url = `https://app.ubik-agent.com/api/v1/tools/${toolId}/execute`;

      const payload = {
        inputs: {
          document_id: "VOTRE_ID_DOCUMENT",
          data_points: ["revenue", "net_income", "ebitda"]
        }
      };

      fetch(url, {
        method: 'POST',
        headers: {
          'X-API-KEY': apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(payload)
      })
      .then(response => {
        if (response.status !== 202) { // Accepted
          throw new Error(`Erreur HTTP: ${response.status}`);
        }
        return response.json();
      })
      .then(executionInfo => {
        console.log(executionInfo);
        // Sauvegardez l'execution_id pour vérifier le statut plus tard
      })
      .catch(error => console.error('Erreur:', error));
      ```
    </CodeGroup>

    L'API répondra avec un statut `202 Accepted`, indiquant que la tâche a été reçue. Le corps de la réponse contient un `execution_id` et une `details_url`. Nous utiliserons cette URL pour obtenir le résultat final.

    <Tip>
      **Isolation des Utilisateurs**: Si vous exécutez des outils pour le compte de vos utilisateurs finaux, vous pouvez isoler leurs données en passant l'en-tête `X-End-User-ID`.

      `curl -H "X-End-User-ID: user_123" ...`

      Pour plus de détails sur l'isolation des données et le multi-tenancy, voir le [Guide Authentification & Sécurité](/fr/guides/authentication).
    </Tip>
  </Step>

  <Step title="Vérifier le Résultat de l'Exécution">
    Comme l'outil s'exécute de manière asynchrone, nous devons interroger la `details_url` pour vérifier le résultat final. Vous devrez vérifier cet endpoint périodiquement jusqu'à ce que le `status` passe à `completed` ou `failed`.

    <CodeGroup title="GET /tool-executions/{execution_id}">
      ```bash cURL theme={null}
      curl -X GET "https://app.ubik-agent.com/api/v1/tool-executions/VOTRE_ID_EXECUTION" \
           -H "X-API-KEY: VOTRE_CLE_API"
      ```

      ```python Python theme={null}
      import requests
      import time

      api_key = "VOTRE_CLE_API"
      execution_id = "VOTRE_ID_EXECUTION"

      headers = {"X-API-KEY": api_key}
      url = f"https://app.ubik-agent.com/api/v1/tool-executions/{execution_id}"

      while True:
          response = requests.get(url, headers=headers)
          if response.status_code == 200:
              result = response.json()
              print(f"Statut actuel: {result['status']}")
              if result['status'] in ['completed', 'failed']:
                  print("Résultat Final:", result)
                  break
          else:
              print(f"Erreur de polling: {response.status_code}", response.text)
              break
          time.sleep(5) # Attendre 5 secondes avant de recommencer
      ```

      ```javascript JavaScript theme={null}
      const apiKey = "VOTRE_CLE_API";
      const executionId = "VOTRE_ID_EXECUTION";
      const url = `https://app.ubik-agent.com/api/v1/tool-executions/${executionId}`;

      const pollResult = async () => {
        try {
          const response = await fetch(url, {
            headers: { 'X-API-KEY': apiKey }
          });

          if (!response.ok) {
            throw new Error(`Erreur HTTP: ${response.status}`);
          }

          const result = await response.json();
          console.log(`Statut actuel: ${result.status}`);

          if (result.status === 'completed' || result.status === 'failed') {
            console.log('Résultat Final:', result);
            // Arrêter le polling
          } else {
            setTimeout(pollResult, 5000); // Réinterroger dans 5 secondes
          }
        } catch (error) {
          console.error('Erreur de polling:', error);
        }
      };

      pollResult();
      ```
    </CodeGroup>

    Une fois que le statut est `completed`, le champ `outputs` contiendra les données extraites par l'outil.

    <Tip>
      Pour une expérience plus réactive et en temps réel, vous pouvez streamer les événements au lieu de faire du polling. Consultez notre guide sur [l'Obtention de Résultats en Temps Réel avec SSE](/fr/guides/streaming-results).
    </Tip>
  </Step>
</Steps>

Vous savez maintenant comment découvrir et exécuter des outils puissants et pré-construits pour automatiser des séquences d'actions complexes avec l'API UBIK.