> For the complete documentation index, see [llms.txt](https://guides.ia.numerique.gouv.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guides.ia.numerique.gouv.fr/albert-api/guides/function-calling.md).

# Function calling & outils

Albert API permet au modèle de chat de proposer des **appels d’outils** (`tool_calls`) décrits dans le corps de la requête. Le flux est le même que sur l’API OpenAI : le modèle émet une complétion avec des appels ; le client exécute la logique métier ; une réponse au rôle `tool` est renvoyée dans `messages` ; le modèle produit alors une réponse utilisateur finale.

## Déclarer des outils

Le champ **`tools`** est une liste d’objets. Chaque outil de type fonction comporte au minimum :

* un **nom** ;
* une **description** ;
* des **paramètres** au format JSON Schema (`parameters`) décrivant les arguments attendus.

Le détail des schémas suit la convention **Chat Completions** OpenAI. Consultez le schéma `CreateChatCompletion` dans la [page de l’endpoint Chat](https://doc.incubateur.net/alliance/albert-api/api-reference/liste-des-endpoint/chat).

## `tool_choice`

* **`none`** — pas d’appel d’outil (comportement par défaut lorsqu’aucun outil n’est fourni).
* **`auto`** — le modèle choisit entre répondre en texte ou appeler un ou plusieurs outils (défaut lorsque des outils sont présents).
* **`required`** — le modèle doit invoquer au moins un outil.
* Sélection ciblée — forcer un outil précis via un objet du type `{"type": "function", "function": {"name": "nom_fonction"}}`.

## Enchaînement typique

1. **Requête initiale** — `messages` + `tools` + `tool_choice` adéquat.
2. **Réponse assistant** — peut contenir `tool_calls` avec des `arguments` JSON à parser.
3. **Exécution** — votre code appelle bases de données, HTTP internes, etc.
4. **Message `tool`** — vous ajoutez un message avec `role: "tool"`, le `tool_call_id` correspondant et le **résultat** (souvent une chaîne JSON).
5. **Nouvelle requête** — vous renvoyez toute l’historique mis à jour pour obtenir la réponse finale de l’assistant.

## Erreurs et robustesse

* Validez et **sandboxez** les arguments produits par le modèle avant toute action sensible.
* Limitez la profondeur des enchaînements d’outils pour éviter boucles et surcoûts tokens.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://guides.ia.numerique.gouv.fr/albert-api/guides/function-calling.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
