# Outil Function

POSTez les arguments du tool sur votre propre endpoint HTTPS et renvoyez la réponse JSON au LLM.

## Vue d'ensemble

L'outil Function est la façon de connecter l'agent à **vos** systèmes — CRM, ticketing, API internes, paiement, tout ce que vous avez déjà derrière un HTTP. Vous déclarez un JSON Schema pour les arguments, vous pointez vers un endpoint, et notre runtime gère l'aller-retour :

1. Vous déclarez un JSON Schema pour les args.
2. Le LLM génère un appel conforme.
3. Notre backend `POST` `{...args}` à votre URL (avec bearer token optionnel).
4. Votre endpoint applique sa logique et renvoie du JSON.
5. La réponse est injectée au LLM comme contexte pour son prochain tour.

Bouton **« Comment l'utiliser »** en haut de la modale pour un guide intégré — il reprend l'exemple ci-dessous.

## Configuration

| Champ | Type | Notes |
| --- | --- | --- |
| Nom | string | Identifiant unique vu par le LLM (ex. `create_ticket`). Court, snake_case. |
| Description | string | Dit au LLM *quand* appeler le tool. Soyez précis — c'est le champ le plus déterminant pour la qualité des appels. |
| URL d'endpoint | URL HTTPS | Où on POST. Doit être atteignable depuis notre backend. |
| JSON Schema des paramètres | objet JSON | JSON Schema standard. La modale valide la syntaxe à l'enregistrement. |
| Credential | optionnel | Sélectionne un credential stocké ; on envoie son token en `Authorization: Bearer <token>`. |
| Headers supplémentaires | clé/valeur | Headers statiques (ex. `X-Source: agent-builder`). |

Timeout par défaut 30 secondes ; surchargez avec `timeoutSeconds` au besoin.

## Exemple — `create_ticket`

**JSON Schema des paramètres :**

```json
{
  "type": "object",
  "properties": {
    "title":    { "type": "string" },
    "priority": { "type": "string", "enum": ["low", "medium", "high", "urgent"] },
    "body":     { "type": "string" }
  },
  "required": ["title", "priority"]
}
```

**Ce qui arrive sur votre endpoint :**

```http
POST https://api.vous.com/tickets
Authorization: Bearer <votre-credential>
Content-Type: application/json
X-Source: agent-builder

{
  "title": "Checkout cassé",
  "priority": "urgent",
  "body": "Trois clients ont rapporté un 500 à l'étape 4 dans la dernière heure."
}
```

**Répondez avec n'importe quel JSON — le LLM le lira :**

```json
{ "ticket_id": "TCK-42", "status": "open", "url": "https://vous.zendesk.com/agent/tickets/42" }
```

L'agent répond à l'utilisateur : *« Ticket TCK-42 ouvert (urgent). Suivi [ici](...). »*

## Écrire l'endpoint receveur (FastAPI)

```python
from fastapi import FastAPI, Header, HTTPException
from pydantic import BaseModel
from typing import Literal, Optional

app = FastAPI()

class CreateTicket(BaseModel):
    title: str
    priority: Literal["low", "medium", "high", "urgent"]
    body: Optional[str] = ""

@app.post("/tickets")
async def create_ticket(payload: CreateTicket, authorization: str = Header(...)):
    if authorization != f"Bearer {EXPECTED_TOKEN}":
        raise HTTPException(401, "unauthorized")
    ticket = await zendesk.create(**payload.model_dump())
    return { "ticket_id": ticket.id, "status": ticket.status, "url": ticket.url }
```

Deux points : (1) on valide avec le même schéma que celui fourni au LLM, ce qui attrape vite les appels mal formés ; (2) on renvoie un **JSON petit et structuré** — le LLM ingère chaque octet et vous le payez.

## Bonnes pratiques

- **Testez d'abord en curl.** Câblez le tool uniquement quand l'endpoint marche bout en bout.
- **Utilisez `enum` pour restreindre.** Le LLM respecte presque parfaitement les enums — beaucoup plus fiable qu'un indice texte du genre *« doit être... »*.
- **Réponse JSON courte et structurée.** `{"ok": true, "id": ...}` suffit. Dumper 50 Ko au LLM est lent et coûteux.
- **Clés d'idempotence.** Si l'agent peut réessayer, acceptez une clé d'idempotence dans le payload et dédupliquez côté serveur.

## Pièges

- HTTPS obligatoire — les URL `http://` sont acceptées par la modale mais bloquées par la plupart des navigateurs/proxies au runtime.
- Le bearer token vient du **credential**, pas des « Headers supplémentaires ». Mélanger est autorisé mais le credential gagne sur `Authorization`.
- Une réponse non-2xx n'est **pas** une erreur côté LLM — il reçoit l'enveloppe complète `{"status": "error", "status_code": 4xx, "body": ...}` et peut s'excuser ou réessayer. Renvoyez un message d'erreur utile.
- Si vous laissez **URL d'endpoint** vide, le tool bascule sur le comportement legacy « template-only », réservé au prototypage — les agents de production doivent toujours fixer l'endpoint.

---

*Source: https://agentbuilder.systalink.sn/docs/tool-function — human documentation.*
*Other language: [/docs-md/en/tool-function.md](/docs-md/en/tool-function.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*