Agents & Outils

Construisez des agents structurés avec des outils et politiques, garantissant desgarde-fous déterministes.

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 } from '@orka-js/core';
import { OpenAIAdapter } from '@orka-js/openai';
import type { Tool } from '@orka-js/tools';
 
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 '@orka-js/tools';
 
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

Interface d'Outil Agentique

Functional Contract for LLM Tool-Calling

nameIdentity

string

Identifiant snake_case unique (ex: fetch_user_data).

descriptionSemantics

string

Prompt sémantique détaillé pour la décision du LLM.

parametersValidation

ToolParameter[]

Schéma typé avec noms et drapeaux obligatoires.

execute()Execution

Promise<ToolResult>

La logique opérationnelle retournant sortie ou erreurs.

# 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 Raisonnement & Action

Les agents Orka JS utilisent une architecture ReAct cyclique pour entrelacer les processus de pensée avec des interactions réelles.

Think— Raisonnement

"Je dois d'abord trouver le statut de la commande"

Act— Appel d'Outil

Appeler get_order({ id: '123' })

Observe— Observation

"Statut : Expédié via FedEx"

Finish— Synthèse finale

Livrer la réponse à 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 '@orka-js/core';
import type { Tool } from '@orka-js/tools';
 
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."

Frameworks d'Agents Avancés

High-Autonomy Decision Systems

ReAct & Structured Chat

Dynamic

Raisonnement dynamique entrelacé avec l'usage d'outils pour une flexibilité conversationnelle.

Plan-and-Execute

Architected

Décomposition d'objectifs en feuille de route fixe avant toute exécution d'outil.

OpenAI Functions

Native

Intégration native pour l'extraction de données structurées avec une fiabilité maximale.

Toolkits (SQL, CSV)

Domain-Specific

Connecteurs spécialisés pour l'interaction directe avec des sources de données structurées.

Besoin de gérer des raisonnements complexes ? Explorez notre documentation spécialisée.

Imports Tree-shakeable

// ✅ Import types
import type { Tool, ToolParameter, ToolResult } from '@orka-js/tools';
 
// ✅ Import agent types for advanced usage
import { ReActAgent, PlanAndExecuteAgent } from '@orka-js/agent';