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

package/templates/contents/plugins/langchain/docs/02-core-concepts/02-agents.md

@@ -1,597 +0,0 @@
-# Agents
-
-Agents are the core of the LangChain plugin. This guide covers how to create, configure, and customize AI agents with system prompts.
-
-## What is an Agent?
-
-An agent combines three elements:
-
-1. **LLM (Brain)**: The language model that reasons and makes decisions
-2. **Tools (Hands)**: Functions the agent can call to interact with data
-3. **System Prompt (Personality)**: Instructions that define agent behavior
-
-```
-┌─────────────────────────────────────────┐
-│                 AGENT                    │
-│                                          │
-│  ┌──────────────────────────────────┐   │
-│  │         System Prompt             │   │
-│  │   "You are a task assistant..."   │   │
-│  └──────────────────────────────────┘   │
-│                    │                     │
-│                    ▼                     │
-│  ┌──────────────────────────────────┐   │
-│  │              LLM                  │   │
-│  │         (Reasoning)               │   │
-│  └──────────────────────────────────┘   │
-│                    │                     │
-│         ┌─────────┴─────────┐           │
-│         ▼                   ▼           │
-│  ┌─────────────┐     ┌─────────────┐    │
-│  │   Tool 1    │     │   Tool 2    │    │
-│  │ list_tasks  │     │ create_task │    │
-│  └─────────────┘     └─────────────┘    │
-│                                          │
-└─────────────────────────────────────────┘
-```
-
-## Creating an Agent
-
-### Step 1: Define in Configuration
-
-```typescript
-// langchain.config.ts
-export const AGENTS = {
-    'my-assistant': {
-        provider: 'ollama',
-        temperature: 0.3,
-        description: 'Helps users manage their items',
-        systemPrompt: 'my-assistant',
-        createTools: (context) => createMyTools(context),
-    },
-}
-```
-
-### Step 2: Create System Prompt
-
-```markdown
-<!-- agents/my-assistant.md -->
-
-You are an AI assistant that helps users manage their items.
-
-## Your Capabilities
-- List, search, and view items
-- Create new items
-- Update existing items
-- Delete items (with confirmation)
-
-## Rules
-1. Always use tools to access data - never fabricate information
-2. Confirm before destructive actions
-3. Match the user's language (Spanish/English)
-
-## Response Format
-- Be concise but helpful
-- Use bullet points for lists
-- Provide links after creating/updating: [Item Name](/items/{id})
-```
-
-### Step 3: Create Tools
-
-```typescript
-// tools/my-entity.ts
-export function createMyTools(context: AgentContext): ToolDefinition[] {
-    return [
-        {
-            name: 'list_items',
-            description: 'List all items',
-            schema: z.object({}),
-            func: async () => {
-                const items = await MyService.list(context.userId)
-                return JSON.stringify(items)
-            },
-        },
-    ]
-}
-```
-
-### Step 4: Use the Agent
-
-```typescript
-import { createAgent } from '@/contents/plugins/langchain/lib/agent-factory'
-import { getAgentTools, getAgentModelConfig } from './langchain.config'
-import { loadSystemPrompt } from './agents'
-
-const agent = await createAgent({
-    sessionId: `user-${userId}-${Date.now()}`,
-    systemPrompt: loadSystemPrompt('my-assistant'),
-    tools: getAgentTools('my-assistant', { userId, teamId }),
-    modelConfig: getAgentModelConfig('my-assistant'),
-    context: { userId, teamId },
-})
-
-const response = await agent.chat('Show me my items')
-```
-
-## System Prompts
-
-System prompts define agent behavior. They are loaded from markdown files in the `agents/` folder.
-
-### Prompt Loader
-
-```typescript
-// agents/index.ts
-import fs from 'fs'
-import path from 'path'
-
-const AGENTS_DIR = path.join(__dirname)
-
-export type AgentName =
-    | 'orchestrator'
-    | 'task-assistant'
-    | 'customer-assistant'
-    | 'page-assistant'
-    | 'single-agent'
-
-const promptCache = new Map<string, string>()
-
-export function loadSystemPrompt(agentName: AgentName): string {
-    if (promptCache.has(agentName)) {
-        return promptCache.get(agentName)!
-    }
-
-    const filePath = path.join(AGENTS_DIR, `${agentName}.md`)
-    const content = fs.readFileSync(filePath, 'utf-8')
-    promptCache.set(agentName, content)
-
-    return content
-}
-
-export function agentExists(agentName: string): boolean {
-    const filePath = path.join(AGENTS_DIR, `${agentName}.md`)
-    return fs.existsSync(filePath)
-}
-```
-
-### Prompt Structure
-
-A well-structured system prompt includes:
-
-```markdown
-# Agent Name
-
-Brief description of what the agent does.
-
-## Critical Rules
-
-**Rules that MUST be followed:**
-- Rule 1: Always use tools
-- Rule 2: Never fabricate data
-- Rule 3: ...
-
-## Capabilities
-
-What this agent can do:
-- Capability 1
-- Capability 2
-- ...
-
-## Available Tools
-
-| Tool | When to Use |
-|------|-------------|
-| `tool_name` | Description of when to use |
-| `other_tool` | Description... |
-
-## Workflow
-
-How the agent should approach tasks:
-
-1. Step 1
-2. Step 2
-3. ...
-
-## Response Format
-
-Guidelines for formatting responses:
-- Use bullet points
-- Match user language
-- Provide links: [Name](/path/{id})
-
-## Examples
-
-Example interactions (optional):
-
-User: "Show me my items"
-Agent: *calls list_items* → Formats and displays results
-
-## What NOT to Do
-
-- Don't fabricate data
-- Don't skip tool calls
-- Don't ...
-```
-
-## Dynamic Prompts with Handlebars
-
-System prompts support Handlebars templates for injecting runtime data. This allows prompts to be personalized based on user context, business data, or other dynamic information.
-
-### Enabling Dynamic Prompts
-
-1. **Define `enrichContext` in your agent configuration:**
-
-```typescript
-// langchain.config.ts
-'sales-assistant': {
-    provider: 'openai',
-    systemPrompt: 'sales-assistant',  // Template file
-
-    enrichContext: async ({ userId, teamId }) => {
-        const user = await UsersService.getById(userId)
-        const team = await TeamsService.getById(teamId)
-        const quotas = await QuotasService.getForUser(userId)
-
-        return {
-            userId,
-            teamId,
-            salesperson: { name: user.name, email: user.email },
-            company: { name: team.name, timezone: team.timezone },
-            quotas,
-        }
-    },
-}
-```
-
-2. **Use Handlebars syntax in your prompt:**
-
-```markdown
-<!-- agents/sales-assistant.md -->
-
-# Sales Assistant
-
-You are helping **{{salesperson.name}}** from **{{company.name}}**.
-Current timezone: {{company.timezone}}
-
-{{#if quotas}}
-## Your quotas this month:
-{{#each quotas}}
-- {{this.name}}: {{this.current}} / {{this.target}}
-{{/each}}
-{{/if}}
-
-## Your Capabilities
-...
-```
-
-### Handlebars Syntax
-
-| Syntax | Description | Example |
-|--------|-------------|---------|
-| `{{variable}}` | Simple variable | `{{user.name}}` |
-| `{{nested.key}}` | Nested property | `{{company.timezone}}` |
-| `{{#if condition}}...{{/if}}` | Conditional | `{{#if isAdmin}}Admin mode{{/if}}` |
-| `{{#unless condition}}...{{/unless}}` | Inverse conditional | `{{#unless hasData}}No data{{/unless}}` |
-| `{{#each items}}...{{/each}}` | Loop over array | `{{#each tasks}}{{this.title}}{{/each}}` |
-| `{{#with object}}...{{/with}}` | Change context | `{{#with user}}{{name}}{{/with}}` |
-
-### Prompt Renderer
-
-The plugin provides a `renderPrompt` utility:
-
-```typescript
-import { renderPrompt } from '@/contents/plugins/langchain/lib/prompt-renderer'
-
-const template = 'Hello {{user.name}} from {{company.name}}!'
-const context = {
-    userId: '123',
-    teamId: '456',
-    user: { name: 'John' },
-    company: { name: 'Acme Corp' },
-}
-
-const rendered = renderPrompt(template, context)
-// "Hello John from Acme Corp!"
-```
-
-### Best Practices
-
-1. **Keep templates readable** - Don't overuse conditionals
-2. **Provide defaults** - Handle missing data gracefully
-3. **Document required context** - Note what data the template expects
-4. **Test with sample data** - Ensure templates render correctly
-
-## Real-World Examples
-
-### Task Assistant
-
-```markdown
-<!-- agents/task-assistant.md -->
-
-You are a task management AI assistant for the Boilerplate application.
-
-## CRITICAL RULE - MUST FOLLOW
-
-**YOU MUST ALWAYS USE TOOLS TO GET DATA. NEVER FABRICATE OR IMAGINE TASK INFORMATION.**
-
-Before responding with ANY task information, you MUST:
-1. Call the appropriate tool (list_tasks, search_tasks, get_task_details)
-2. Wait for the tool result
-3. ONLY THEN respond based on the REAL data from the tool
-
-If a tool returns an error or empty results, tell the user honestly - NEVER make up fake tasks.
-
-## Your Capabilities
-- List, search, and view tasks (using tools)
-- Create new tasks with title, description, priority, and due dates
-- Update existing tasks (status, priority, details)
-- Suggest ideas, recipes, lists, or content to ADD to tasks when asked
-
-## Handling Suggestions + Task Updates
-
-When the user asks you to "suggest X for task Y" or "add recommendations to task":
-1. First, find the task using search_tasks or get_task_details
-2. Generate your suggestions (recipes, ideas, items, etc.) using your knowledge
-3. Update the task with the suggestions using update_task
-4. Confirm what you added
-
-## Available Tools - USE THEM
-
-| Tool | When to use |
-|------|-------------|
-| **list_tasks** | User asks to see tasks, pending items, todo list |
-| **search_tasks** | User wants to find specific tasks by keyword |
-| **get_task_details** | User asks about a specific task |
-| **create_task** | User wants to create a new task |
-| **update_task** | User wants to modify an existing task |
-
-## Response Format
-- Use Spanish when the user writes in Spanish, English when they write in English
-- Be concise but helpful
-- Use bullet points for task lists
-- When a task is created or updated, provide a link: [Task Title](/dashboard/tasks/{id})
-- If no tasks found, say so honestly - don't invent them
-
-## What NOT to do
-- NEVER respond with example/fake tasks like "Task 1: Description..."
-- NEVER imagine what tasks the user might have
-- NEVER skip calling tools before responding about tasks
-```
-
-### Customer Assistant
-
-```markdown
-<!-- agents/customer-assistant.md -->
-
-You are a customer management AI assistant for the Boilerplate application.
-
-## CRITICAL RULE - MUST FOLLOW
-
-**YOU MUST ALWAYS USE TOOLS TO GET DATA. NEVER FABRICATE OR IMAGINE CUSTOMER INFORMATION.**
-
-Before responding with ANY customer information, you MUST:
-1. Call the appropriate tool (list_customers, search_customers, get_customer)
-2. Wait for the tool result
-3. ONLY THEN respond based on the REAL data from the tool
-
-## Your Capabilities
-- List, search, and view customer details (using tools)
-- Create new customers with all their information
-- Update existing customer data
-- Delete customers (with confirmation)
-
-## Customer Fields
-- **name**: Company or customer name (required)
-- **account**: Account number (required, numeric, must be unique)
-- **office**: Office location/branch (required)
-- **phone**: Contact phone number (optional)
-- **salesRep**: Assigned sales representative name (optional)
-- **visitDays**: Days for in-person visits (optional)
-- **contactDays**: Days for phone/email contact (optional)
-
-## Handling Contextual Updates
-
-When the user says "modificalo", "cambialo", "actualízalo" (modify it, change it, update it):
-1. Look at the conversation history to identify which customer they're referring to
-2. Get the customer ID from your previous search/get results
-3. Call update_customer with that ID and the new values
-4. Confirm the update with a link
-
-**Example:**
-- Previous context: You showed StartupXYZ (id: customer-002, phone: +1 512 555 0102)
-- User: "modificalo, su nuevo telefono es +1 457 45465245"
-- YOU: Call update_customer with customerId="customer-002" and phone="+1 457 45465245"
-
-## Response Format
-- Use Spanish when the user writes in Spanish, English otherwise
-- After creating or updating a customer, provide a link: [Customer Name](/dashboard/customers/{id})
-- When listing customers, summarize key info: name, office, salesRep
-- Always confirm before deleting a customer
-```
-
-### Orchestrator
-
-```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.
-
-## Your Job
-
-1. Analyze the user's message AND the conversation history
-2. Decide which agent should handle it
-3. Call the appropriate routing tool OR respond to greetings only
-
-## Routing Rules
-
-**route_to_customer** - Use when:
-- User mentions customers, clients, accounts
-- 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
-- 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
-- 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?"
-- "¿Quién eres?" → "Soy tu asistente para tareas, clientes y páginas."
-
-For EVERYTHING else, use a routing tool.
-```
-
-## Agent Patterns
-
-### Pattern 1: Single Domain Agent
-
-For simple applications with one entity type:
-
-```typescript
-'item-assistant': {
-    provider: 'ollama',
-    temperature: 0.3,
-    systemPrompt: 'item-assistant',
-    createTools: (ctx) => createItemTools(ctx),
-}
-```
-
-### Pattern 2: Unified Multi-Domain Agent
-
-For applications where one agent handles everything:
-
-```typescript
-'assistant': {
-    provider: 'ollama',
-    temperature: 0.3,
-    systemPrompt: 'unified-assistant',
-    createTools: (ctx) => [
-        ...createTaskTools(ctx),
-        ...createCustomerTools(ctx),
-        ...createPageTools(ctx),
-    ],
-}
-```
-
-### Pattern 3: Specialized Agents
-
-For complex applications with domain experts:
-
-```typescript
-const AGENTS = {
-    'task-expert': { createTools: (ctx) => createTaskTools(ctx) },
-    'customer-expert': { createTools: (ctx) => createCustomerTools(ctx) },
-    'content-expert': { createTools: (ctx) => createPageTools(ctx) },
-}
-```
-
-### Pattern 4: Hierarchical Agents
-
-Orchestrator + specialized agents:
-
-```typescript
-const AGENTS = {
-    'orchestrator': {
-        temperature: 0.1,
-        createTools: () => createRoutingTools(),
-    },
-    'task-assistant': { ... },
-    'customer-assistant': { ... },
-}
-```
-
-## Best Practices
-
-### 1. Be Explicit About Tool Usage
-
-```markdown
-## CRITICAL RULE
-You MUST use tools to get data. NEVER fabricate information.
-```
-
-### 2. Provide Examples
-
-```markdown
-## Workflow Example
-1. User: "Show me my tasks"
-2. YOU: Call list_tasks
-3. Tool returns: [{id: "1", title: "Review report"}]
-4. YOU: Format and display the real data
-```
-
-### 3. Handle Edge Cases
-
-```markdown
-## Error Handling
-- If no results found, say so honestly
-- If a tool fails, report the error to the user
-- Never make up data to fill gaps
-```
-
-### 4. Match User Language
-
-```markdown
-## Language
-- Use Spanish when the user writes in Spanish
-- Use English when the user writes in English
-```
-
-### 5. Provide Action Feedback
-
-```markdown
-## Response Format
-- After creating: [Item Name](/items/{id})
-- After updating: "Updated successfully"
-- Before deleting: "Are you sure?"
-```
-
-## Debugging Prompts
-
-Enable logging to see how the agent interprets prompts:
-
-```env
-LOG_ENABLED=true
-```
-
-Check logs in `logger/ai/session-{id}.log`:
-
-```
-[SESSION_INIT] { model: "qwen2.5:7b", toolsCount: 5 }
-[USER_MESSAGE] { message: "Show me my tasks" }
-[AGENT_RESPONSE] {
-  messages: [
-    { type: "human", content: "Show me my tasks" },
-    { type: "ai", content: "", tool_calls: [{ name: "list_tasks" }] },
-    { type: "tool", content: "[{...}]" },
-    { type: "ai", content: "Here are your tasks:..." }
-  ]
-}
-```
-
-## Next Steps
-
-- [Build tools for your agents](./03-tools.md)
-- [Set up graph orchestration](../03-orchestration/01-graph-orchestrator.md) (recommended)
-- [Configure observability](../04-advanced/01-observability.md)