Agents et personas — AiHummer Docs

une agent est l’unité qu’AiHummer met en avant dans une conversation. Chaque agent a une personnalité, son propre modèle, une invite structurée et un ensemble de compétences, et chaque modification est versionnée. Les agents sont gérés depuis l’interface d’administration web et via l’API d’administration sous /v1/admin/agents/*.

Cette page couvre de quoi un agent est composé, comment le prompt structuré « G3 » est assemblé, et comment un agent peut modifier son propre profil en toute sécurité.

Le registre des agents

Le registre est un catalogue CRUD complet des agents. Pour chaque agent, vous définissez une identité, une persona, le modèle sur lequel il fonctionne et les compétences qu’il peut utiliser. Comme le portail est multi-locataire, les agents vivent à l’intérieur d’un espace de travail et sont isolés comme toutes les autres données des locataires.

Persona — la voix et le comportement de l’agent, rendus dans une écurie, couche du prompt système adaptée au cache.
Modèle par agent — chaque agent peut épingler son propre modèle et fournisseur, donc un Un agent bon marché et un agent phare peuvent coexister dans le même espace de travail.
Compétences — les compétences par agent et partagées transforment un bloc « Compétences » en invite ; ils décrivent des capacités, pas des poids.

[!NOTE] Un modèle par agent est indépendant du routage. Routage par niveau de modèle (simple / standard / complexe) choisit une classe de modèle pour un tour, tandis que le par-agent le modèle est le défaut de l’agent lui-même. Voir Routage.

Versions, restauration et clonage

Chaque changement significatif apporté à un agent est capturé comme un version. Cela rend la configuration de l’agent vérifiable et réversible : vous pouvez examiner ce qui a changé, revenir en arrière à une version antérieure, ou clone un agent pour l’utiliser comme point de départ pour un nouveau. Les ressources de version et de profil se trouvent sous /v1/admin/agents/* (profil, sections, compétences, versions).

[!TIP] Clonez un agent fonctionnel avant une réécriture importante de persona ou de prompt. Si le nouveau si la direction ne fonctionne pas, l’original n’est toujours qu’à un retour en arrière.

L’invite structurée « G3 »

Au lieu d’une seule invite système en texte libre, AiHummer utilise un profil d’agent structuré (interne “G3”). L’identité est décomposé en champs plutôt que enterré dans la prose, et le reste de l’invite est construit à partir de noms sections plus un intégration bloc. L’orchestrateur les rend dans le prompt système en couches, en gardant les parties stables (identité, personnage, sections) dans un préfixe pouvant être mis en cache et en ajoutant les données volatiles en dernier.

La structure rend un profil facile à modifier champ par champ, facile à comparer entre les versions, et prévisible à rendre — il n’y a pas de soupe de prompts cachée.

G3 profile
├── identity fields   (decomposed: name, role, ...)
├── sections          (named, ordered prompt blocks)
└── onboarding        (first-run guidance)

Auto-édition derrière un portail d’approbation

Un agent peut être autorisé à modifier son propre profil utiliser des outils d’auto-édition — par exemple pour affiner une section ou mettre à jour son intégration. Cela est délibérément protégé :

Les auto-édition passent par le porte d’approbation: un changement proposé est enregistré et doit être approuvé par un humain avant de prendre effet. Une modification rejetée n’est jamais appliqué.
Le changement est capturé comme un nouveau version, donc une auto-édition est aussi vérifiable et réversible comme toute modification manuelle.

[!WARNING] L’auto-édition est puissante. Gardez-la derrière la porte d’approbation afin qu’un agent ne puisse pas réécrire silencieusement sa propre identité. Examiner les auto-modifications proposées de la même manière que vous examiner toute modification privilégiée.

Les mots de passe de messagerie vont dans le coffre

Si la configuration d’un agent inclut des informations d’identification de messagerie (pour le mail outil), le mot de passe est écrit dans le coffre-fort de credentials chiffrés, non stocké dans le profil ni rendu dans l’invite. Les secrets n’entrent jamais dans le contexte du modèle.

Politique d’exécution : contexte, sessions et agents enfants

Depuis la version 1.3, un agent possède une politique d’exécution — le champ runtime_policy de l’API d’administration (/v1/admin/agents à la création et à la mise à jour). C’est un objet JSON strictement validé avec "version": 1 : un {} vide rétablit les valeurs par défaut, l’omission du champ à la mise à jour conserve la politique précédente, et les champs inconnus ou les valeurs hors limites sont rejetés. La politique n’accorde aucun outil et n’élargit aucun droit — elle ne fixe que des budgets et des délais. Le clonage d’un agent et le transfert d’un tour vers lui en héritent.

context — le budget d’historique : max_tokens, reserve_tokens et history_share déterminent la part d’historique incluse dans une requête ; max_history_messages borne la fenêtre de messages, bootstrap_max_chars la taille du bloc de profil. Avec un contexte explicite, les messages anciens sont compactés en résumé par lots avant la construction de la requête courante.
- pruning — nettoyage des résultats d’outils obsolètes : par âge (ttl_seconds), en protégeant les dernières réponses (keep_last_assistants), avec une coupe douce (soft_trim_ratio, head_chars, tail_chars) et un remplacement complet par le texte placeholder au-delà de hard_clear_ratio. Le texte de l’utilisateur, les images et l’historique complet en base ne sont pas touchés.
- memory_flush — avant la compaction, un agent sans outils rédige une courte note sur les objectifs, décisions et points ouverts (soft_threshold_tokens) ; les trois dernières notes du même dialogue sont mêlées au contexte comme référence non vérifiée.
session — le cycle de vie du dialogue : idle_reset_minutes ouvre un nouveau contexte après une pause (l’historique brut est conservé), index_prune_after_days et index_max_entries retirent les vieux dialogues de la liste par défaut sans les supprimer. scope = per-peer (un dialogue par utilisateur vérifié sur tous les canaux) ou per-channel-peer (un dialogue distinct par canal).
children — agents enfants : max_depth (jusqu’à 4), max_concurrent (jusqu’à 8 par arbre d’exécution), max_per_parent (jusqu’à 5), timeout_seconds (jusqu’à 48 heures, jamais plus que le parent) et archive_after_minutes — quand les exécutions terminées quittent la liste par défaut. Ces valeurs remplacent pour cet agent les réglages globaux AIHUMMER_SUBAGENT_MAX_DEPTH et AIHUMMER_SUBAGENT_TIMEOUT_SEC.
max_iterations (1–256) — la limite de pas de la boucle d’appel de fonctions pour des scénarios validés à nombreuses délégations.
app — uniquement pour l’application AiHummer : reasoning_effort, service_tier et le mode de réponse courte direct_completion (auto ou always avec max_tokens jusqu’à 4096 et timeout_ms jusqu’à 60 000).
interaction — autorisations explicites sur les sessions : user_ids, session_agent_ids, spawn_agent_ids, la visibilité session_visibility (self, agent ou granted), session_send, les interdictions d’outils pour les appels enfants (child_tool_deny, child_leaf_tool_deny) et elevated_telegram_user_ids — un sous-ensemble de user_ids autorisé à demander une exécution code_exec explicitement élevée (les approbations ne sont pas contournées). Il n’existe ni joker ni autorisation à l’échelle du locataire.

API d’administration

Les agents et leurs profils structurés sont gérés via l’API d’administration, qui est protégée par OIDC et auditée :

Ressource	But
`/v1/admin/agents`	Lister, créer, mettre à jour, supprimer des agents (CRUD)
`/v1/admin/agents/.../profile`	Le profil structuré G3 (champs d’identité)
`/v1/admin/agents/.../sections`	Sections de commandes nommées
`/v1/admin/agents/.../skills`	Compétences par agent
`/v1/admin/agents/.../versions`	Historique des versions, restauration et clonage

Où aller ensuite

Comprendre comment les agents exécutent un tour et font apparaître des assistants dans Orchestration et sous-agents.
Voyez comment un message entrant parvient à un agent spécifique dans Routage.
Donnez à vos agents une mémoire à long terme avec Mémoire (Einstein).