goblin-agents
Advanced tools
Le module goblin-agents fournit une infrastructure complète pour intégrer des agents d'intelligence artificielle (IA) dans l'écosystème Xcraft. Il permet de créer, configurer et interagir avec différents modèles de langage (LLM) via des fournisseurs comme Ollama et OpenAI. Ce module est conçu pour faciliter l'utilisation d'agents IA dans diverses applications, en offrant des fonctionnalités avancées comme la gestion de conversations, l'analyse de documents PDF, et l'utilisation d'outils externes.
Le module est organisé autour du pattern Elf, avec une séparation claire entre la logique métier (AiAgentLogic) et l'interface de l'acteur (AiAgent).
Le module goblin-agents permet de créer et gérer des agents IA qui peuvent interagir avec les utilisateurs via des conversations textuelles. Chaque agent est configuré avec un modèle spécifique, un fournisseur (Ollama ou OpenAI), et des paramètres qui définissent son comportement.
Les agents peuvent maintenir plusieurs contextes de conversation simultanément, ce qui permet d'avoir des conversations distinctes avec différents utilisateurs ou sur différents sujets. Chaque contexte conserve son propre historique de messages, ce qui permet à l'agent de maintenir la cohérence dans ses réponses.
Le module prend en charge diverses fonctionnalités avancées :
Les agents peuvent être configurés avec une grande variété d'options qui influencent leur comportement, comme la température (créativité), la taille du contexte, et diverses pénalités pour éviter les répétitions.
const {AiAgent} = require('goblin-agents/lib/llm/aiAgent.js');
// Dans une méthode d'un acteur Elf
async initAgents() {
const feedId = await this.newQuestFeed();
// Création d'un agent avec Ollama (local)
const ollamaAgentId = 'aiAgent@ollama-mistral-assistant';
const agent = await new AiAgent(this).create(ollamaAgentId, feedId, {
name: 'Assistant Personnel',
role: 'assistant',
prompt: 'Tu es un assistant personnel serviable et précis.',
provider: 'ollama',
model: 'mistral-small',
host: 'http://127.0.0.1:11434',
options: {
temperature: 0.7
},
usability: 'stable'
});
// Création d'un agent avec OpenAI (cloud)
const openAiAgentId = 'aiAgent@gpt-4o-assistant';
const cloudAgent = await new AiAgent(this).create(openAiAgentId, feedId, {
name: 'Assistant Personnel',
role: 'assistant',
provider: 'open-ai',
model: 'openai/gpt-4o',
host: 'https://openrouter.ai/api/v1',
headers: {
Authorization: `Bearer <votre-clef-api>`,
},
usability: 'stable'
});
}
// Dans une méthode d'un acteur Elf
async askAgent(desktopId, agentId, contextId, question, saveExchange = false) {
const feedId = await this.newQuestFeed();
// Instancie l'agent approprié par ex. 'aiAgent@gpt-4o-assistant'
const agent = await new AiAgent(this).create(agentId, feedId);
// Continue la conversation sur ce contexte par ex. 'story-xyz' et
// obtient une réponse à la question de l'utilisateur
const response = await agent.chat(contextId, question, desktopId);
if(saveExchange) {
//Persiste l'échange contextuel nouvelle paire (question->réponse) sur le disque
await agent.save();
}
return response;
}
// Dans une méthode d'un acteur Elf
async addWeatherToolSupportToAgent(agentId) {
const feedId = await this.newQuestFeed();
// Instancie l'agent approprié par ex. 'aiAgent@gpt-4o-assistant'
const agent = await new AiAgent(this).create(agentId, feedId);
// Configurer un agent avec des outils
// Provoquera des envois de commandes sur le bus à l'acteur "weather"
// en appelant la quête "getWeather(city)"
await agent.patch({
toolServiceId: 'weather', //acteur (ici le singleton weather) qui expose des quêtes "outils"
tools: [
{
type: 'function',
function: {
name: 'getWeather', //nom de la quête de l'acteur qui récupère la météo
description: 'Obtenir la météo pour une ville',
parameters: {
type: 'object',
properties: {
city: {
type: 'string',
description: 'Nom de la ville'
}
},
required: ['city']
}
}
}
]
});
// L'agent pourra maintenant utiliser l'outil weather.getWeather
const question = "Quel temps fait-il à Paris aujourd'hui?";
const response = await agent.chat(contextId, question, desktopId);
}
// Dans une méthode d'un acteur Elf
async updateKnowledgeBase(articles) {
const feedId = await this.newQuestFeed();
// Instancie l'agent approprié pour faire un embedding
// par ex. 'aiAgent@default-embedder'
const agent = await new AiAgent(this).create(agentId, feedId);
// Récupère les textes à indexer
const texts = Object.values(articles);
// Prépare un boucle d'insertion par id d'article
const articlesIds = Object.keys(articles);
// Générer des embeddings pour plusieurs textes en une seule requête
const vectorsBatch = await agent.embedInBatch(texts);
// Upsert les articles dans un archetype IndexedContent
for(const articleId of articleIds) {
// Récupère les vecteurs correspondant au texte dans le lot
// et le texte original
const index = articleIds.indexOf(articleId);
const vectors = vectorsBatch[index];
const text = texts[index];
const indexedContent = new IndexedContentState({
id: articleId,
text, //texte original de l'article
meta: {
locale: 'fr', //définit la locale
scope: 'knowledge-base', //définit le scope
vectors, //vecteur correspondants au texte
status: 'published',
}
});
// Effectue l'upsert de l'archetype
await new IndexedContent(this).insertOrReplace(
articleId,
feedId,
indexedContent
);
}
}
Le module goblin-agents interagit avec plusieurs autres composants de l'écosystème Xcraft :
Le module peut également interagir avec d'autres services Goblin via le système d'appels d'outils, permettant aux agents d'effectuer des actions concrètes dans l'application.
| Option | Description | Type | Valeur par défaut |
|---|---|---|---|
| version | Version des agents | Number | 2 |
| defaultProfile | Profil par défaut des agents | String | null |
| defaultSettings | Paramètres par défaut | Object | null |
| profiles | Profils pour remplacer les paramètres | Object | {} |
| settings | Paramètres par nom | Object | {} |
aiAgent.jsCe fichier est le point d'entrée du module, exportant les commandes Xcraft pour l'acteur AiAgent. Il importe l'acteur et sa logique depuis le fichier principal et les expose au système Xcraft via Elf.birth().
lib/llm/aiAgent.jsCe fichier contient la définition complète de l'acteur AiAgent, avec :
L'état d'un agent IA est défini par la classe AiAgentShape qui contient les propriétés suivantes :
id : Identifiant unique de l'agentversion : Version de l'agentname : Nom de l'agentrole : Rôle de l'agent (assistant, etc.)prompt : Prompt par défaut utilisé pour définir le comportement de l'agentprovider : Fournisseur LLM ('ollama' ou 'open-ai')model : Modèle de langage utiliséhost : URL du serveur LLMheaders : En-têtes HTTP pour les requêtes APImessages : Historique des messages par contexteoptions : Options de configuration du modèle (voir OptionsShape)format : Format de sortie attendutools : Outils externes disponibles pour l'agenttoolServiceId : Identifiant du service d'outilsusability : État d'utilisabilité ('disabled', 'experimental', 'stable', 'deprecated')meta : Métadonnées de l'agentLa classe OptionsShape définit de nombreuses options de configuration pour les modèles LLM, incluant des paramètres comme la température, la taille du contexte, les pénalités de répétition, et les options d'optimisation mémoire.
L'acteur AiAgent suit le cycle de vie standard des acteurs Elf Archetype :
create() qui initialise l'agent avec un ID et un étatpatch() pour modifier les paramètres ou upgrade() pour les mises à jour de versionsave() pour sauvegarder l'étattrash() pour marquer comme supprimé ou delete() pour suppression définitivecreate(id, desktopId, agentState) — Crée un nouvel agent avec l'ID et l'état spécifiés. Persiste automatiquement l'agent après création.patch(agentState) — Met à jour l'état de l'agent avec les propriétés fournies et persiste les changements.upgrade(version, agentState) — Met à niveau l'agent vers une nouvelle version avec l'état spécifié, uniquement si la version est supérieure à la version actuelle.gen(prompt) — Génère du texte à partir d'un prompt en utilisant le modèle configuré de l'agent.reset(contextId, save=false) — Réinitialise l'historique des messages pour un contexte spécifique. Si aucun contextId n'est fourni, réinitialise tous les contextes.readPDFpages(pdfPath) — Extrait le texte des pages d'un document PDF en utilisant l'OCR via un modèle multimodal.embed(rawText) — Génère un embedding vectoriel pour un texte donné, retourné sous forme de littéral SQL hexadécimal.embedInBatch(rawTexts=[]) — Génère des embeddings vectoriels pour plusieurs textes en une seule requête, optimisé pour les traitements par lots avec gestion des verrous.set(contextId, messages) — Définit directement l'historique des messages pour un contexte spécifique.chat(contextId, question, userDesktopId, sessionId=null) — Engage une conversation avec l'agent dans un contexte spécifique. Gère automatiquement l'historique et les appels d'outils.ask(contextId, question, questionId) — Pose une question à l'agent avec streaming de la réponse (uniquement pour Ollama). Émet des événements pour chaque partie de la réponse.resumeExchange(resumePrompt, contextId) — Reprend un échange existant avec un nouveau prompt système, en utilisant l'historique du contexte comme base.react(reactPrompt, contextId, question) — Utilise le paradigme ReAct (Reasoning and Acting) pour permettre à l'agent de raisonner et d'agir de manière autonome.callAgent(contextId, agentId, action, feedId) — Appelle un autre agent pour effectuer une action spécifique dans le cadre d'une orchestration multi-agents.addAssistantMessage(contextId, message) — Ajoute un message de l'assistant à l'historique d'un contexte spécifique.change(path, newValue) — Modifie une propriété spécifique de l'état de l'agent avec gestion automatique des types pour certains paramètres.getUserChatContextHistory(contextId, filterTool=true) — Récupère l'historique des messages pour un contexte spécifique avec option de filtrage des messages d'outils.getBaseSettings() — Retourne les paramètres de base de l'agent (provider, host, headers, model).getUsability() — Retourne l'état d'utilisabilité de l'agent.trash() — Marque l'agent comme supprimé en changeant son statut meta à 'trashed'.save() — Persiste l'état actuel de l'agent sur le disque.lib/llm/providers.jsCe fichier définit l'architecture des fournisseurs de LLM avec une classe abstraite LLMProvider et ses implémentations concrètes :
Définit l'interface commune que tous les fournisseurs doivent implémenter :
chat() : Conversation avec le modèlegen() : Génération de texteembed() : Génération d'embeddingsembedInBatch() : Génération d'embeddings par lotsImplémentation pour le fournisseur Ollama (serveur local) :
ollama pour communiquer avec le serveurImplémentation pour OpenAI et services compatibles (OpenRouter, etc.) :
RestAPI de xcraft-core-utils pour les appels HTTPlib/llm/utils.jsCe fichier contient un ensemble complet d'utilitaires pour le traitement de texte et de documents :
getPDFImages(pdfPath) — Convertit les pages d'un PDF en images base64 pour l'OCR avec des options optimisées pour la qualité du texte.OCR_SYSTEM_PROMPT — Prompt système spécialisé pour guider les modèles multimodaux dans l'extraction de texte à partir d'images.cleanHtmlContent(html) — Nettoie le contenu HTML en supprimant les balises et en normalisant les espaces.simplifyHtml(html) — Simplifie le HTML en gardant uniquement les éléments sûrs via sanitize-html.extractTitlesAndContent(html) — Extrait intelligemment les titres et le contenu d'un document HTML en préservant la structure.html2chunks(html, chunkSize=300, chunkOverlap=0) — Découpe un document HTML en chunks en utilisant RecursiveCharacterTextSplitter de LangChain.estimateTokenCount(text) — Estime le nombre de tokens d'un texte (approximation basée sur les mots × 1.33).splitLongText(text, maxLength, baseId) — Découpe un texte long en segments de taille maximale en préservant les mots entiers.sliceText(text, chunkSize) — Découpe un texte en chunks en respectant les limites de phrases.groupSentences(text, maxSize) — Groupe les phrases en chunks de taille optimale pour les modèles de langage.chunkArray(array, size) — Divise un tableau en sous-tableaux de taille spécifiée pour le traitement par lots.embedChunksInBatch(agent, allChunks, batchSize=50) — Traite les embeddings par lots en associant chaque embedding à son contenu d'origine.buildPromptFromArticlesMulti(initialQuestion, questionsWithArticles, maxTotalTokens) — Construit des prompts optimisés à partir de multiples articles en respectant les limites de tokens.vectorToSqlLiteral(vec) — Convertit un vecteur Float32Array en littéral SQL hexadécimal pour le stockage en base de données.Ces utilitaires sont essentiels pour préparer les données avant de les envoyer aux modèles de langage et pour traiter les résultats. Ils permettent notamment de gérer les contraintes de taille de contexte des modèles en découpant intelligemment les textes longs tout en préservant la cohérence sémantique.
Cette documentation a été mise à jour automatiquement.
FAQs
AI Agents framework
The npm package goblin-agents receives a total of 15 weekly downloads. As such, goblin-agents popularity was classified as not popular.
We found that goblin-agents demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.
Security News
AGENTS.md is a fast-growing open format giving AI coding agents a shared, predictable way to understand project setup, style, and workflows.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.