Agents & Outils

Construisez des agents IA structurés et déterministes avec des outils, des politiques et des garde-fous de sécurité.

Pourquoi des Agents ?

Les agents sont des LLMs qui peuvent prendre des actions. Au lieu de simplement générer du texte, ils peuvent appeler des outils (fonctions) pour interagir avec des systèmes externes, des bases de données, des APIs, et plus encore. Les agents Orka suivent une boucle de raisonnement structurée : ils réfléchissent à ce qu'il faut faire, prennent une action, observent le résultat, et répètent jusqu'à avoir une réponse finale.

import { createOrka, OpenAIAdapter } from 'orkajs';
import type { Tool } from 'orkajs';
 
const orka = createOrka({
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
  vectorDB: myVectorDB,
});
 
const agent = orka.agent({
  goal: 'Help customers with their orders',
  tools: [getOrder, cancelOrder, refundOrder],
  policy: {
    maxSteps: 5,
    noHallucination: true,
    rules: ['Always verify order exists before any action'],
  },
});
 
const result = await agent.run('What is the status of order ORD-123?');
 
console.log(result.output);      // "Order ORD-123 is currently being shipped..."
console.log(result.toolsUsed);   // ['get_order']
console.log(result.steps);       // Detailed reasoning trace
console.log(result.totalTokens); // Token usage

# Définir des Outils

Les outils sont des fonctions que les agents peuvent appeler. Chaque outil a un nom, une description, des paramètres et une fonction execute. La description est cruciale — elle indique au LLM quand et comment utiliser l'outil.

import type { Tool } from 'orkajs';
 
const getOrder: Tool = {
  name: 'get_order',
  description: 'Retrieve an order by its ID. Returns order status, items, and shipping info.',
  parameters: [
    {
      name: 'orderId',
      type: 'string',
      description: 'The order ID (e.g., ORD-123)',
      required: true,
    },
  ],
  async execute(input) {
    const order = await db.orders.findById(input.orderId as string);
    if (!order) {
      return { output: '', error: `Order ${input.orderId} not found` };
    }
    return {
      output: `Order ${order.id}: ${order.status}, shipped via ${order.carrier}`,
      metadata: { orderId: order.id, status: order.status },
    };
  },
};
 
const cancelOrder: Tool = {
  name: 'cancel_order',
  description: 'Cancel an order. Only works for orders not yet shipped.',
  parameters: [
    { name: 'orderId', type: 'string', description: 'Order ID to cancel', required: true },
    { name: 'reason', type: 'string', description: 'Cancellation reason', required: false },
  ],
  async execute(input) {
    const result = await db.orders.cancel(input.orderId as string, input.reason as string);
    if (!result.success) {
      return { output: '', error: result.error };
    }
    return { output: `Order ${input.orderId} has been cancelled.` };
  },
};

Interface Tool

name: string

Identifiant unique pour l'outil. Utilisez snake_case (ex: get_order, send_email).

description: string

Description claire de ce que fait l'outil. Le LLM l'utilise pour décider quand l'appeler.

parameters: ToolParameter[]

Tableau de { name, type, description, required }. Types : string, number, boolean, array, object.

execute(input): Promise<ToolResult>

Fonction async qui exécute l'outil. Retourne { output: string, error?: string, metadata?: object }.

# Politiques d'Agent

Les politiques contrôlent le comportement de l'agent et ajoutent des garde-fous de sécurité. Utilisez-les pour limiter les étapes, restreindre les outils et imposer des règles.

Propriété	Type	Description
maxSteps	`number`	Étapes de raisonnement max
noHallucination	`boolean`	Instruire l'agent de ne pas halluciner
rules	`string[]`	Règles personnalisées en langage naturel
allowedTools	`string[]`	Liste blanche des outils autorisés
blockedTools	`string[]`	Liste noire des outils interdits

💡 Boucle ReAct

Les agents Orka AI suivent une boucle ReAct (Raisonnement + Action) structurée :

Think: "Je dois d'abord trouver le statut de la commande"
Act: Appeler get_order({orderId: 'ORD-123'})
Observe: "Commande ORD-123 : expédiée via FedEx"
Think: "J'ai la réponse, je peux répondre"
Finish: Retourner la réponse finale à l'utilisateur

# Résultat de l'Agent

Propriété	Type	Description
output	`string`	Réponse finale de l'agent
toolsUsed	`string[]`	Noms des outils qui ont été appelés
steps	`AgentStep[]`	Trace détaillée de chaque étape de raisonnement
totalTokens	`number`	Total de tokens consommés
metadata	`object`	Métadonnées combinées de tous les appels d'outils

Exemple Complet

import { createOrka, OpenAIAdapter } from 'orkajs';
import type { Tool } from 'orkajs';
 
const orka = createOrka({
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
  vectorDB: myVectorDB,
});
 
// Define tools
const getWeather: Tool = {
  name: 'get_weather',
  description: 'Get current weather for a city',
  parameters: [
    { name: 'city', type: 'string', description: 'City name', required: true },
  ],
  execute: async (input) => {
    const weather = await weatherAPI.get(input.city as string);
    return { output: `${weather.temp}°C, ${weather.condition}` };
  },
};
 
const sendEmail: Tool = {
  name: 'send_email',
  description: 'Send an email to a recipient',
  parameters: [
    { name: 'to', type: 'string', description: 'Email address', required: true },
    { name: 'subject', type: 'string', description: 'Email subject', required: true },
    { name: 'body', type: 'string', description: 'Email body', required: true },
  ],
  execute: async (input) => {
    await emailService.send(input.to, input.subject, input.body);
    return { output: `Email sent to ${input.to}` };
  },
};
 
// Create agent with policies
const agent = orka.agent({
  goal: 'Help users with weather info and email tasks',
  tools: [getWeather, sendEmail],
  policy: {
    maxSteps: 5,
    noHallucination: true,
    rules: [
      'Always confirm before sending emails',
      'Provide temperature in both Celsius and Fahrenheit',
    ],
    blockedTools: [], // Could block 'send_email' for read-only mode
  },
});
 
// Run the agent
const result = await agent.run('What is the weather in Paris?');
console.log(result.output);
// "The current weather in Paris is 18°C (64°F), partly cloudy."

🚀 Agents Avancés

Pour des patterns d'agents plus sophistiqués (ReAct, Plan-and-Execute, OpenAI Functions, Structured Chat) et des toolkits pré-construits (SQL, CSV), consultez la documentation des Agents Avancés.

Imports Tree-shakeable

// ✅ Import types
import type { Tool, ToolParameter, ToolResult } from 'orkajs';
 
// ✅ Import agent types for advanced usage
import { ReActAgent } from 'orkajs/agent/react';
import { PlanAndExecuteAgent } from 'orkajs/agent/plan-and-execute';