Modèle d’intégration

Les deux façons de le brancher

La plupart des équipes optent d'abord pour la version impérative, car elle semble plus simple :

# Imperative: your code decides, always, on every turn.
context = hive.search(user_question)        # always fires, relevant or not
answer  = llm(prompt=user_question, context=context)
return answer

La version par appel d'outils confie ce jugement au modèle :

# Tool-based: the model decides whether to search, what to search for,
# and whether what came back was worth a follow-up query.
tools = [
    {
        "name": "search_team_knowledge",
        "description": (
            "Search the team's knowledge base for prior decisions, standards "
            "and meeting outcomes. Use whenever the answer might depend on "
            "something the team already decided. Prefer this over guessing."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "question": {
                    "type": "string",
                    "description": "A natural-language question, not keywords.",
                }
            },
            "required": ["question"],
        },
    },
]
# ... on a tool_use block, call aiqbee_search and return the result.

Pourquoi la seconde l'emporte

1. La qualité de la récupération dépend de la requête, et le modèle rédige de meilleures requêtes

aiqbee_search est sémantique. Avec les mots bruts de l’utilisateur, il se débrouille raisonnablement ; avec une question bien formulée, il fait considérablement mieux. Le modèle a la conversation sous les yeux — il peut transformer « avons-nous décidé de ne pas le faire ? » en « quelle a été la décision sur la limitation de débit de l’API publique ? » Votre code ne le peut pas, car il ne sait pas ce que désigne « cela ».

2. La plupart des tours ne devraient pas lancer de recherche

« Merci, ça a marché » ne nécessite aucune récupération. Une recherche systématique ajoute de la latence et injecte dans le prompt du contexte non pertinent, ce qui dégrade sensiblement les réponses. Laisser le modèle s’abstenir est une fonctionnalité, pas de la paresse.

3. Une seule recherche ne suffit souvent pas

Les vraies questions demandent une première recherche, un coup d'œil aux résultats, puis une seconde recherche plus ciblée. Cette boucle est native à l'appel d'outils et malaisée à exprimer dans un flux de contrôle figé.

4. C’est en réécrivant qu’une couche de mémoire fait ses preuves

C'est la partie que la plupart des intégrations sautent, et c'est tout l'enjeu. Donnez aussi un outil d'écriture au modèle, et les connaissances s'accumulent comme un effet secondaire du travail normal, sans qu'il faille que quelqu'un pense à les classer.

{
    "name": "record_team_knowledge",
    "description": (
        "Record a durable decision, standard or outcome so it is available "
        "to the team later. Use when something is settled that a colleague "
        "would need in six months. Do NOT use for chit-chat, transient "
        "status, or anything you were not told."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "title":   {"type": "string"},
            "content": {"type": "string",
                        "description": "Include who, what and WHY. Self-contained."},
            "type_id": {"type": "string",
                        "description": "A real id from aiqbee_get_neuron_types."},
        },
        "required": ["title", "content", "type_id"],
    },
}

Rédiger des descriptions d'outils efficaces

La description est votre véritable surface d'intégration — c'est l'invite qui détermine si l'outil est utilisé correctement. Quelques points qui comptent systématiquement :

• Dites quand l’utiliser, pas seulement ce qu’il fait. « Recherche dans la base de connaissances » produit un usage erratique. « À utiliser chaque fois que la réponse peut dépendre d’une décision antérieure de l’équipe » produit un bon usage.
• Précisez aussi quand ne pas l’utiliser. Sans exclusion explicite, les outils d’écriture sont appelés pour de simples politesses et le brain se remplit de bruit.
• Décrivez la forme d’une bonne entrée. « Une question en langage naturel, pas des mots-clés » change ce que le modèle envoie.
• Renvoyez les erreurs telles quelles. Les erreurs de Hive sont rédigées pour être exploitables — un doublon rejeté renvoie le neurone existant afin que le modèle puisse le mettre à jour ou le lier à la place. Si vous les masquez, vous perdez cette récupération.

Garde-fous à conserver dans votre code

Laisser au modèle le jugement sur le moment de l’appel n’équivaut pas à lui donner une autorité sans limites. Conservez ceci de votre côté :

• Moindre privilège. Accordez au compte de service un accès en lecture seule, sauf si l’agent a réellement besoin d’écrire. L’accès est défini par brain.
• Des identités distinctes par intégration. Un compte de service par agent, afin que l’historique d’audit et la révocation aient un sens.
• Confirmez les appels destructeurs. Il vaut mieux exclure totalement les outils de suppression du jeu d’outils, ou les soumettre à une approbation humaine.
• Activez l’audit pour tout ce qui est réglementé — chaque écriture est alors attribuable au compte de service appelant. Fonctionnalité payante ; voir Licences & offres.

Quand les appels impératifs sont adaptés

Il existe un cas légitime d'appel direct : le travail déterministe, non conversationnel. Import en masse de documents, synchronisation nocturne, script de provisionnement, migration. Aucun jugement n'est requis, il n'y a donc rien à déléguer — utilisez l'API REST ou appelez directement les outils MCP et restez simple.