Présentation des agents

Un agent est un acteur IA autonome qui opère comme un utilisateur virtuel à l'intérieur de votre application. Il se lie à un rôle auth, travaille depuis 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 de ressources. Les agents vivent dans le tableau de premier niveau app.agents[].

Ils exigent deux choses présentes : app.auth (les agents sont stockés comme utilisateurs auth) et AI_PROVIDER (il leur faut un modèle).

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 une ligne auth.user avec type: 'agent' et une adresse synthétique ({name}@agents.sovrium.local). Ce n'est pas de la comptabilité — c'est toute la conception de sécurité.

• L'agent hérite de chaque permission de table et de champ de son rôle, exactement comme un humain. Il n'y a pas de système de permissions IA distinct à tenir synchronisé, ni de moyen pour un agent d'excéder un rôle que vous avez déjà raisonné.
• Les agents ne peuvent pas s'authentifier. Aucun point d'accès de connexion ne les accepte : ni e-mail et mot de passe, ni lien magique, ni OTP. L'identité existe pour être autorisée, jamais pour se connecter.
• Les actions d'agent apparaissent dans le journal d'activité avec actor.type = 'agent' : un audit se lit donc uniformément entre humains et machines.
• Les utilisateurs agents sont exclus de la liste des utilisateurs sauf si vous passez ?includeAgents=true.

Les enregistrements sont gérés pour vous : créés au premier démarrage, mis à jour au changement de rôle, supprimés en douceur quand l'agent quitte la configuration.

Propriétés de définition

Les champs d'identité se placent au premier niveau de chaque entrée.

systemPrompt et instructions se partagent nettement le travail en pratique : le prompt dit qui est l'agent, et chaque instruction est une règle que vous auriez sinon noyée dans un paragraphe. Des règles énoncées en lignes numérotées distinctes sont mieux suivies, et se relisent mieux en diff.

Outils et sécurité à double garde-fou

Déplacé vers Outils — la liste blanche tools, les actions disponibles, et les deux garde-fous que traverse chaque appel.

Permissions : qui peut invoquer l'agent

Déplacé vers Permissions et approbation — le bloc permissions et sa règle trigger.

Approbation humaine dans la boucle

Déplacé vers Permissions et approbation — modes d'approbation, délais et escalade.

Exécution planifiée

Déplacé vers Planification et limites — expressions cron, fuseaux horaires et prompts de tâche.

Limites opérationnelles

Déplacé vers Planification et limites — plafonds d'actions, de jetons et de concurrence.

Mémoire, connaissances et MCP

Trois blocs supplémentaires se composent sur un agent :

Multi-agent & invocation

Un agent est atteignable depuis le composant de chat IA, par l'API sur POST /api/agents/{name}/chat, par sa propre planification, et depuis une automatisation via l'action ai:agent.

Parce que chaque agent est un utilisateur virtuel distinct avec son rôle et sa liste blanche, plusieurs peuvent coexister à des niveaux de privilège différents — un analyste en lecture seule à côté d'un agent de tri capable d'écrire — sans que l'un hérite de la portée de l'autre.

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.

Lisez-le comme un énoncé de sécurité plutôt que comme une liste de fonctionnalités : cet agent peut lire deux tables et rien d'autre, n'écrit rien, n'a besoin d'aucune approbation parce qu'il ne peut nuire, et se réveille une fois par jour.

Pages associées

• Outils — la liste blanche de capacités et son double garde-fou.
• Permissions et approbation — qui invoque, et ce qui attend.
• Planification et limites — cron et plafonds de ressources.
• Fournisseurs d'IA — les valeurs de modèle dont héritent les agents.
• Chat IA — intégrer un agent comme panneau conversationnel.
• Rôles et RBAC — les permissions dont hérite un agent.