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.

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 :

Garde-fou RBAC — le rôle de l'agent a-t-il la permission pour cette table/action ?
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: <seconds>, to: <role> }`.

approval:
  mode: selective
  required: [record.delete, email.send]
  timeout: 1800
  escalation:
    after: 600
    to: admin

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.

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
`knowledge`	Tables et documents à intégrer comme base de connaissances RAG de l'agent.	RAG IA
`mcp`	Liste blanche d'outils MCP externes que l'agent peut invoquer.	Intégration MCP

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. 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

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 — l'écosystème IA complet.
Fournisseurs IA — valeurs par défaut de modèle, température et jetons dont héritent les agents.
Chat IA — intégrer un agent comme panneau conversationnel.
Mémoire IA — conversation, connaissances et faits d'agent.
RAG IA — sources de connaissances que les agents intègrent.
Intégration MCP — agents comme clients MCP.
Actions IA — l'action d'automatisation ai:agent et le vocabulaire d'actions IA.
Rôles & RBAC — les permissions de rôle dont héritent les agents.

← PreviousChat IA Next →RAG IA