OrkaJS
Orka.JS

Types d'Agents Avancés

Architectures d'agents spécialisées pour différents patterns de raisonnement : ReAct pour le raisonnement étape par étape, Plan-and-Execute pour les tâches complexes multi-étapes, OpenAI Functions pour l'appel structuré d'outils, et Structured Chat pour les interactions basées sur JSON. Plus des toolkits pré-construits pour l'analyse de données SQL et CSV.

🧠

ReAct Agent

Raisonnement + Action : pense étape par étape, utilise des outils, observe les résultats

📋

Plan-and-Execute

Planifie d'abord, puis exécute chaque étape. Re-planifie en cas d'échec.

⚡

OpenAI Functions

Utilise le format d'appel de fonctions OpenAI pour une invocation précise d'outils

💬

Structured Chat

Appel d'outils basé sur JSON avec validation optionnelle du schéma de sortie

# Agent ReAct — Raisonnement + Action

L'agent ReAct suit la boucle Pensée → Action → Observation. À chaque étape, il raisonne sur ce qu'il faut faire, effectue une action (appelle un outil), observe le résultat et répète jusqu'à pouvoir fournir une réponse finale. C'est le pattern d'agent le plus polyvalent et il fonctionne bien pour la plupart des tâches.

import { ReActAgent } from 'orkajs/agent/react';
import { OpenAIAdapter } from 'orkajs/adapters/openai';
import type { Tool } from 'orkajs';
 
const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! });
 
// Define tools
const searchTool: Tool = {
  name: 'web_search',
  description: 'Search the web for current information',
  parameters: [
    { name: 'query', type: 'string', description: 'Search query', required: true }
  ],
  execute: async (input) => {
    const results = await mySearchAPI(input.query as string);
    return { output: results };
  }
};
 
const calculatorTool: Tool = {
  name: 'calculator',
  description: 'Perform mathematical calculations',
  parameters: [
    { name: 'expression', type: 'string', description: 'Math expression to evaluate', required: true }
  ],
  execute: async (input) => {
    const result = eval(input.expression as string); // Use a safe math parser in production
    return { output: String(result) };
  }
};
 
// Create ReAct agent
const agent = new ReActAgent(
  {
    goal: 'Help users find information and perform calculations',
    tools: [searchTool, calculatorTool],
    maxSteps: 10,
    verbose: true,  // Logs each Thought/Action/Observation
    policy: {
      rules: [
        'Always verify information from multiple sources',
        'Show your calculations step by step'
      ]
    }
  },
  llm
);
 
const result = await agent.run('What is the population of France times 2?');
 
console.log(result.output);
// "The population of France is approximately 68 million. 68,000,000 × 2 = 136,000,000."
 
console.log(result.steps);
// [
//   { thought: "I need to find the population of France", action: "web_search", ... },
//   { thought: "Now I need to multiply by 2", action: "calculator", ... }
// ]

🔄 Boucle ReAct

  1. Thought: "Je dois d'abord trouver la population de la France"
  2. Action: web_search({query: "population France 2024"})
  3. Observation: "La France compte environ 68 millions d'habitants"
  4. Thought: "Maintenant je dois multiplier 68 000 000 par 2"
  5. Action: calculator({expression: "68000000 * 2"})
  6. Observation: "136000000"
  7. Action: finish({answer: "136 000 000"})

# Agent Plan-and-Execute

L'agent Plan-and-Execute sépare la planification de l'exécution. D'abord, il crée un plan complet d'étapes. Ensuite, il exécute chaque étape une par une. Si une étape échoue et que replanOnFailure est activé, il ajuste dynamiquement le plan restant. Cette architecture est idéale pour les tâches complexes multi-étapes où avoir une feuille de route claire améliore la fiabilité.

import { PlanAndExecuteAgent } from 'orkajs/agent/plan-and-execute';
 
const agent = new PlanAndExecuteAgent(
  {
    goal: 'Research and analyze data to answer complex questions',
    tools: [searchTool, calculatorTool, databaseTool],
    maxSteps: 15,
    replanOnFailure: true,  // Dynamically adjust plan if a step fails
  },
  llm
);
 
const result = await agent.run(
  'Compare the GDP per capita of France, Germany, and Japan. Which has grown the most in the last 5 years?'
);
 
console.log(result.output);
// Comprehensive comparison with data and analysis
 
console.log(result.plan);
// [
//   { id: 1, description: "Search for France GDP per capita data", status: "completed", result: "..." },
//   { id: 2, description: "Search for Germany GDP per capita data", status: "completed", result: "..." },
//   { id: 3, description: "Search for Japan GDP per capita data", status: "completed", result: "..." },
//   { id: 4, description: "Calculate growth rates for each country", status: "completed", result: "..." },
//   { id: 5, description: "Compare and determine highest growth", status: "completed", result: "..." }
// ]
 
console.log(result.steps);
// Detailed execution trace with timing and token usage per step

✅ Quand Utiliser Plan-and-Execute

  • Tâches complexes nécessitant plusieurs étapes
  • Workflows de recherche et d'analyse
  • Tâches où l'ordre des opérations compte
  • Quand vous avez besoin d'un plan d'exécution visible

❌ Quand NE PAS Utiliser

  • Requêtes simples en une étape
  • Agents conversationnels en temps réel
  • Tâches où le chemin est imprévisible

# Agent OpenAI Functions

Utilise le format d'appel de fonctions OpenAI pour une invocation d'outils précise et structurée. Les outils sont décrits comme des schémas JSON, et le LLM répond avec des appels de fonctions structurés au lieu d'un parsing de texte libre. Cela résulte en une utilisation d'outils plus fiable avec moins d'erreurs de parsing.

import { OpenAIFunctionsAgent } from 'orkajs/agent/openai-functions';
 
const agent = new OpenAIFunctionsAgent(
  {
    goal: 'Help users manage their tasks and calendar',
    tools: [
      {
        name: 'create_event',
        description: 'Create a calendar event',
        parameters: [
          { name: 'title', type: 'string', description: 'Event title', required: true },
          { name: 'date', type: 'string', description: 'Event date (YYYY-MM-DD)', required: true },
          { name: 'time', type: 'string', description: 'Event time (HH:MM)', required: false },
        ],
        execute: async (input) => {
          await calendarAPI.create(input);
          return { output: `Event "${input.title}" created for ${input.date}` };
        }
      },
      {
        name: 'list_events',
        description: 'List calendar events for a date range',
        parameters: [
          { name: 'start_date', type: 'string', description: 'Start date', required: true },
          { name: 'end_date', type: 'string', description: 'End date', required: true },
        ],
        execute: async (input) => {
          const events = await calendarAPI.list(input.start_date, input.end_date);
          return { output: JSON.stringify(events) };
        }
      }
    ],
    // Optional: provide custom function definitions (auto-generated from tools if omitted)
    // functions: [{ name: 'create_event', description: '...', parameters: { ... } }],
    maxSteps: 5,
  },
  llm
);
 
const result = await agent.run('Schedule a team meeting for next Monday at 2pm');
 
console.log(result.output);
// "I've created a 'Team Meeting' event for 2024-03-18 at 14:00."
 
console.log(result.metadata);
// { agentType: 'openai-functions', stepsUsed: 1 }

🔧 Schémas de Fonctions Auto-générés

Si vous ne fournissez pas de définitions de fonctions personnalisées, l'agent convertit automatiquement vos définitions Tool en schémas de fonctions compatibles OpenAI :

// Your Tool definition:
{ name: 'create_event', parameters: [{ name: 'title', type: 'string', required: true }] }
 
// Auto-generated OpenAI function schema:
{
  "name": "create_event",
  "parameters": {
    "type": "object",
    "properties": { "title": { "type": "string" } },
    "required": ["title"]
  }
}

# Agent Structured Chat

L'agent Structured Chat communique entièrement via JSON. Chaque réponse — qu'il s'agisse d'un appel d'outil ou d'une réponse finale — est un objet JSON structuré. Cela le rend très prévisible et facile à intégrer dans des systèmes qui nécessitent des sorties structurées. Vous pouvez optionnellement définir un schéma de sortie pour imposer le format de la réponse finale.

import { StructuredChatAgent } from 'orkajs/agent/structured-chat';
 
const agent = new StructuredChatAgent(
  {
    goal: 'Analyze customer support tickets and route them',
    tools: [
      {
        name: 'classify_ticket',
        description: 'Classify a support ticket by category and urgency',
        parameters: [
          { name: 'text', type: 'string', description: 'Ticket text', required: true }
        ],
        execute: async (input) => {
          // Classification logic
          return { output: JSON.stringify({ category: 'billing', urgency: 'high' }) };
        }
      },
      {
        name: 'route_ticket',
        description: 'Route a ticket to the appropriate team',
        parameters: [
          { name: 'category', type: 'string', description: 'Ticket category', required: true },
          { name: 'urgency', type: 'string', description: 'Urgency level', required: true }
        ],
        execute: async (input) => {
          return { output: `Routed to ${input.category} team (priority: ${input.urgency})` };
        }
      }
    ],
    // Optional: enforce output format
    outputSchema: {
      type: 'object',
      properties: {
        category: { type: 'string' },
        urgency: { type: 'string' },
        team: { type: 'string' },
        summary: { type: 'string' }
      }
    },
    maxSteps: 5,
  },
  llm
);
 
const result = await agent.run('Customer says: "I was charged twice for my subscription!"');
 
console.log(result.output);
// "Classified as billing/high urgency. Routed to billing team with priority handling."
 
console.log(result.steps);
// All steps are structured JSON — easy to log and audit

# Toolkits d'Agents

Les toolkits sont des collections pré-construites d'outils pour les tâches courantes d'analyse de données. Au lieu de définir les outils manuellement, utilisez un toolkit pour équiper instantanément n'importe quel agent avec des capacités spécifiques à un domaine.

- Toolkit SQL

Fournit des outils pour interroger des bases de données SQL : exécuter des requêtes, inspecter le schéma et lister les tables. Supporte le mode lecture seule pour la sécurité et l'injection automatique de LIMIT.

import { SQLToolkit } from 'orkajs/agent/toolkits/sql';
import { ReActAgent } from 'orkajs/agent/react';
 
const sqlToolkit = new SQLToolkit({
  execute: async (query: string) => {
    // Connect to your database
    const result = await db.query(query);
    return JSON.stringify(result.rows);
  },
  schema: `
    CREATE TABLE users(id INT, name VARCHAR, email VARCHAR, created_at TIMESTAMP);
    CREATE TABLE orders(id INT, user_id INT, amount DECIMAL, status VARCHAR, created_at TIMESTAMP);
    CREATE TABLE products(id INT, name VARCHAR, price DECIMAL, category VARCHAR);
  `,
  readOnly: true,   // Only SELECT queries allowed
  maxRows: 50       // Auto-inject LIMIT 50
});
 
// Use with any agent type
const agent = new ReActAgent(
  {
    goal: 'Answer questions about the database by writing SQL queries',
    tools: sqlToolkit.tools,  // Includes: sql_query, sql_schema, sql_list_tables
    maxSteps: 8,
  },
  llm
);
 
const result = await agent.run('How many orders were placed last month? What was the total revenue?');
 
// The agent will:
// 1. Use sql_schema to understand the tables
// 2. Write and execute SQL queries
// 3. Synthesize the results into a natural language answer

🛡️ Fonctionnalités de Sécurité du Toolkit SQL

  • readOnly: Quand activé, seules les requêtes SELECT/WITH/EXPLAIN sont autorisées. INSERT, UPDATE, DELETE sont bloqués.
  • maxRows: Ajoute automatiquement LIMIT aux requêtes SELECT pour éviter les requêtes incontrôlées.
  • schema: Fournissez le schéma pour que l'agent comprenne la structure de la base sans interroger information_schema.

- Toolkit CSV

Fournit des outils pour analyser des données CSV en mémoire : recherche, filtrage et agrégation. Pas de base de données requise — passez simplement vos données CSV comme une chaîne de caractères.

import { CSVToolkit } from 'orkajs/agent/toolkits/csv';
import { ReActAgent } from 'orkajs/agent/react';
 
const csvData = `name,department,salary,start_date
Alice,Engineering,95000,2021-03-15
Bob,Marketing,72000,2020-06-01
Charlie,Engineering,105000,2019-01-10
Diana,Sales,68000,2022-09-20
Eve,Engineering,88000,2023-02-01`;
 
const csvToolkit = new CSVToolkit({
  data: csvData,
  separator: ','  // default
});
 
const agent = new ReActAgent(
  {
    goal: 'Analyze employee data and answer questions',
    tools: csvToolkit.tools,  // Includes: csv_info, csv_search, csv_filter, csv_aggregate
    maxSteps: 8,
  },
  llm
);
 
// Ask questions about the data
const result = await agent.run('What is the average salary in Engineering? Who earns the most?');
 
// The agent will use csv_filter and csv_aggregate tools to find the answer
console.log(result.output);
// "The average salary in Engineering is $96,000. Charlie earns the most at $105,000."
 
// CSV Toolkit tools:
// - csv_info: Get column names, row count, sample data
// - csv_search: Search for rows by column value (partial match)
// - csv_filter: Filter rows with operators (=, !=, >, <, >=, <=, contains)
// - csv_aggregate: count, sum, avg, min, max, distinct

# Combiner Agents et Toolkits

Vous pouvez combiner plusieurs toolkits et outils personnalisés avec n'importe quel type d'agent :

import { PlanAndExecuteAgent } from 'orkajs/agent/plan-and-execute';
import { SQLToolkit } from 'orkajs/agent/toolkits/sql';
import { CSVToolkit } from 'orkajs/agent/toolkits/csv';
 
const sqlToolkit = new SQLToolkit({ execute: db.query, readOnly: true });
const csvToolkit = new CSVToolkit({ data: reportCSV });
 
// Combine toolkit tools with custom tools
const allTools = [
  ...sqlToolkit.tools,
  ...csvToolkit.tools,
  myCustomSearchTool,
  myCalculatorTool,
];
 
const agent = new PlanAndExecuteAgent(
  {
    goal: 'Cross-reference database records with CSV reports',
    tools: allTools,
    maxSteps: 15,
    replanOnFailure: true,
  },
  llm
);
 
const result = await agent.run(
  'Compare the sales figures in the CSV report with the orders table in the database. Are there any discrepancies?'
);

Comparaison des Types d'Agents

AgentPatternIdéal PourFiabilité
Agent (base)Thought/ActionUtilisation simple d'outils⭐⭐⭐
ReActThink → Act → ObserveRaisonnement polyvalent⭐⭐⭐⭐
Plan-and-ExecutePlan → Execute → SynthesizeTâches complexes multi-étapes⭐⭐⭐⭐⭐
OpenAI FunctionsJSON function callsInvocation précise d'outils⭐⭐⭐⭐⭐
Structured ChatJSON in/outSorties structurées, audit⭐⭐⭐⭐

Bonnes Pratiques

1. Choisissez le Bon Type d'Agent

Utilisez ReAct pour les tâches générales, Plan-and-Execute pour les workflows complexes multi-étapes, OpenAI Functions quand vous avez besoin d'appels d'outils précis, et Structured Chat quand vous avez besoin de sorties JSON.

2. Définissez des Limites Appropriées

Définissez toujours maxSteps pour éviter les boucles infinies. Utilisez les policies pour restreindre l'accès aux outils et imposer des règles.

3. Utilisez les Toolkits pour l'Analyse de Données

SQLToolkit et CSVToolkit fournissent des outils éprouvés. Utilisez toujours le mode readOnly pour SQL en production. Combinez plusieurs toolkits pour l'analyse croisée de données.

4. Surveillez avec le Mode verbose

Activez verbose: true sur ReActAgent pendant le développement pour voir chaque Pensée/Action/Observation dans la console. Tous les agents retournent des étapes détaillées pour le monitoring en production.

Imports Tree-shakeable

// ✅ Import only what you need
import { ReActAgent } from 'orkajs/agent/react';
import { PlanAndExecuteAgent } from 'orkajs/agent/plan-and-execute';
import { OpenAIFunctionsAgent } from 'orkajs/agent/openai-functions';
import { StructuredChatAgent } from 'orkajs/agent/structured-chat';
import { SQLToolkit } from 'orkajs/agent/toolkits/sql';
import { CSVToolkit } from 'orkajs/agent/toolkits/csv';
 
// ✅ Or import from agent index
import { ReActAgent, PlanAndExecuteAgent, SQLToolkit } from 'orkajs/agent';