@nextsparkjs/core 0.1.0-beta.2 → 0.1.0-beta.4

package/dist/templates/contents/plugins/langchain/docs/03-orchestration/02-legacy-react.md

@@ -1,650 +0,0 @@
-# Orchestration (Legacy)
-
-> **DEPRECATED**: This document describes the legacy ReAct-based orchestration approach.
-> For new implementations, use the **Graph-Based Orchestrator** which is 25-50x faster.
->
-> **Recommended**: See [Graph Orchestrator](./01-graph-orchestrator.md) for the modern approach.
->
-> **Migration**: Set `LANGCHAIN_USE_GRAPH_ORCHESTRATOR=true` to enable the new system.
-
----
-
-Orchestration enables complex multi-agent systems where a central orchestrator routes requests to specialized agents. This guide covers orchestration patterns, implementation, and best practices.
-
-## Why Orchestration?
-
-As applications grow, a single agent with many tools becomes:
-- **Hard to maintain**: Too many tools, complex prompts
-- **Slow**: LLM must consider all tools for every request
-- **Error-prone**: More tools = more chance of wrong tool selection
-
-Orchestration solves this by:
-- **Separating concerns**: Each agent handles one domain
-- **Improving focus**: Smaller tool sets = better accuracy
-- **Enabling specialization**: Different models/temps per domain
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                          USER REQUEST                            │
-│                    "Show me customer details"                    │
-└─────────────────────────────────────────────────────────────────┘
-                               │
-                               ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                        ORCHESTRATOR                              │
-│                                                                  │
-│  ┌─────────────────────────────────────────────────────────┐    │
-│  │                    System Prompt                         │    │
-│  │    "Analyze intent and route to appropriate agent"       │    │
-│  └─────────────────────────────────────────────────────────┘    │
-│                               │                                  │
-│  ┌─────────────────────────────────────────────────────────┐    │
-│  │                    Routing Tools                         │    │
-│  │  route_to_task | route_to_customer | route_to_page      │    │
-│  └─────────────────────────────────────────────────────────┘    │
-│                                                                  │
-│                    Decision: route_to_customer                   │
-└─────────────────────────────────────────────────────────────────┘
-                               │
-                               ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                     CUSTOMER AGENT                               │
-│                                                                  │
-│  Tools: search_customers, get_customer, update_customer, ...    │
-│                                                                  │
-│  *Executes request and returns response*                        │
-└─────────────────────────────────────────────────────────────────┘
-                               │
-                               ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                           RESPONSE                               │
-│                    "Here's the customer..."                      │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Implementation
-
-### Step 1: Configure Agents
-
-```typescript
-// langchain.config.ts
-export const AGENTS = {
-    // Orchestrator - low temperature for consistent routing
-    'orchestrator': {
-        provider: 'ollama',
-        temperature: 0.1,
-        description: 'Routes requests to specialized agents',
-        systemPrompt: 'orchestrator',
-        createTools: () => createOrchestratorTools(),
-    },
-
-    // Specialized agents
-    'task-assistant': {
-        provider: 'ollama',
-        temperature: 0.3,
-        systemPrompt: 'task-assistant',
-        createTools: (ctx) => createTaskTools(ctx),
-    },
-    'customer-assistant': {
-        provider: 'ollama',
-        temperature: 0.3,
-        systemPrompt: 'customer-assistant',
-        createTools: (ctx) => createCustomerTools(ctx),
-    },
-    'page-assistant': {
-        provider: 'ollama',
-        temperature: 0.3,
-        systemPrompt: 'page-assistant',
-        createTools: (ctx) => createPageTools(ctx),
-    },
-}
-```
-
-### Step 2: Create Routing Tools
-
-```typescript
-// tools/orchestrator.ts
-import { z } from 'zod'
-
-export interface RoutingResult {
-    agent: 'task' | 'customer' | 'page'
-    message: string
-}
-
-export interface ClarificationResult {
-    action: 'clarify'
-    question: string
-    options: Array<{ label: string; description: string }>
-}
-
-export function createOrchestratorTools() {
-    return [
-        {
-            name: 'route_to_task',
-            description: 'Route to task agent when user mentions tasks, todos, or work items.',
-            schema: z.object({
-                message: z.string().describe('User message to forward'),
-            }),
-            func: async ({ message }) => {
-                return JSON.stringify({ agent: 'task', message })
-            },
-        },
-        {
-            name: 'route_to_customer',
-            description: 'Route to customer agent when user mentions customers, clients, or accounts.',
-            schema: z.object({
-                message: z.string().describe('User message to forward'),
-            }),
-            func: async ({ message }) => {
-                return JSON.stringify({ agent: 'customer', message })
-            },
-        },
-        {
-            name: 'route_to_page',
-            description: 'Route to page agent when user mentions pages, content, or blocks.',
-            schema: z.object({
-                message: z.string().describe('User message to forward'),
-            }),
-            func: async ({ message }) => {
-                return JSON.stringify({ agent: 'page', message })
-            },
-        },
-        {
-            name: 'ask_clarification',
-            description: 'Ask user for clarification when intent is unclear.',
-            schema: z.object({
-                question: z.string(),
-                options: z.array(z.object({
-                    label: z.string(),
-                    description: z.string(),
-                })),
-            }),
-            func: async ({ question, options }) => {
-                return JSON.stringify({ action: 'clarify', question, options })
-            },
-        },
-    ]
-}
-```
-
-### Step 3: Orchestrator System Prompt
-
-```markdown
-<!-- agents/orchestrator.md -->
-
-You are an AI Orchestrator that routes user requests to specialized agents.
-
-## CRITICAL RULE
-
-**YOU CAN ONLY DO TWO THINGS:**
-1. Call a routing tool (route_to_task, route_to_customer, route_to_page)
-2. Respond to simple greetings
-
-**NEVER claim to perform actions like creating, updating, or deleting data.** You don't have those tools. Only the specialized agents do.
-
-## Routing Rules
-
-**route_to_customer** - Use when:
-- User mentions customers, clients, accounts (cliente, customer, cuenta)
-- User wants to modify something about a previously discussed customer
-- User references a customer from earlier ("modificalo", "cambialo")
-
-**route_to_task** - Use when:
-- User mentions tasks, to-dos, work items (tarea, task, pendiente)
-- User wants to create, update, or list tasks
-- User asks for suggestions to add to a task
-
-**route_to_page** - Use when:
-- User mentions pages, content, website (página, page, contenido)
-- User wants to create or modify landing pages, blocks
-
-## Context Awareness
-
-When the user says "modificalo", "cambialo", "actualízalo":
-- Look at the conversation history to determine WHAT they're referring to
-- If discussing a customer → route_to_customer
-- If discussing a task → route_to_task
-- If discussing a page → route_to_page
-
-## Direct Response (ONLY for greetings)
-
-Respond directly ONLY for:
-- "Hola" → "¡Hola! ¿En qué puedo ayudarte?"
-- "Hello" → "Hello! How can I help you?"
-
-For EVERYTHING else, use a routing tool.
-```
-
-### Step 4: Orchestrator Handler
-
-```typescript
-// orchestrator.ts
-import { createAgent } from '@/contents/plugins/langchain/lib/agent-factory'
-import { loadSystemPrompt } from './agents'
-import { getAgentConfig, getAgentModelConfig, getAgentTools } from './langchain.config'
-import type { RoutingResult, ClarificationResult } from './tools/orchestrator'
-
-type AgentType = 'task' | 'customer' | 'page'
-
-const AGENT_NAME_MAP: Record<AgentType, string> = {
-    task: 'task-assistant',
-    customer: 'customer-assistant',
-    page: 'page-assistant',
-}
-
-export interface OrchestratorContext {
-    userId: string
-    teamId: string
-    sessionId: string
-}
-
-export interface OrchestratorResponse {
-    content: string
-    sessionId: string
-    agentUsed?: 'orchestrator' | AgentType
-}
-
-/**
- * Extract routing decision from the LATEST turn only
- */
-function extractRoutingFromMessages(messages: any[]): RoutingResult | ClarificationResult | null {
-    // Find last human message (start of current turn)
-    let lastHumanIndex = -1
-    for (let i = messages.length - 1; i >= 0; i--) {
-        if (messages[i]._getType() === 'human') {
-            lastHumanIndex = i
-            break
-        }
-    }
-
-    // Only search for tool results AFTER the last human message
-    for (let i = messages.length - 1; i > lastHumanIndex; i--) {
-        const msg = messages[i]
-        if (msg._getType() === 'tool') {
-            const content = typeof msg.content === 'string'
-                ? msg.content
-                : JSON.stringify(msg.content)
-            try {
-                const parsed = JSON.parse(content)
-                if (parsed.action === 'clarify' || parsed.agent) {
-                    return parsed
-                }
-            } catch {
-                // Not JSON
-            }
-        }
-    }
-    return null
-}
-
-/**
- * Invoke a specialized sub-agent
- */
-async function invokeSubAgent(
-    agentType: AgentType,
-    message: string,
-    context: OrchestratorContext
-): Promise<OrchestratorResponse> {
-    const { userId, teamId, sessionId } = context
-    const agentName = AGENT_NAME_MAP[agentType]
-
-    const config = getAgentConfig(agentName)
-    if (!config?.systemPrompt) {
-        throw new Error(`Agent not found: ${agentName}`)
-    }
-
-    const agent = await createAgent({
-        sessionId: `${sessionId}-${agentType}`,
-        systemPrompt: loadSystemPrompt(config.systemPrompt as any),
-        tools: getAgentTools(agentName, { userId, teamId }),
-        modelConfig: getAgentModelConfig(agentName),
-        context: { userId, teamId },
-    })
-
-    const response = await agent.chat(message)
-
-    return {
-        content: response.content,
-        sessionId,
-        agentUsed: agentType,
-    }
-}
-
-/**
- * Process a message through the orchestrator
- */
-export async function processWithOrchestrator(
-    message: string,
-    context: OrchestratorContext
-): Promise<OrchestratorResponse> {
-    const { userId, teamId, sessionId } = context
-
-    try {
-        // Step 1: Create orchestrator
-        const orchestratorAgent = await createAgent({
-            sessionId: `${sessionId}-orchestrator`,
-            systemPrompt: loadSystemPrompt('orchestrator'),
-            tools: getAgentTools('orchestrator', { userId, teamId }),
-            modelConfig: getAgentModelConfig('orchestrator'),
-            context: { userId, teamId },
-        })
-
-        // Step 2: Get routing decision
-        const routingResponse = await orchestratorAgent.chat(message)
-
-        // Step 3: Extract routing from tool results
-        const decision = extractRoutingFromMessages(routingResponse.messages || [])
-
-        if (!decision) {
-            // Orchestrator responded directly (greeting, meta-question)
-            return {
-                content: routingResponse.content,
-                sessionId,
-                agentUsed: 'orchestrator',
-            }
-        }
-
-        // Step 4: Handle clarification
-        if ('action' in decision && decision.action === 'clarify') {
-            let response = decision.question + '\n\n'
-            decision.options.forEach((opt, i) => {
-                response += `${i + 1}. **${opt.label}**: ${opt.description}\n`
-            })
-            return {
-                content: response,
-                sessionId,
-                agentUsed: 'orchestrator',
-            }
-        }
-
-        // Step 5: Route to specialized agent
-        if ('agent' in decision) {
-            return await invokeSubAgent(
-                decision.agent,
-                decision.message || message,
-                context
-            )
-        }
-
-        return {
-            content: routingResponse.content,
-            sessionId,
-            agentUsed: 'orchestrator',
-        }
-    } catch (error) {
-        console.error('[Orchestrator] Error:', error)
-        throw new Error(
-            error instanceof Error ? error.message : 'Failed to process message'
-        )
-    }
-}
-```
-
-### Step 5: API Integration
-
-```typescript
-// api/ai/chat/route.ts
-import { NextRequest, NextResponse } from 'next/server'
-import { authenticateRequest } from '@/core/lib/auth/server'
-import { processWithOrchestrator } from '@/themes/default/lib/langchain/orchestrator'
-
-export async function POST(request: NextRequest) {
-    try {
-        const { user, teamId } = await authenticateRequest(request)
-        if (!user || !teamId) {
-            return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
-        }
-
-        const { message, sessionId } = await request.json()
-
-        const response = await processWithOrchestrator(message, {
-            userId: user.id,
-            teamId,
-            sessionId: sessionId || `session-${Date.now()}`,
-        })
-
-        return NextResponse.json(response)
-    } catch (error) {
-        return NextResponse.json(
-            { error: error instanceof Error ? error.message : 'Error' },
-            { status: 500 }
-        )
-    }
-}
-```
-
-## Session Management
-
-Orchestration creates separate sessions for each agent:
-
-```
-Main session: user-123-session-1
-├── Orchestrator: user-123-session-1-orchestrator
-├── Task Agent: user-123-session-1-task
-├── Customer Agent: user-123-session-1-customer
-└── Page Agent: user-123-session-1-page
-```
-
-This allows:
-- Independent conversation history per agent
-- Context isolation between domains
-- Parallel conversations if needed
-
-## Handling Context References
-
-A key challenge is handling contextual references like "modificalo" (modify it):
-
-### Problem
-
-```
-User: "Show me customer StartupXYZ"
-Agent: *shows customer details*
-User: "modificalo, su nuevo telefono es +1 555..."
-       ^^^^^^^^^^
-       What is "it"?
-```
-
-### Solution: Context Awareness in Prompt
-
-```markdown
-## Context Awareness
-
-When the user says "modificalo", "cambialo", "actualízalo":
-- Look at the conversation history to determine WHAT they're referring to
-- If you were just discussing a customer → route_to_customer
-- If you were just discussing a task → route_to_task
-- If you were just discussing a page → route_to_page
-```
-
-### Solution: Extracting Only Current Turn
-
-```typescript
-// Only look at messages after the last human message
-function extractRoutingFromMessages(messages) {
-    let lastHumanIndex = -1
-    for (let i = messages.length - 1; i >= 0; i--) {
-        if (messages[i]._getType() === 'human') {
-            lastHumanIndex = i
-            break
-        }
-    }
-
-    // Search only in current turn
-    for (let i = messages.length - 1; i > lastHumanIndex; i--) {
-        // Extract routing...
-    }
-}
-```
-
-## Orchestration Patterns
-
-### Pattern 1: Simple Router
-
-Route based on keywords only:
-
-```typescript
-'orchestrator': {
-    temperature: 0.1,
-    systemPrompt: 'simple-router',
-    createTools: () => [routeToTask, routeToCustomer, routeToPage],
-}
-```
-
-### Pattern 2: Intent Classifier
-
-More sophisticated intent analysis:
-
-```markdown
-## Intent Classification
-
-Before routing, classify the user's intent:
-
-1. **CRUD Operations**: Create, Read, Update, Delete
-2. **Search/Query**: Finding specific items
-3. **Aggregation**: Summaries, counts, reports
-4. **Action**: Workflows, multi-step operations
-
-Then route to the appropriate agent.
-```
-
-### Pattern 3: Hierarchical Orchestration
-
-For very complex systems:
-
-```
-Main Orchestrator
-├── Domain A Orchestrator
-│   ├── Agent A1
-│   └── Agent A2
-└── Domain B Orchestrator
-    ├── Agent B1
-    └── Agent B2
-```
-
-### Pattern 4: Fallback Chain
-
-Try agents in order:
-
-```typescript
-async function processWithFallback(message, context) {
-    try {
-        return await processWithOrchestrator(message, context)
-    } catch {
-        // Fallback to single agent
-        return await processSingleAgent(message, context)
-    }
-}
-```
-
-## Clarification Flow
-
-When intent is unclear, ask for clarification:
-
-```typescript
-{
-    name: 'ask_clarification',
-    description: 'Ask user for clarification when intent is ambiguous.',
-    schema: z.object({
-        question: z.string(),
-        options: z.array(z.object({
-            label: z.string(),
-            description: z.string(),
-        })),
-    }),
-    func: async ({ question, options }) => {
-        return JSON.stringify({
-            action: 'clarify',
-            question,
-            options,
-        })
-    },
-}
-```
-
-**Example:**
-
-```
-User: "Create a new entry"
-Orchestrator: *calls ask_clarification*
-Response:
-  "What type of entry would you like to create?"
-
-  1. **Task**: Create a new task or todo item
-  2. **Customer**: Create a new customer record
-  3. **Page**: Create a new content page
-```
-
-## Debugging Orchestration
-
-### Enable Logging
-
-```env
-LOG_ENABLED=true
-```
-
-### Check Logs
-
-```bash
-# View orchestrator decisions
-cat logger/ai/session-*-orchestrator.log
-
-# View sub-agent execution
-cat logger/ai/session-*-task.log
-cat logger/ai/session-*-customer.log
-```
-
-### Common Issues
-
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| Wrong agent selected | Unclear routing rules | Improve prompt keywords |
-| Stale routing | Using old tool results | Only check current turn |
-| Direct response instead of routing | Too permissive direct response rules | Restrict to greetings only |
-| Infinite loops | Agent calling itself | Check recursion limits |
-
-## Best Practices
-
-### 1. Keep Orchestrator Lightweight
-
-```typescript
-'orchestrator': {
-    temperature: 0.1,  // Low for consistency
-    // Only routing tools, no data tools
-    createTools: () => createOrchestratorTools(),
-}
-```
-
-### 2. Be Explicit About Routing Rules
-
-```markdown
-## Routing Rules
-
-**route_to_customer** - Use when message contains:
-- "customer", "cliente", "client"
-- "account", "cuenta"
-- "phone", "teléfono"
-- OR when referring to a previously discussed customer
-```
-
-### 3. Handle Edge Cases
-
-```markdown
-## Edge Cases
-
-- If message could match multiple agents, ask for clarification
-- If user says "undo", route to the same agent as previous action
-- If user says "help", respond directly with capability list
-```
-
-### 4. Monitor and Iterate
-
-- Track routing accuracy
-- Log misrouted requests
-- Continuously improve prompts
-
-## Next Steps
-
-- [Advanced customization](../05-reference/02-customization.md)
-- [API reference](../05-reference/01-api-reference.md)