Terminez d'abord "Travailler avec NoSQL et les bases de données vectorielles" pour débloquer cette leçon.Aller à la leçon précédente

Introduction

Les agents IA deviennent utiles lorsqu07 ils peuvent parler avec le monde extérieur. Les API REST sont le moyen le plus courant par lequel les systèmes exposent des fonctionnalités, donc un agent doit pouvoir les appeler à la demande. Le défi est que la plupart des API sont conçues pour des clients pilotés par l07 humain (tableaux de bord, applications mobiles), et non pour des décideurs autonomes. Avant qu07 un agent puisse utiliser une API, il faut traduire le contrat d07 API en quelque chose que l07 agent peut comprendre et invoquer.

Envelopper une API en un outil

Un outil, du point de vue de l07 agent, est une fonction avec un nom, une description et un ensemble de paramètres. Vous construisez une mince enveloppe qui reçoit une entrée structurée de l07 agent (par exemple, un nom de ville) et renvoie un résultat structuré.

python
import requests
def get_weather(city: str) -> dict:
url = "https://api.example.com/weather"
params = {"q": city, "units": "metric"}
response = requests.get(url, params=params, timeout=10)
response.raise_for_status()
return response.json()

L07 enveloppe masque les détails HTTP (en-têtes, codes d07 statut, analyse JSON) et expose une signature de fonction propre. L07 agent ne voit que le nom de la fonction, son docstring ou sa description, et les paramètres typés.

Structurer la Description pour l07 Agent

La description est ce qui indique à l07 agent quand et comment appeler l07 outil. Une bonne description d07 outil comporte trois parties : un résumé d07 une ligne de ce que fait l07 outil, une note sur quand l07 utiliser (et tout aussi important, quand ne pas l07 utiliser), et une description de chaque paramètre incluant le format et les contraintes.

json
{
"name": "get_weather",
"description": "Get current weather for a city. Use when the user asks about weather, temperature, or conditions outdoors. Do not use for forecasts beyond 24 hours.",
"parameters": {
"city": {
"type": "string",
"description": "City name in English, e.g. 'Hanoi' or 'Tokyo'"
}
}
}

Restez factuel dans les descriptions. Évitez les mots accrocheurs comme « puissant » ou « avancé » — l07 agent prend des décisions d07 appel en fonction de l07 utilité, pas du langage marketing.

diagramme de flux montrant que l07 agent reçoit la requête utilisateur, décide quel outil appeler en fonction de la description, envoie les paramètres à l07 enveloppe, l07 enveloppe appelle l07 API HTTP et renvoie le résultat structuré à l07 agent

Gestion des limites de taux, de la pagination et des erreurs

Les API échouent de manière prévisible. Votre wrapper doit gérer ces échecs afin que l’agent obtienne des retours utiles plutôt que des traces de pile brutes.

Pour les limites de taux, respectez l’en-tête Retry-After lorsque présent et rétro-pédez de manière exponentielle en cas de multiples réponses 429. Enveloppez l’appel dans une boucle de réessai avec un nombre maximal de tentatives pour éviter les attentes infinies.

python
import time
import requests
def call_with_retry(url, params, max_attempts=3):
for attempt in range(max_attempts):
response = requests.get(url, params=params, timeout=10)
if response.status_code == 429:
wait = int(response.headers.get("Retry-After", 2 ** attempt))
time.sleep(wait)
continue
response.raise_for_status()
return response.json()
raise Exception("Rate limited after retries")

Pour la pagination, concevez le wrapper pour qu’il accepte un paramètre de page ou de curseur et renvoie un signal clair lorsque d’autres pages sont disponibles. Laissez l’agent décider s’il continue à récupérer — il peut raisonner sur le coût et la pertinence mieux qu’une boucle codée en dur.

Pour les erreurs, retournez un objet structuré au lieu d’élever des exceptions sans discernement. Incluez le code d’état, une raison courte lisible et éventuellement un indice sur la manière de récupérer. Cela permet à l’agent de réessayer avec des paramètres corrigés, de changer d’outil ou de signaler le problème à l’utilisateur.

Résumé

Considérez chaque API comme un outil avec trois couches : une signature de fonction propre, une description précise que l’agent peut utiliser pour la sélection, et un wrapper robuste qui gère les réalités dérangeantes du HTTP — réessais, pagination et signalement des erreurs. Le wrapper est le contrat entre un service externe instable et un agent de raisonnement qui a besoin d’inputs prévisibles pour prendre de bonnes décisions.

Erreurs courantes

Wrappe une API sans une description précisant quand ne pas l’utiliser. Laisser les exceptions brutes remonter à l’agent au lieu de renvoyer des objets d’erreur structurés. Programmer des boucles de pagination en dur pour empêcher l’agent de sauter des pages ou d’arrêter tôt. Ignorer l’en-tête Retry-After et utiliser des délais fixes qui vous font interdire plus rapidement.

Entraînement

Point de contrôle de la leçon

Révisez la leçon et recevez des conseils sur votre travail.

0/1
Répondu · 0/1