Outils

En cours d'appel, l'agent décide quand invoquer un outil en fonction de ce que l'appelant a dit et de ce que la description de votre outil indique qu'il fait. Pour un outil personnalisé, Aethex effectue un appel HTTPS serveur-à-serveur vers votre point d'accès et renvoie la réponse dans la conversation :

Toute la boucle s'exécute à l'intérieur de l'appel, avec l'appelant en attente. Gardez votre point d'accès rapide : une réponse en moins d'une seconde est idéale. L'agent obtient toujours une réponse en moins de 9 secondes, et ce délai couvre la résolution DNS, la connexion et la réponse entière.

Chaque agent obtient ces deux automatiquement. Ils sont activés par la configuration sur l'agent (end_call_enabled, transfer_phone_number), sans rien enregistrer.

Enregistrez votre propre outil avec un seul POST. Le pipeline l'intègre lors du prochain appel vers cet agent.

Champs

Enregistrer un outil

import os, requests

API_KEY = os.environ["AETHEX_API_KEY"]
BASE_URL = "https://api.aethexai.com/api/v1"
AGENT_ID = "ag_..."

resp = requests.post(
    f"{BASE_URL}/agents/{AGENT_ID}/tools",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "name": "lookup_order",
        "description": (
            "Look up the status of a customer order by order ID. "
            "Use when the caller asks about an order or shipment they have placed."
        ),
        "parameters_schema": {
            "type": "object",
            "properties": {
                "order_id": {
                    "type": "string",
                    "description": "The order ID, alphanumeric. Example: A1B2C3.",
                },
            },
            "required": ["order_id"],
        },
        "endpoint_url": "https://orders.example.com/aethex/lookup",
        "headers": {"Authorization": "Bearer your-shared-secret"},
    },
)
resp.raise_for_status()
print(resp.json())

Quand le LLM invoque un outil personnalisé, Aethex appelle votre endpoint_url avec la méthode http_method configurée (POST par défaut). Vous avez 9 secondes pour répondre, résolution DNS, connexion et réponse entière comprises.

Requête POST (par défaut)

{
  "arguments": {
    "order_id": "A1B2C3"
  },
  "agent_id": "ag_...",
  "conversation_id": "co_...",
  "call_id": "ca_..."
}

Requête GET

Pour http_method: GET, les arguments LLM sont ajoutés à l'URL comme paramètres de requête et les identifiants contextuels sont transmis comme en-têtes. Aucun corps n'est envoyé. Note : les arguments apparaissent dans les journaux d'accès de votre serveur web.

GET /aethex/lookup?order_id=A1B2C3&in_stock=true&tags=%5B%22prime%22%5D
Host: orders.example.com
X-Aethex-Agent-Id: ag_...
X-Aethex-Conversation-Id: co_...
X-Aethex-Call-Id: ca_...
(no body)

Réponse

Retournez un corps JSON avec tout ce que l'agent doit savoir. Aethex injecte la réponse entière dans le LLM comme résultat de l'outil, donc structurez-la pour que le LLM puisse la lire (paires clé/valeur, champs en langage naturel).

{
  "status": "shipped",
  "tracking_number": "1Z999AA10123456784",
  "estimated_delivery": "Tomorrow, 3 PM"
}

Erreurs

Toute erreur 4xx, 5xx, expiration du délai ou défaillance réseau est capturée en tant qu'erreur d'outil et transmise au LLM sous la forme d'un objet JSON tel que {"error": "<reason>"}. L'agent la gère alors de manière appropriée (reconnaît l'échec, propose un transfert). L'appel n'est jamais interrompu en raison de l'indisponibilité de votre endpoint. Si un outil échoue, il répond quand même à l'agent : l'appel ne reste jamais bloqué en l'attendant.

Une fois que votre agent a des outils, donnez-lui des connaissances fondées : consultez Base de connaissances pour télécharger des documents de référence que l'agent peut utiliser au moment de l'appel.