Agents et outils

Un agent est la configuration qu'un run exécute : instructions, modèle et outils. Les agents se gèrent par GET/POST /v1/agents et GET/PATCH/DELETE /v1/agents/{agent} (droit agents en écriture, runs ou agents en lecture), ou depuis la console « Développeurs » : le même service écrit les deux, avec les mêmes refus.

Champs

Pour exposer l'agent dans une bulle de chat sur votre site, voir Widget.

Une clé de champ inconnue est refusée (unknown_parameter), tout comme une valeur de mauvaise forme (invalid_parameter, errors par champ).

{
  "data": {
    "id": "agt_01k6examplea0000000000000",
    "name": "Assistant support",
    "instructions": "Tu réponds à partir des tickets fournis.",
    "model": null,
    "temperature": 0.3,
    "tools": ["web_search", "create_chart"],
    "active": true,
    "output_schema": null,
    "client_tools": [],
    "unavailable_tools": [],
    "created_at": "2026-09-21T10:00:00+00:00",
    "updated_at": "2026-09-21T10:00:00+00:00"
  }
}

Documents de connaissance

Un agent peut porter des documents permanents (catalogue, FAQ, procédures) lus par chaque run de l'agent, widget compris, avec les outils de lecture de fichiers existants. Il n'y a pas de recherche sémantique : l'agent lit le document quand il en a besoin.

• POST /v1/agents/{agent}/documents (multipart, un champ file, mêmes types et taille que Fichiers), GET /v1/agents/{agent}/documents et DELETE /v1/agents/{agent}/documents/{file}. La console les envoie aussi depuis le tiroir de l'agent.
• 20 documents au plus par agent (422 too_many_documents). Pas d'expiration (expires_at: null). Ils comptent dans le quota de fichiers et de stockage (400 storage_quota_exceeded).
• Un document ne se supprime que par la route ci-dessus : DELETE /v1/files/{file} répond 409 file_in_use. Supprimer l'agent supprime ses documents.

GET /v1/tools : le catalogue

Cette route liste tout ce que votre organisation peut mettre sur un agent, et pourquoi le reste est refusé : une liste blanche, jamais « tout sauf quelques exceptions » :

{
  "data": [
    { "key": "web_search", "label": "Web search", "description": "Searches the web and returns results with their URLs.", "kind": "native", "forced": true, "available": true, "reason": null, "server": null, "writes_data": false },
    { "key": "create_chart", "label": "Chart", "description": "Creates a bar, line, pie or area chart, returned as structured data.", "kind": "native", "forced": false, "available": true, "reason": null, "server": null, "writes_data": false },
    { "key": "list_data_bases", "label": "List data bases", "description": "Lists the data bases of the organization and their tables.", "kind": "data", "forced": false, "available": false, "reason": { "code": "plan_feature_missing", "message": "Your plan does not include structured data." }, "server": null, "writes_data": false },
    { "key": "mcp_3_send_email", "label": "CRM Acme — send_email", "description": "Sends an email through the connected CRM.", "kind": "mcp", "forced": false, "available": true, "reason": null, "server": { "id": 3, "name": "CRM Acme" }, "writes_data": true },
    { "key": "mcp_5_list_orders", "label": "Boutique — list_orders", "description": "Lists orders.", "kind": "mcp", "forced": false, "available": false, "reason": { "code": "mcp_oauth_credentials", "message": "This connector signs each member in with OAuth; an API run has no member." }, "server": { "id": 5, "name": "Boutique" }, "writes_data": false }
  ]
}

• kind vaut native (outils intégrés), data (lecture des données structurées, offert si votre formule inclut la fonctionnalité Données) ou mcp (un outil d'un de vos serveurs MCP).
• forced : web_search, web_fetch et calculate sont portés par tout agent, que vous les listiez ou non dans tools ; les quatre outils de fichiers (inspect_file, read_uploaded_file, search_text, list_uploaded_files) sont eux aussi automatiques, mais seulement sur un run qui a des fichiers en entrée, voir Fichiers.
• available à false explique pourquoi (reason.code, reason.message) : formule sans la fonctionnalité (plan_feature_missing), connecteur MCP à jeton par membre ou OAuth (mcp_per_user_credentials, mcp_oauth_credentials : une API n'a pas de membre derrière elle), connecteur inactif (mcp_server_inactive), outil désactivé (mcp_tool_disabled) ou à revoir (mcp_tool_needs_review) dans vos réglages MCP.
• writes_data à true signale un outil de connecteur qui modifie des données dans votre logiciel (création, mise à jour, suppression, envoi…). Dans le chat, une telle action attend l'approbation d'une personne ; dans un run API, personne n'est là pour approuver : l'outil s'exécute directement dès que le modèle l'appelle. C'est vous qui décidez, agent par agent, en l'ajoutant ou non à tools. Voir « Outils d'écriture » ci-dessous.

Outils indisponibles au moment d'enregistrer

Ajouter à tools un outil qui n'existe pas (unknown_tool) ou qui est indisponible maintenant (tool_unavailable, avec la raison) est refusé à l'écriture. En revanche, un outil déjà présent sur l'agent et devenu indisponible depuis (formule changée, connecteur désactivé…) n'est jamais retiré de force : il reste dans tools, apparaît dans unavailable_tools de la réponse, et chaque run de cet agent continue sans lui, signalé par un avertissement plutôt qu'un échec :

{
  "warnings": [
    { "code": "tool_unavailable", "tool": "list_data_bases", "reason": { "code": "plan_feature_missing", "message": "Your plan does not include structured data." } }
  ]
}

Outils d'écriture

Un outil de connecteur avec writes_data: true n'est jamais porté par un agent sans que vous l'ayez listé dans tools : ce choix est votre consentement. Chaque appel est tracé dans steps du run (outil, statut, durée).

Avant d'en confier un à un agent :

• Ne donnez que les écritures nécessaires à l'usage de cet agent ; gardez des agents distincts pour la lecture et pour l'écriture.
• Validez côté serveur MCP : votre serveur reste l'autorité, il doit refuser toute action hors des droits du jeton qu'il a délivré à leem.
• Rendez vos écritures idempotentes (une référence métier dans les arguments) : un modèle peut réessayer un appel.
• Méfiez-vous du contenu tiers : web_search, web_fetch et les résultats de vos propres outils peuvent contenir du texte rédigé par un tiers. leem le marque comme non fiable pour le modèle, mais un agent qui écrit doit recevoir des instructions explicites sur ce qu'il a le droit de faire.

Instructions : agent puis appel

Les instructions de l'agent s'appliquent à chaque run. Si l'appel POST /v1/runs fournit lui aussi des instructions, elles sont ajoutées après celles de l'agent, jamais un remplacement, ce qui permet de garder une configuration stable sur l'agent et d'affiner ponctuellement par appel.