agentic-api 1.0.1

package/dist/src/utils.js

@@ -0,0 +1,288 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.slug = exports.openaiInstance = void 0;
+exports.injectTransferTools = injectTransferTools;
+exports.handleTransferCall = handleTransferCall;
+exports.callForSystemReview = callForSystemReview;
+const prompts_1 = require("./prompts");
+const system_1 = require("./agents/system");
+const princing_openai_1 = require("./princing.openai");
+let _openaiInstance;
+const openaiInstance = function (openai) {
+    if (openai) {
+        _openaiInstance = openai;
+    }
+    if (!_openaiInstance) {
+        throw new Error('OpenAI instance has not been initialized');
+    }
+    return _openaiInstance;
+};
+exports.openaiInstance = openaiInstance;
+const slug = (text) => {
+    return text.toLowerCase().replace(/ /g, '-').replace(/[^a-z0-9àâçéèêëîïôûù-]+/g, '').replace(/-{2,}/g, '-');
+};
+exports.slug = slug;
+/**
+ * This defines and adds "transferAgents" tool dynamically based on the specified downstreamAgents on each agent.
+ */
+function injectTransferTools(agentDefs) {
+    // Iterate over each agent definition
+    agentDefs.forEach((agentDef) => {
+        if (agentDef.ready) {
+            return;
+        }
+        const downstreamAgents = agentDef.downstreamAgents || [];
+        //
+        // Add the think tool if maxSteps is set
+        // https://www.aihero.dev/implementing-anthropics-think-tool-in-typescript
+        if (agentDef.maxSteps && agentDef.maxSteps > 0) {
+            const description = `
+Use the tool as a helper to think about something with a plan of multiple steps.
+It will not obtain new information or change the database, but just append the thought to the log.
+Use it when complex reasoning or some cache memory is needed.
+To avoid infinite thinking, the tool is limited to ${agentDef.maxSteps} calls.
+
+It takes two arguments:
+- thought (str): A thought to think about.
+- step (int): The incremented step number that constrains the global thinking with a limitation of ${agentDef.maxSteps} calls.
+`;
+            const think = {
+                type: "function",
+                function: {
+                    name: "thinking",
+                    description,
+                    strict: true,
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            justification: {
+                                type: "string",
+                                description: "The reasoning why this thinking is needed.",
+                            },
+                            thought: {
+                                type: "string",
+                                description: "A thought to think about.",
+                            },
+                            step: {
+                                type: "number",
+                                description: "The incremented step number that constrains the global thinking.",
+                            },
+                        },
+                        required: ["justification", "thought", "step"],
+                        additionalProperties: false,
+                    },
+                }
+            };
+            // Ensure the agent has a tools array
+            if (!agentDef.tools) {
+                agentDef.tools = [];
+            }
+            console.log('--- DBG addTools', agentDef.name, 'with think step', agentDef.maxSteps);
+            // Add the newly created tool to the current agent's tools
+            agentDef.tools.push(think);
+        }
+        // Only proceed if there are downstream agents
+        if (downstreamAgents.length > 0) {
+            // Build a list of downstream agents and their descriptions for the prompt
+            const availableAgentsList = downstreamAgents
+                .map((dAgent) => `- ${dAgent.name}: ${dAgent.publicDescription ?? "No description"} ${dAgent.human ? '(human agent, less specialized)' : ''}`)
+                .join("\n");
+            // Create the transfer_agent tool specific to this agent
+            const transferAgentTool = {
+                type: "function",
+                function: {
+                    name: "transferAgents",
+                    description: `${prompts_1.transferAgentPrompt.replace('__AGENT_NAME__', agentDef.name)}
+${availableAgentsList}
+          `,
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            rationale_for_transfer: {
+                                type: "string",
+                                description: "The reasoning why this transfer is needed.",
+                            },
+                            conversation_context: {
+                                type: "string",
+                                description: "Relevant context from the conversation that will help the recipient perform the correct action.",
+                            },
+                            destination_agent: {
+                                type: "string",
+                                description: "The more specialized destination_agent that should handle the user’s intended request.",
+                                enum: downstreamAgents.map((dAgent) => dAgent.name),
+                            },
+                            confidence: {
+                                type: "number",
+                                description: "The confidence that the transfer to a more appropriate agent is needed."
+                            },
+                        },
+                        required: [
+                            "rationale_for_transfer",
+                            "conversation_context",
+                            "destination_agent",
+                            "confidence",
+                        ],
+                        additionalProperties: false,
+                    },
+                    strict: true,
+                },
+            };
+            // Ensure the agent has a tools array
+            if (!agentDef.tools) {
+                agentDef.tools = [];
+            }
+            // Add the newly created tool to the current agent's tools
+            agentDef.tools.push(transferAgentTool);
+            // console.log('--- DBG injectTransferTools',agentDef.name,'with new transfer',JSON.stringify(transferAgentTool.function.parameters,null,2 ));
+        }
+        // so .stringify doesn't break with circular dependencies
+        agentDef.downstreamAgents = agentDef.downstreamAgents?.map(({ name, publicDescription, human }) => ({
+            name,
+            publicDescription,
+            human
+        }));
+        agentDef.ready = true;
+    });
+    return agentDefs;
+}
+//
+// Fonction pour gérer un appel de fonction retourné par OpenAI
+// le contexte est un objet qui contient des informations supplémentaires de session
+async function handleTransferCall(memory, functionCallParams, session) {
+    const { agents } = memory;
+    const currentAgentName = memory.currentAgent?.name;
+    const args = JSON.parse(functionCallParams?.function?.arguments || '{}');
+    // console.log("↩️ Appel de fonction à gérer :",currentAgent?.name,'->', functionCallParams.function.name,'::',args);
+    if (functionCallParams.function.name === "transferAgents") {
+        if (args.confidence < 0.7) {
+            return {
+                content: "Le transfert n'est pas nécessaire, tu DOIS répondre directement",
+                feedback: args.rationale_for_transfer,
+                did_transfer: false,
+                name: functionCallParams.function.name
+            };
+        }
+        const destinationAgentName = args.destination_agent;
+        console.log(`🤖 Transfert de l'agent "${currentAgentName}" vers "${destinationAgentName}" (${args?.confidence})`, '::', args?.rationale_for_transfer);
+        // For debug, we don't want to transfer to the same agent
+        if (currentAgentName === destinationAgentName) {
+            console.log("❌ Le transfert sur moi-même n'est pas nécessaire", destinationAgentName, args);
+            memory.messages.slice(1).forEach(m => {
+                process.stdout.write(`--    DBG      ---> 🤖 ${m.role}: ${m.content}\n`);
+            });
+        }
+        //
+        // agent transfer to the destination agent
+        const destinationAgent = agents.find((agent) => agent.name === destinationAgentName);
+        if (destinationAgent) {
+            //console.log(`🤖 Agent "${destinationAgent.name}" en préparation`);
+            memory.currentAgent = destinationAgent;
+            return {
+                feedback: args.rationale_for_transfer,
+                destination_agent: destinationAgentName,
+                source_agent: currentAgentName,
+                did_transfer: true,
+                name: functionCallParams.function.name
+            };
+        }
+        else {
+            console.log("❌ Agent non trouvé !");
+            return {
+                feedback: "L'agent destination n'a pas été trouvé.",
+                did_transfer: false,
+                name: functionCallParams.function.name
+            };
+        }
+    }
+    if (functionCallParams.function.name === "thinking") {
+        const { justification, thought, step } = args;
+        console.log('🤖', memory.currentAgent?.name, '->', functionCallParams.function.name, '::', thought, '(step', step, ')');
+        return {
+            feedback: justification,
+            content: `Pour l'étape ${step}, j'ai pensé à "${thought}"`,
+            name: functionCallParams.function.name,
+            usage: 0
+        };
+    }
+    //
+    // looking on agents tool logic
+    const agent = memory.currentAgent;
+    if (agent?.toolLogic && agent.toolLogic[functionCallParams.function.name]) {
+        const { content, usage } = await agent.toolLogic[functionCallParams.function.name](args, session);
+        console.log('🤖', agent.name, '->', functionCallParams.function.name, '::usage', usage);
+        return {
+            content,
+            name: functionCallParams.function.name,
+            usage
+        };
+    }
+    else {
+        // whit thinking, we hask the agent to restart the conversation 
+        // console.log('🤖',agent.name,'->',agent.tools[0]);
+        console.log("❌ Cette fonction n'existe pas !", agent.name, functionCallParams.function.name);
+        return {
+            feedback: `Humm, cette fonction "${functionCallParams.function.name}" n'existe pas!`,
+            name: functionCallParams.function.name,
+            content: `Cette fonction "${functionCallParams.function.name}" n'existe pas, tu ne dois plus l'appeler et TU DOIS répondre à la question.`
+        };
+    }
+}
+/**
+ * Calls the system review agent to analyze a prompt
+ *
+ * This function sends a prompt to the system review agent and returns its analysis.
+ * The system review agent evaluates prompts based on various criteria like clarity,
+ * identity, scope, decision logic, etc.
+ *
+ * @param {string} prompt - The prompt text to be analyzed by the system review agent
+ * @param {Object} params - Parameters for the API call
+ * @param {Object} params.openai - The OpenAI client instance
+ * @param {Object} params.defaultOptions - Default options to be merged with agent model options
+ * @returns {Promise<string>} The analysis response from the system review agent
+ */
+async function callForSystemReview(prompt, params) {
+    const { openai, defaultOptions } = params;
+    const agent = system_1.system;
+    const options = Object.assign({}, agent.model, defaultOptions || {});
+    const jsonOptions = `
+- L'option JSON a été activée, tu dois respecter le format brut suivant \`
+{
+  directives: [
+    {"directive": "...","criteria": [{"criterion": "...","score": "...","comment": "..."}]},
+    ...
+  ]
+}
+\``;
+    //
+    // add the initial agent to his memory
+    // Handle two-shot prompting: if instructions is an array, use the first part as a system message
+    const instructions = agent.instructions;
+    options.messages = [
+        { role: "system", content: instructions }
+    ];
+    if (options.response_format?.type == "json_object") {
+        options.messages.push({ role: "user", content: jsonOptions });
+    }
+    options.messages.push({ role: "user", content: `tu dois analyser toutes les directives:\n ${prompt}` });
+    let thinking = 1;
+    //
+    // loop until the agent has finished thinking
+    do {
+        const response = await openai.chat.completions.create(options);
+        const cost = (0, princing_openai_1.calculateCost)(options.model, response.usage);
+        if (options.response_format?.type == "json_object") {
+            const content = JSON.parse(response.choices[0].message.content || '{}');
+            return { content, cost };
+        }
+        // Handle two-shot prompting: if instructions is an array, send the second part as a user message
+        // This allows for more complex agent behavior by providing additional context or instructions
+        // after the initial response, similar to chain-of-thought prompting
+        if (!Array.isArray(agent.instructions) || thinking >= agent.instructions.length) {
+            const content = response.choices[0].message.content;
+            return { content, cost };
+        }
+        const instructions = agent.instructions[thinking];
+        options.messages.push({ role: "user", content: instructions });
+        thinking++;
+    } while (true);
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "agentic-api",
+  "version": "1.0.1",
+  "description": "API pour l'orchestration d'agents intelligents avec séquences et escalades automatiques",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist/src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "lint": "eslint 'src/**/*.ts'",
+    "prepublishOnly": "npm run build",
+    "extract:pdf": "texttopdf "
+  },
+  "optionalDependencies": {
+    "python3": ">=3.5"
+  },
+  "dependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "dotenv": "^16.4.7",
+    "hnswlib-node": "^3.0.0",
+    "jsdom": "^26.0.0",
+    "openai": "^4.89.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/jsdom": "^21.1.7",
+    "@types/node": "^22.13.2",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.7.3"
+  },
+  "keywords": [
+    "agent",
+    "llm",
+    "openai",
+    "rag",
+    "ai"
+  ],
+  "author": "Olivier Evalet",
+  "license": "MIT"
+}