Workflows Multi-Étapes

Enchaînez des opérations LLM dans des pipelines lisibles et testables avec les workflows Orka AI.

Pourquoi des Workflows ?

Les workflows vous permettent d'enchaîner plusieurs opérations LLM dans un pipeline unique et lisible. Chaque étape transforme le contexte et le passe à la suivante. Les étapes intégrées gèrent les patterns courants comme la planification, la récupération, la génération et la vérification — mais vous pouvez aussi créer des étapes personnalisées pour n'importe quelle logique.

import { createOrka } from 'orkajs/core';
import { OpenAIAdapter } from 'orkajs/adapters';
import { plan, retrieve, generate, verify, improve } from 'orkajs/workflow';
 
const orka = createOrka({
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
  vectorDB: myVectorDB,
});
 
const workflow = orka.workflow({
  name: 'support-response',
  steps: [
    plan(),                                    // Analyze input and create action plan
    retrieve('knowledge-base', { topK: 5 }),   // Semantic search in knowledge base
    generate({ temperature: 0.7 }),            // Generate response using LLM
    verify({ criteria: ['relevant', 'no hallucination'] }), // Evaluate quality
    improve({ maxIterations: 1 }),             // Fix issues if verify fails
  ],
});
 
const result = await workflow.run('How do I reset my password?');
 
console.log(result.output);          // Final response
console.log(result.steps);           // Results from each step
console.log(result.totalLatencyMs);  // Total execution time
console.log(result.totalTokens);     // Total tokens consumed

# Étapes Intégrées

Orka fournit six étapes de workflow intégrées qui couvrent les patterns LLM les plus courants :

plan()

Analyser l'entrée et créer un plan d'action

retrieve(name, opts)

Recherche sémantique dans une base de connaissances

generate(opts)

Générer une réponse avec le LLM

verify(opts)

Évaluer la qualité avec LLM-as-judge

improve(opts)

Corriger les problèmes identifiés par verify

custom(name, fn)

Créer n'importe quelle étape personnalisée

# Détails des Étapes

plan()

Analyse l'entrée et crée un plan d'action. Utile pour les requêtes complexes qui nécessitent plusieurs étapes.

plan()
// Output: "1. Search for password reset documentation
2. Extract relevant steps
3. Format as user-friendly instructions"

retrieve(name, options)

Effectue une recherche sémantique dans une base de connaissances et ajoute les résultats au contexte.

retrieve('documentation', {
  topK: 5,           // Number of results to retrieve
  minScore: 0.7,     // Minimum similarity score
  filter: { category: 'guides' } // Metadata filter
})

generate(options)

Génère une réponse en utilisant le LLM avec le contexte actuel (entrée + documents récupérés).

generate({
  temperature: 0.7,  // Creativity level (0-1)
  maxTokens: 1000,   // Maximum response length
  systemPrompt: 'You are a helpful assistant.' // Custom system prompt
})

verify(options)

Évalue la sortie générée par rapport à des critères en utilisant LLM-as-judge. Définit ctx.verified à true/false.

verify({
  criteria: [
    'relevant',           // Is the answer relevant to the question?
    'no hallucination',   // Is the answer grounded in the context?
    'complete',           // Does it fully answer the question?
    'professional tone'   // Is the tone appropriate?
  ]
})

improve(options)

Si verify() a échoué, tente de corriger les problèmes. S'exécute jusqu'à maxIterations fois.

improve({
  maxIterations: 2,  // Maximum improvement attempts
  // Automatically uses the verification feedback to improve the output
})

# Étapes Personnalisées

Créez des étapes personnalisées pour toute logique non couverte par les étapes intégrées. Les étapes personnalisées reçoivent le contexte du workflow et doivent le retourner.

import { custom } from 'orkajs/workflow';
 
// Custom step to translate the output
const translateStep = custom('translate', async (ctx) => {
  const result = await ctx.llm.generate(
    `Translate to French: ${ctx.output}`,
    { temperature: 0.3 }
  );
 
  ctx.output = result.content;
  ctx.metadata.translatedTo = 'fr';
 
  // Record step in history
  ctx.history.push({
    stepName: 'translate',
    output: result.content,
    latencyMs: result.latencyMs,
    tokens: result.usage?.totalTokens,
  });
 
  return ctx;
});
 
// Use in workflow
const workflow = orka.workflow({
  name: 'multilingual-support',
  steps: [
    retrieve('docs'),
    generate(),
    translateStep,  // Your custom step
  ],
});

Contexte du Workflow (ctx)

ctx.input: string

L'entrée originale passée à workflow.run()

ctx.output: string

La sortie actuelle (modifiée par chaque étape)

ctx.retrievedDocs: Document[]

Documents récupérés par l'étape retrieve()

ctx.llm: LLMAdapter

L'adaptateur LLM pour faire des appels

ctx.metadata: Record<string, unknown>

Métadonnées personnalisées que vous pouvez définir/lire entre les étapes

# Résultat du Workflow

La méthode workflow.run() retourne un objet WorkflowResult avec la sortie finale et des informations d'exécution détaillées :

Propriété	Type	Description
output	`string`	Sortie finale après toutes les étapes
steps	`WorkflowStepResult[]`	Résultats de chaque étape
totalLatencyMs	`number`	Temps d'exécution total
totalTokens	`number`	Total de tokens consommés
verified	`boolean`	Si verify() a réussi (si utilisé)

Exemple Complet

workflow-step-example.ts

import { createOrka } from 'orkajs/core';
import { OpenAIAdapter, PineconeAdapter } from 'orkajs/adapters';
import { plan, retrieve, generate, verify, improve, custom } from 'orkajs/workflow';
 
const orka = createOrka({
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
  vectorDB: new PineconeAdapter({ apiKey: process.env.PINECONE_API_KEY! }),
});
 
// Custom logging step
const logStep = custom('log', async (ctx) => {
  console.log('[Workflow] Current output length:', ctx.output.length);
  return ctx;
});
 
const supportWorkflow = orka.workflow({
  name: 'customer-support',
  steps: [
    plan(),
    retrieve('support-docs', { topK: 5 }),
    generate({ temperature: 0.5, systemPrompt: 'You are a helpful support agent.' }),
    logStep,
    verify({ criteria: ['helpful', 'accurate', 'professional'] }),
    improve({ maxIterations: 1 }),
  ],
});
 
async function handleSupportQuery(query: string) {
  const result = await supportWorkflow.run(query);
 
  console.log('Answer:', result.output);
  console.log('Verified:', result.verified);
  console.log('Steps:', result.steps.map(s => s.stepName));
  console.log('Total time:', result.totalLatencyMs, 'ms');
  console.log('Total tokens:', result.totalTokens);
 
  return result.output;
}
 
await handleSupportQuery('How do I cancel my subscription?');

Imports Tree-shakeable

// ✅ Import only what you need
import { plan, retrieve, generate, verify, improve, custom } from 'orkajs/workflow';
 
// ✅ Or import from main package
import { plan, retrieve, generate } from 'orkajs';