@nextsparkjs/plugin-langchain 0.1.0-beta.1

package/docs/02-core-concepts/02-agents.md

@@ -0,0 +1,597 @@
+# 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)