# Agents IA Un agent est un acteur IA autonome qui opère **comme un utilisateur virtuel** à l'intérieur de votre application. Chaque agent se lie à un rôle auth, est restreint à une liste blanche explicite de tables et d'actions, et peut être encadré par une approbation humaine, s'exécuter selon une planification et être borné par des limites opérationnelles. Les agents sont déclarés dans le tableau de premier niveau `app.agents[]`. Les agents nécessitent que `app.auth` soit configuré (ils sont stockés comme utilisateurs auth) et que `AI_PROVIDER` soit défini. ```yaml agents: - name: support-agent role: support systemPrompt: You are a courteous support assistant. Resolve tickets accurately. tools: tables: [tickets, customers] actions: [record.read, record.update, email.send] approval: mode: selective required: [email.send] limits: maxActionsPerMinute: 20 maxTokensPerDay: 100000 ``` ## Modèle agent-en-tant-qu'utilisateur Chaque agent est matérialisé à l'exécution comme un enregistrement `auth.user` avec `type: 'agent'` et un e-mail synthétique (`{name}@agents.sovrium.local`). C'est le fondement de la sécurité des agents : - L'agent **hérite de chaque permission de table et de champ de son rôle assigné**, exactement comme un utilisateur humain. - Les agents **ne peuvent pas s'authentifier** via un quelconque point d'accès de connexion (e-mail/mot de passe, lien magique, OTP). - Les actions d'agent apparaissent dans le journal d'activité avec `actor.type = 'agent'`. - Les utilisateurs agents sont exclus de la liste des utilisateurs par défaut, et inclus uniquement lorsque `?includeAgents=true` est passé. Les enregistrements d'utilisateurs agents sont gérés automatiquement : créés au premier démarrage, mis à jour lorsque le rôle change, et supprimés en douceur lorsque l'agent est retiré de la configuration. ## Propriétés de définition Les champs d'identité principaux sont intégrés au niveau supérieur de chaque entrée d'agent. | Propriété | Description | | -------------- | -------------------------------------------------------------------------------------------------------- | | `name` | Identifiant unique en kebab-case (ex. `support-agent`). Lettres minuscules, chiffres, tirets simples. | | `role` | Rôle auth sous lequel l'agent opère. Doit référencer un rôle dans `auth.roles`. | | `systemPrompt` | Invite système définissant la personnalité, le rôle et les règles de l'agent. | | `instructions` | Tableau optionnel d'instructions comportementales, ajoutées comme règles numérotées à l'invite système. | | `model` | Remplacement du modèle LLM (par défaut `AI_MODEL`). | | `temperature` | Remplacement de la température, `0`–`1` inclus (par défaut `AI_TEMPERATURE`). | | `maxTokens` | Remplacement du nombre maximal de jetons de sortie (par défaut `AI_MAX_TOKENS`). | | `enabled` | Si l'agent peut s'exécuter. Par défaut `true`. Les agents désactivés ignorent les exécutions planifiées. | ## Outils & sécurité à double garde-fou Le bloc `tools` est la liste blanche de capacités de l'agent. Sovrium applique un modèle de sécurité à **double garde-fou** — les deux garde-fous doivent passer : 1. **Garde-fou RBAC** — le rôle de l'agent a-t-il la permission pour cette table/action ? 2. **Garde-fou liste blanche** — cette table/action est-elle listée dans les `tools` de l'agent ? Un agent sans `tools` n'a **aucun accès** (sécurisé par défaut). | Propriété | Description | | --------------- | ----------------------------------------------------------------------------------------- | | `tools.tables` | Noms de tables auxquels l'agent peut accéder (au moins une ; doit exister dans `tables`). | | `tools.actions` | Types d'actions que l'agent peut effectuer (au moins une ; voir ci-dessous). | ### Actions disponibles Les actions suivent le motif `type.operator` utilisé par le moteur d'automatisation. | Catégorie | Actions | | ---------- | ----------------------------------------------------------------------------------------------- | | **Record** | `record.read`, `record.create`, `record.update`, `record.delete` | | **State** | `state.get`, `state.set`, `state.increment`, `state.delete`, `state.list` (KV inter-exécutions) | | **HTTP** | `http.request` | | **AI** | `ai.generate`, `ai.classify`, `ai.extract` (chaîner des sous-tâches LLM) | | **Code** | `code.runTypescript` (en bac à sable) | | **Email** | `email.send` | | **Auth** | `auth.createUser`, `auth.assignRole`, `auth.banUser`, `auth.unbanUser` | | **File** | `file.upload`, `file.download`, `file.delete`, `file.list`, `file.getMetadata` | ## Permissions : qui peut invoquer l'agent Le bloc optionnel `permissions` décrit l'intégration RBAC de l'agent et qui peut le déclencher. | Propriété | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------- | | `permissions.type` | Discriminateur de type d'utilisateur — toujours `agent`. | | `permissions.trigger` | Qui peut invoquer cet agent : `all`, `authenticated`, ou un tableau de rôles comme `[admin, member]`. | | `permissions.emailDomain` | Domaine pour l'e-mail synthétique de l'agent (par défaut `agents.sovrium.local`). | ## Approbation humaine dans la boucle Le bloc `approval` encadre les actions de l'agent derrière une revue humaine. | Propriété | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------ | | `approval.mode` | `none` (exécuter immédiatement), `all` (chaque action nécessite une approbation), ou `selective`. | | `approval.required` | Actions nécessitant une approbation (un sous-ensemble de `tools.actions`). Requis lorsque `mode: selective`. | | `approval.timeout` | Secondes avant qu'une approbation en attente n'expire (par défaut `3600`). | | `approval.escalation` | Escalade lorsqu'une approbation reste en attente — `{ after: , to: }`. | ```yaml approval: mode: selective required: [record.delete, email.send] timeout: 1800 escalation: after: 600 to: admin ``` :::callout **L'`after` d'escalade doit être inférieur au `timeout`.** Une approbation qui n'est pas traitée dans les `after` secondes escalade vers le rôle `to` ; si toujours non traitée au `timeout`, elle expire. ::: ## Exécution planifiée Le bloc `schedule` fait s'exécuter un agent automatiquement à un intervalle cron. Le `taskPrompt` est envoyé au LLM comme message utilisateur à chaque exécution. | Propriété | Description | | --------------------- | ------------------------------------------------------------------------ | | `schedule.cron` | Expression cron standard à 5 champs (ex. `*/15 * * * *`, `0 9 * * MON`). | | `schedule.timezone` | Identifiant de fuseau horaire IANA (par défaut `UTC`). | | `schedule.taskPrompt` | Invite envoyée au LLM à chaque exécution planifiée. | ```yaml schedule: cron: '0 9 * * MON' timezone: Europe/Paris taskPrompt: Summarize last week's new tickets and post the digest. ``` Les exécutions planifiées respectent `enabled` (les agents désactivés les ignorent) et `approval` (ex. `mode: all` met en pause l'exécution planifiée pour validation humaine). ## Limites opérationnelles Le bloc `limits` plafonne la consommation de ressources pour empêcher les agents emballés. Tous les champs sont optionnels et reviennent aux valeurs par défaut du système. | Propriété | Défaut | Description | | ---------------------------- | -------- | ----------------------------------------------------------------- | | `limits.maxActionsPerMinute` | `30` | Nombre maximal d'actions BD/e-mail par minute. | | `limits.maxTokensPerDay` | `200000` | Nombre maximal de jetons LLM par 24 h. Réinitialisé à minuit UTC. | | `limits.maxConcurrentTasks` | `5` | Nombre maximal d'exécutions de tâches simultanées. | ## Mémoire, connaissances et MCP Les agents se composent avec trois capacités supplémentaires, chacune documentée dans sa propre page : | Bloc | Objectif | Documentation | | ----------- | ------------------------------------------------------------------------------------------- | ------------------------------------------- | | `memory` | Historique de conversation, récupération de connaissances RAG, et faits appris persistants. | [Mémoire IA](/fr/docs/ai-memory) | | `knowledge` | Tables et documents à intégrer comme base de connaissances RAG de l'agent. | [RAG IA](/fr/docs/ai-rag) | | `mcp` | Liste blanche d'outils MCP externes que l'agent peut invoquer. | [Intégration MCP](/fr/docs/mcp-integration) | ## Multi-agent & invocation Les agents peuvent être invoqués depuis l'interface de chat IA (un composant `ai-chat` nommé), via l'API, selon une planification, et depuis les automatisations via l'[action `ai:agent`](/fr/docs/automation-ai-actions). Parce que chaque agent est un utilisateur virtuel distinct avec son propre rôle et sa propre liste blanche d'outils, plusieurs agents peuvent coexister avec des frontières de privilèges différentes — un agent analyste en lecture seule et un agent de triage capable d'écrire, par exemple. ## Exemple complet ```yaml agents: - name: data-analyst role: analyst systemPrompt: You are an expert data analyst. Be precise and cite the records you used. instructions: - Never expose customer PII in summaries. - Prefer aggregates over row-level dumps. tools: tables: [orders, customers] actions: [record.read] approval: mode: none limits: maxActionsPerMinute: 20 maxTokensPerDay: 150000 schedule: cron: '0 7 * * *' timezone: UTC taskPrompt: Produce the daily orders summary. ``` ## Pages connexes - [Vue d'ensemble de l'IA](/fr/docs/ai-overview) — l'écosystème IA complet. - [Fournisseurs IA](/fr/docs/ai-providers) — valeurs par défaut de modèle, température et jetons dont héritent les agents. - [Chat IA](/fr/docs/ai-chat) — intégrer un agent comme panneau conversationnel. - [Mémoire IA](/fr/docs/ai-memory) — conversation, connaissances et faits d'agent. - [RAG IA](/fr/docs/ai-rag) — sources de connaissances que les agents intègrent. - [Intégration MCP](/fr/docs/mcp-integration) — agents comme clients MCP. - [Actions IA](/fr/docs/automation-ai-actions) — l'action d'automatisation `ai:agent` et le vocabulaire d'actions IA. - [Rôles & RBAC](/fr/docs/auth-roles-rbac) — les permissions de rôle dont héritent les agents.