@runflow-ai/sdk 1.0.24 → 1.0.27

package/README.md

@@ -1,76 +1,111 @@
-# 🚀 Runflow SDK V2
+# 🚀 Runflow SDK
 
-> **Framework Multi-Agent de IA para construir agentes inteligentes com TypeScript**
+> **A powerful TypeScript-first framework for building intelligent AI agents and multi-agent systems**
 
-O Runflow SDK V2 é um framework completo e type-safe para construir agentes de IA, workflows complexos e sistemas multi-agent. Projetado para ser simples de usar, mas poderoso o suficiente para casos de uso avançados.
+Runflow SDK is a comprehensive, type-safe framework for building AI agents, complex workflows, and multi-agent systems. Designed to be simple to use yet powerful enough for advanced use cases.
 
-[![npm version](https://img.shields.io/npm/v/@runflow-ai/sdk)](https://www.npmjs.com/package/@runflow-ai/sdk)
+[![npm version](https://img.shields.io/npm/v/@runflow-ai/sdk.svg)](https://www.npmjs.com/package/@runflow-ai/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## 📑 Índice
-
-- [Instalação](#-instalação)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.0.0-green.svg)](https://nodejs.org/)
+
+## ✨ Features
+
+- 🤖 **Intelligent Agents** - Create agents with LLM, tools, memory, and RAG capabilities
+- 🔧 **Type-Safe Tools** - Build custom tools with Zod schema validation
+- 🔌 **Built-in Connectors** - HubSpot, Twilio, Email, Slack integrations out of the box
+- 🌊 **Workflows** - Orchestrate complex multi-step processes with conditional logic
+- 🧠 **Memory Management** - Persistent conversation history with automatic summarization
+- 📚 **Agentic RAG** - LLM-driven semantic search in vector knowledge bases
+- 👥 **Multi-Agent Systems** - Supervisor pattern with automatic agent routing
+- 🔍 **Full Observability** - Automatic tracing with cost tracking and performance metrics
+- 📡 **Streaming Support** - Real-time streaming responses with memory persistence
+- 🎨 **Multi-Modal** - Support for text and images (vision models)
+- 🔄 **Multiple Providers** - OpenAI, Anthropic (Claude), and AWS Bedrock
+
+## 📑 Table of Contents
+
+- [Installation](#-installation)
 - [Quick Start](#-quick-start)
-- [Conceitos Fundamentais](#-conceitos-fundamentais)
+- [Core Concepts](#-core-concepts)
   - [Agents](#agents)
-  - [Context Management](#context-management-runflow)
+  - [Context Management](#context-management)
   - [Memory](#memory)
   - [Tools](#tools)
   - [Connectors](#connectors)
   - [Workflows](#workflows)
-  - [RAG/Knowledge](#ragknowledge)
+  - [Knowledge (RAG)](#knowledge-rag)
   - [LLM Standalone](#llm-standalone)
   - [Observability](#observability)
-- [Arquitetura](#-arquitetura)
-- [Exemplos Avançados](#-exemplos-avançados)
-- [Configuração](#-configuração)
+- [Advanced Examples](#-advanced-examples)
+- [Real-World Use Cases](#-real-world-use-cases)
+  - [Customer Support Agent with RAG](#1-customer-support-agent-with-rag)
+  - [Sales Automation with Multi-Step Workflow](#2-sales-automation-with-multi-step-workflow)
+  - [Intelligent Collections Agent (WhatsApp)](#3-intelligent-collections-agent-whatsapp)
+  - [Customer Onboarding Assistant](#4-customer-onboarding-assistant)
+  - [Feedback Analysis System](#5-feedback-analysis-system)
+  - [Multi-Agent System (Supervisor Pattern)](#6-multi-agent-system-supervisor-pattern)
+- [Configuration](#-configuration)
 - [API Reference](#-api-reference)
+- [TypeScript Types](#-typescript-types)
 - [Providers](#-providers)
-- [Contribuindo](#-contribuindo)
+- [Troubleshooting](#-troubleshooting)
+- [Contributing](#-contributing)
+- [License](#-license)
 
 ---
 
-## 📦 Instalação
+## 📦 Installation
 
 ```bash
 npm install @runflow-ai/sdk
-# ou
+# or
 yarn add @runflow-ai/sdk
+# or
+pnpm add @runflow-ai/sdk
 ```
 
-### Requisitos
+### Requirements
 
 - **Node.js**: >= 22.0.0
-- **TypeScript**: >= 5.0.0 (recomendado)
-- **Zod**: ^3.22.0 (já incluído como dependência)
+- **TypeScript**: >= 5.0.0 (recommended)
+- **Zod**: ^3.22.0 (included as dependency)
 
 ---
 
 ## 🚀 Quick Start
 
-### Agent Simples
+> **Note on Parameters:**
+> - `message` is **required** (the user's message)
+> - `companyId` is **optional** (for multi-tenant applications - your end-user's company ID)
+> - `sessionId` is **optional** but recommended (maintains conversation history)
+> - `userId` is **optional** (for user identification)
+> - All other fields are optional and can be set via `Runflow.identify()` or environment variables
+
+### Simple Agent
 
 ```typescript
 import { Agent, openai } from '@runflow-ai/sdk';
 
-// Criar agent básico
+// Create a basic agent
 const agent = new Agent({
   name: 'Support Agent',
   instructions: 'You are a helpful customer support assistant.',
   model: openai('gpt-4o'),
 });
 
-// Processar mensagem
+// Process a message
 const result = await agent.process({
-  message: 'I need help with my order',
-  companyId: 'company_123',
-  sessionId: 'session_456',
+  message: 'I need help with my order',  // Required
+  sessionId: 'session_456',              // Optional: For conversation history
+  userId: 'user_789',                    // Optional: User identifier
+  companyId: 'company_123',              // Optional: For multi-tenant apps
 });
 
 console.log(result.message);
 ```
 
-### Agent com Memory
+### Agent with Memory
 
 ```typescript
 import { Agent, openai } from '@runflow-ai/sdk';
@@ -80,35 +115,32 @@ const agent = new Agent({
   instructions: 'You are a helpful assistant with memory.',
   model: openai('gpt-4o'),
   memory: {
-    type: 'conversation',
     maxTurns: 10,
   },
 });
 
-// Primeira interação
+// First interaction
 await agent.process({
   message: 'My name is John',
-  companyId: 'company_123',
-  sessionId: 'session_456',
+  sessionId: 'session_456',  // Same session for conversation continuity
 });
 
-// Segunda interação - agent lembra o nome
+// Second interaction - agent remembers the name
 const result = await agent.process({
   message: 'What is my name?',
-  companyId: 'company_123',
-  sessionId: 'session_456',
+  sessionId: 'session_456',  // Same session
 });
 
 console.log(result.message); // "Your name is John"
 ```
 
-### Agent com Tools
+### Agent with Tools
 
 ```typescript
 import { Agent, openai, createTool } from '@runflow-ai/sdk';
 import { z } from 'zod';
 
-// Criar tool customizada
+// Create a custom tool
 const weatherTool = createTool({
   id: 'get-weather',
   description: 'Get current weather for a location',
@@ -116,7 +148,7 @@ const weatherTool = createTool({
     location: z.string(),
   }),
   execute: async ({ context }) => {
-    // Simular busca de clima
+    // Fetch weather data
     return {
       temperature: 22,
       condition: 'Sunny',
@@ -125,7 +157,7 @@ const weatherTool = createTool({
   },
 });
 
-// Agent com tool
+// Create agent with tool
 const agent = new Agent({
   name: 'Weather Agent',
   instructions: 'You help users check the weather.',
@@ -137,28 +169,54 @@ const agent = new Agent({
 
 const result = await agent.process({
   message: 'What is the weather in São Paulo?',
-  companyId: 'company_123',
 });
 
 console.log(result.message);
 ```
 
+### Agent with RAG (Knowledge Base)
+
+```typescript
+import { Agent, openai } from '@runflow-ai/sdk';
+
+const agent = new Agent({
+  name: 'Support Agent',
+  instructions: 'You are a helpful support agent.',
+  model: openai('gpt-4o'),
+  rag: {
+    vectorStore: 'support-docs',
+    k: 5,
+    threshold: 0.7,
+    searchPrompt: `Use searchKnowledge tool when user asks about:
+- Technical problems
+- Process questions
+- Specific information`,
+  },
+});
+
+// Agent automatically has 'searchKnowledge' tool
+// LLM decides when to use it (not always searching - more efficient!)
+const result = await agent.process({
+  message: 'How do I reset my password?',
+});
+```
+
 ---
 
-## 🎯 Conceitos Fundamentais
+## 🎯 Core Concepts
 
 ### Agents
 
-Os **Agents** são a unidade fundamental do Runflow SDK. Cada agent é configurado com:
+**Agents** are the fundamental building blocks of the Runflow SDK. Each agent is configured with:
 
-- **Name**: Identificador do agent
-- **Instructions**: Instruções de comportamento (system prompt)
-- **Model**: Modelo LLM a ser utilizado (OpenAI, Anthropic, Bedrock)
-- **Tools**: Ferramentas disponíveis para o agent
-- **Memory**: Configuração de memória
-- **RAG**: Configuração de busca em base de conhecimento
+- **Name**: Agent identifier
+- **Instructions**: Behavior instructions (system prompt)
+- **Model**: LLM model to use (OpenAI, Anthropic, Bedrock)
+- **Tools**: Available tools for the agent
+- **Memory**: Memory configuration
+- **RAG**: Knowledge base search configuration
 
-#### Configuração Completa de Agent
+#### Complete Agent Configuration
 
 ```typescript
 import { Agent, anthropic } from '@runflow-ai/sdk';
@@ -169,46 +227,55 @@ const agent = new Agent({
     - Always be polite and helpful
     - Solve problems efficiently
     - Use tools when needed`,
-  
-  // Modelo
+
+  // Model
   model: anthropic('claude-3-5-sonnet-20241022'),
-  
-  // Configuração do modelo
+
+  // Model configuration
   modelConfig: {
     temperature: 0.7,
     maxTokens: 4000,
     topP: 0.9,
+    frequencyPenalty: 0,
+    presencePenalty: 0,
   },
-  
-  // Memória
+
+  // Memory
   memory: {
-    type: 'conversation',
     maxTurns: 20,
     summarizeAfter: 50,
+    summarizePrompt: 'Create a concise summary highlighting key points and decisions',
+    summarizeModel: openai('gpt-4o-mini'), // Cheaper model for summaries
   },
-  
-  // RAG
+
+  // RAG (Agentic - LLM decides when to search)
   rag: {
     vectorStore: 'support-docs',
-    autoSearch: true,
     k: 5,
     threshold: 0.7,
+    searchPrompt: 'Use for technical questions',
   },
-  
+
   // Tools
   tools: {
     createTicket: ticketTool,
     searchOrders: orderTool,
   },
-  
+
+  // Tool iteration limit
+  maxToolIterations: 10,
+
   // Streaming
   streaming: {
     enabled: true,
   },
+
+  // Debug mode
+  debug: true,
 });
 ```
 
-#### Modelos Suportados
+#### Supported Models
 
 ```typescript
 import { openai, anthropic, bedrock } from '@runflow-ai/sdk';
@@ -216,54 +283,128 @@ import { openai, anthropic, bedrock } from '@runflow-ai/sdk';
 // OpenAI
 const gpt4 = openai('gpt-4o');
 const gpt4mini = openai('gpt-4o-mini');
+const gpt4turbo = openai('gpt-4-turbo');
 const gpt35 = openai('gpt-3.5-turbo');
 
-// Anthropic
+// Anthropic (Claude)
 const claude35 = anthropic('claude-3-5-sonnet-20241022');
-const claude3 = anthropic('claude-3-sonnet-20240229');
+const claude3opus = anthropic('claude-3-opus-20240229');
+const claude3sonnet = anthropic('claude-3-sonnet-20240229');
+const claude3haiku = anthropic('claude-3-haiku-20240307');
 
 // AWS Bedrock
 const claudeBedrock = bedrock('anthropic.claude-3-sonnet-20240229-v1:0');
 const titan = bedrock('amazon.titan-text-express-v1');
 ```
 
-### Context Management (Runflow)
+#### Agent Methods
+
+```typescript
+// Process a message
+const result = await agent.process(input: AgentInput): Promise<AgentOutput>;
+
+// Stream a message
+const stream = await agent.processStream(input: AgentInput): AsyncIterable<ChunkType>;
+
+// Simple generation (without full agent context)
+const response = await agent.generate(input: string | Message[]): Promise<{ text: string }>;
+
+// Streaming generation
+const stream = await agent.generateStream(prompt: string): AsyncIterable<ChunkType>;
+
+// Generation with tools
+const response = await agent.generateWithTools(input): Promise<{ text: string }>;
+```
+
+#### Multi-Agent Systems (Supervisor Pattern)
+
+```typescript
+const supervisor = new Agent({
+  name: 'Supervisor',
+  instructions: 'Route tasks to appropriate agents.',
+  model: openai('gpt-4o'),
+  agents: {
+    support: {
+      name: 'Support Agent',
+      instructions: 'Handle support requests.',
+      model: openai('gpt-4o-mini'),
+    },
+    sales: {
+      name: 'Sales Agent',
+      instructions: 'Handle sales inquiries.',
+      model: openai('gpt-4o-mini'),
+    },
+  },
+});
+
+// Supervisor automatically routes to the appropriate agent
+await supervisor.process({
+  message: 'I want to buy your product',
+  sessionId: 'session_123',
+});
+```
+
+#### Debug Mode
+
+```typescript
+const agent = new Agent({
+  name: 'Debug Agent',
+  instructions: 'Help users',
+  model: openai('gpt-4o'),
+
+  // Simple debug (all logs enabled)
+  debug: true,
+
+  // Or detailed debug configuration
+  debug: {
+    enabled: true,
+    logMessages: true,      // Log messages
+    logLLMCalls: true,      // Log LLM API calls
+    logToolCalls: true,     // Log tool executions
+    logRAG: true,           // Log RAG searches
+    logMemory: true,        // Log memory operations
+    truncateAt: 1000,       // Truncate logs at N characters
+  },
+});
+```
+
+---
+
+### Context Management
 
-O **Runflow Context** é um singleton global que gerencia informações de execução e identificação de usuários. Ele permite que você identifique uma vez e todos os agents/workflows usem automaticamente.
+The **Runflow Context** is a global singleton that manages execution information and user identification. It allows you to identify once and all agents/workflows automatically use this context.
 
-#### Uso Básico
+#### Basic Usage
 
 ```typescript
 import { Runflow, Agent, openai } from '@runflow-ai/sdk';
 
-// Identificar usuário por telefone (WhatsApp)
+// Identify user by phone (WhatsApp)
 Runflow.identify({
   type: 'phone',
   value: '+5511999999999',
 });
 
-// Agent usa automaticamente o context
+// Agent automatically uses the context
 const agent = new Agent({
   name: 'WhatsApp Bot',
   instructions: 'You are a helpful assistant.',
   model: openai('gpt-4o'),
   memory: {
-    type: 'conversation',
     maxTurns: 10,
   },
 });
 
-// Memória é automaticamente vinculada ao telefone
+// Memory is automatically bound to the phone number
 await agent.process({
   message: 'Hello!',
-  companyId: 'company_123',
 });
 ```
 
-#### Tipos de Identificação
+#### Identification Types
 
 ```typescript
-// WhatsApp/SMS (por telefone)
+// WhatsApp/SMS (by phone)
 Runflow.identify({
   type: 'phone',
   value: '+5511999999999',
@@ -282,14 +423,14 @@ Runflow.identify({
   userId: 'user@example.com',
 });
 
-// Custom (pedido, ticket, etc)
+// Custom (order, ticket, etc)
 Runflow.identify({
   type: 'order',
   value: 'order_456',
   userId: 'customer_789',
 });
 
-// Com threadId customizado
+// With custom threadId
 Runflow.identify({
   type: 'phone',
   value: '+5511999999999',
@@ -300,10 +441,14 @@ Runflow.identify({
 #### State Management
 
 ```typescript
-// Get estado completo
+// Get complete state
 const state = Runflow.getState();
 
-// Set estado customizado (avançado)
+// Get specific value
+const threadId = Runflow.get('threadId');
+const entityType = Runflow.get('entityType');
+
+// Set custom state (advanced)
 Runflow.setState({
   entityType: 'custom',
   entityValue: 'xyz',
@@ -312,15 +457,17 @@ Runflow.setState({
   metadata: { custom: 'data' },
 });
 
-// Limpar estado (útil para testes)
+// Clear state (useful for testing)
 Runflow.clearState();
 ```
 
+---
+
 ### Memory
 
-O sistema de **Memory** gerencia o histórico de conversação de forma inteligente.
+The **Memory** system intelligently manages conversation history.
 
-#### Memory Integrada no Agent
+#### Memory Integrated in Agent
 
 ```typescript
 const agent = new Agent({
@@ -328,91 +475,140 @@ const agent = new Agent({
   instructions: 'You remember everything.',
   model: openai('gpt-4o'),
   memory: {
-    type: 'conversation',
-    maxTurns: 20,           // Limitar turnos
-    maxTokens: 4000,        // Limitar tokens
-    summarizeAfter: 50,     // Resumir após N turnos
+    maxTurns: 20,           // Limit turns
+    maxTokens: 4000,        // Limit tokens
+    summarizeAfter: 50,     // Summarize after N turns
+    summarizePrompt: 'Create a concise summary with key facts and action items',
+    summarizeModel: openai('gpt-4o-mini'), // Cheaper model for summaries
   },
 });
 ```
 
-#### Memory Standalone
+#### Standalone Memory Manager
 
 ```typescript
 import { Memory } from '@runflow-ai/sdk';
 
-// Criar memory manager
-const memory = new Memory({
-  sessionId: 'session_123',
-  maxTurns: 10,
-});
-
-// Append mensagens
-await memory.append({
+// Using static methods (most common - 99% of cases)
+await Memory.append({
   role: 'user',
   content: 'Hello!',
   timestamp: new Date(),
 });
 
-await memory.append({
+await Memory.append({
   role: 'assistant',
   content: 'Hi! How can I help you?',
   timestamp: new Date(),
 });
 
-// Get histórico formatado
-const history = await memory.getFormatted();
+// Get formatted history
+const history = await Memory.getFormatted();
 console.log(history);
 
-// Get mensagens recentes
-const recent = await memory.getRecent(5); // Últimos 5 turnos
+// Get recent messages
+const recent = await Memory.getRecent(5); // Last 5 turns
 
-// Buscar na memória
-const results = await memory.search('order');
+// Search in memory
+const results = await Memory.search('order');
 
-// Limpar memória
-await memory.clear();
+// Check if memory exists
+const exists = await Memory.exists();
+
+// Get full memory data
+const data = await Memory.get();
+
+// Clear memory
+await Memory.clear();
 ```
 
-#### Memory com Runflow Context
+#### Memory with Runflow Context
 
 ```typescript
 import { Runflow, Memory } from '@runflow-ai/sdk';
 
-// Identificar usuário
+// Identify user
 Runflow.identify({
   type: 'phone',
   value: '+5511999999999',
 });
 
-// Memory usa automaticamente o context
-const memory = new Memory({
-  maxTurns: 10,
-});
-
-// Memória é vinculada ao telefone automaticamente
-await memory.append({
+// Memory automatically uses the context
+await Memory.append({
   role: 'user',
   content: 'My order number is 12345',
   timestamp: new Date(),
 });
+
+// Memory is automatically bound to the phone number
 ```
 
 #### Custom Memory Key
 
 ```typescript
-// Override completo do memoryKey
+// Create memory with custom key
 const memory = new Memory({
   memoryKey: 'custom_key_123',
   maxTurns: 10,
 });
+
+// Now use instance methods
+await memory.append({ role: 'user', content: 'Hello', timestamp: new Date() });
+const history = await memory.getFormatted();
+```
+
+#### Cross-Session Access
+
+```typescript
+// Access memory from different sessions (admin, analytics, etc)
+const dataUser1 = await Memory.get('phone:+5511999999999');
+const dataUser2 = await Memory.get('email:user@example.com');
+
+// Search across multiple sessions
+const results = await Promise.all([
+  Memory.search('bug', 'user:123'),
+  Memory.search('bug', 'user:456'),
+  Memory.search('bug', 'user:789'),
+]);
+
+// Get recent from specific session
+const recent = await Memory.getRecent(5, 'session:abc123');
+
+// Clear specific session
+await Memory.clear('phone:+5511999999999');
+```
+
+#### Custom Summarization
+
+```typescript
+// Agent with custom summarization
+const agent = new Agent({
+  name: 'Smart Agent',
+  model: openai('gpt-4o'),
+  memory: {
+    summarizeAfter: 30,
+    summarizePrompt: `Summarize in 3 bullet points:
+- Main issue discussed
+- Solution provided
+- Next steps`,
+    summarizeModel: anthropic('claude-3-haiku'), // Fast & cheap
+  },
+});
+
+// Manual summarization with custom prompt
+const summary = await Memory.summarize({
+  prompt: 'Extract only the key decisions from this conversation',
+  model: openai('gpt-4o-mini'),
+});
 ```
 
+---
+
 ### Tools
 
-**Tools** são funções que os agents podem chamar para executar ações específicas. O SDK usa Zod para validação type-safe.
+**Tools** are functions that agents can call to perform specific actions. The SDK uses Zod for type-safe validation.
 
-#### Criar Tool Básica
+#### Create Basic Tool
 
 ```typescript
 import { createTool } from '@runflow-ai/sdk';
@@ -429,10 +625,10 @@ const weatherTool = createTool({
     temperature: z.number(),
     condition: z.string(),
   }),
-  execute: async ({ context, runflow }) => {
-    // Implementar lógica
+  execute: async ({ context, runflow, projectId }) => {
+    // Implement logic
     const weather = await fetchWeather(context.location);
-    
+
     return {
       temperature: weather.temp,
       condition: weather.condition,
@@ -441,7 +637,7 @@ const weatherTool = createTool({
 });
 ```
 
-#### Tool com Runflow API
+#### Tool with Runflow API
 
 ```typescript
 const searchDocsTool = createTool({
@@ -451,12 +647,12 @@ const searchDocsTool = createTool({
     query: z.string(),
   }),
   execute: async ({ context, runflow }) => {
-    // Usar Runflow API
+    // Use Runflow API for vector search
     const results = await runflow.vectorSearch(context.query, {
       vectorStore: 'docs',
       k: 5,
     });
-    
+
     return {
       results: results.results.map(r => r.content),
     };
@@ -464,7 +660,7 @@ const searchDocsTool = createTool({
 });
 ```
 
-#### Tool com Connector
+#### Tool with Connector
 
 ```typescript
 const createTicketTool = createTool({
@@ -476,7 +672,7 @@ const createTicketTool = createTool({
     priority: z.enum(['low', 'medium', 'high']),
   }),
   execute: async ({ context, runflow }) => {
-    // Usar connector
+    // Use connector
     const ticket = await runflow.connector(
       'hubspot',
       'tickets',
@@ -487,22 +683,31 @@ const createTicketTool = createTool({
         priority: context.priority,
       }
     );
-    
+
     return { ticketId: ticket.id };
   },
 });
 ```
 
+#### Tool Execution Context
+
+The `execute` function receives:
+- `context`: Validated input parameters (from `inputSchema`)
+- `runflow`: Runflow API client for vector search, connectors, memory
+- `projectId`: Current project ID
+
+---
+
 ### Connectors
 
-**Connectors** são integrações pré-configuradas com serviços externos (HubSpot, Twilio, Email, Slack).
+**Connectors** are pre-configured integrations with external services (HubSpot, Twilio, Email, Slack).
 
-#### Criar Connector Tool
+#### Create Connector Tool
 
 ```typescript
 import { createConnectorTool } from '@runflow-ai/sdk';
 
-// HubSpot - Criar contato
+// HubSpot - Create contact
 const createContact = createConnectorTool(
   'hubspot',
   'contacts',
@@ -516,7 +721,7 @@ const createContact = createConnectorTool(
   }
 );
 
-// Twilio - Enviar WhatsApp
+// Twilio - Send WhatsApp
 const sendWhatsApp = createConnectorTool(
   'twilio',
   'messages',
@@ -528,7 +733,7 @@ const sendWhatsApp = createConnectorTool(
   }
 );
 
-// Email - Enviar email
+// Email - Send email
 const sendEmail = createConnectorTool(
   'email',
   'messages',
@@ -540,9 +745,22 @@ const sendEmail = createConnectorTool(
     html: 'boolean?',
   }
 );
+
+// Slack - Send message
+const sendSlack = createConnectorTool(
+  'slack',
+  'messages',
+  'send',
+  {
+    channel: 'string',
+    message: 'string',
+    username: 'string?',
+    iconEmoji: 'string?',
+  }
+);
 ```
 
-#### Usar Built-in Shortcuts
+#### Use Built-in Shortcuts
 
 ```typescript
 import { hubspot, twilio, email, slack } from '@runflow-ai/sdk';
@@ -552,52 +770,58 @@ const agent = new Agent({
   instructions: 'You help customers.',
   model: openai('gpt-4o'),
   tools: {
+    // Built-in connector shortcuts
     createContact: hubspot.createContact(),
+    getContact: hubspot.getContact(),
+    createTicket: hubspot.createTicket(),
     sendWhatsApp: twilio.sendWhatsApp(),
+    sendSMS: twilio.sendSMS(),
     sendEmail: email.send(),
     sendSlack: slack.sendMessage(),
   },
 });
 ```
 
-#### Tipos de Parâmetros
+#### Parameter Types
 
 ```typescript
 const tool = createConnectorTool('service', 'resource', 'action', {
-  // Tipos básicos
+  // Basic types
   name: 'string',
   age: 'number',
   active: 'boolean',
-  
-  // Opcionais
+  createdAt: 'date',
+
+  // Optional (append ?)
   nickname: 'string?',
   score: 'number?',
-  
-  // Validações especiais
+
+  // Special validations
   email: 'email',
   website: 'url',
-  birthday: 'date',
-  
+
   // Enum
   priority: { enum: ['low', 'medium', 'high'] },
-  
+
   // Arrays
   tags: { array: 'string' },
   scores: { array: 'number' },
 });
 ```
 
+---
+
 ### Workflows
 
-**Workflows** orquestram múltiplos agents, functions e connectors em sequência.
+**Workflows** orchestrate multiple agents, functions, and connectors in sequence.
 
-#### Workflow Básico
+#### Basic Workflow
 
 ```typescript
 import { createWorkflow, Agent, openai } from '@runflow-ai/sdk';
 import { z } from 'zod';
 
-// Definir schema de entrada/saída
+// Define input/output schemas
 const inputSchema = z.object({
   customerEmail: z.string().email(),
   issueDescription: z.string(),
@@ -609,7 +833,7 @@ const outputSchema = z.object({
   emailSent: z.boolean(),
 });
 
-// Criar agents
+// Create agents
 const analyzerAgent = new Agent({
   name: 'Issue Analyzer',
   instructions: 'Analyze customer issues and categorize them.',
@@ -622,7 +846,7 @@ const responderAgent = new Agent({
   model: openai('gpt-4o'),
 });
 
-// Criar workflow
+// Create workflow
 const workflow = createWorkflow({
   id: 'support-workflow',
   name: 'Support Ticket Workflow',
@@ -647,7 +871,7 @@ const workflow = createWorkflow({
   })
   .build();
 
-// Executar workflow
+// Execute workflow
 const result = await workflow.execute({
   customerEmail: 'customer@example.com',
   issueDescription: 'My order has not arrived',
@@ -656,7 +880,7 @@ const result = await workflow.execute({
 console.log(result);
 ```
 
-#### Workflow com Parallel Steps
+#### Workflow with Parallel Steps
 
 ```typescript
 const workflow = createWorkflow({
@@ -669,7 +893,7 @@ const workflow = createWorkflow({
     createAgentStep('agent2', agent2),
     createAgentStep('agent3', agent3),
   ], {
-    waitForAll: true, // Aguardar todos completarem
+    waitForAll: true, // Wait for all to complete
   })
   .function('merge', async (input, context) => {
     // Merge results
@@ -680,7 +904,7 @@ const workflow = createWorkflow({
   .build();
 ```
 
-#### Workflow com Conditional Steps
+#### Workflow with Conditional Steps
 
 ```typescript
 const workflow = createWorkflow({
@@ -707,7 +931,7 @@ const workflow = createWorkflow({
   .build();
 ```
 
-#### Workflow com Retry
+#### Workflow with Retry
 
 ```typescript
 const workflow = createWorkflow({
@@ -726,7 +950,7 @@ const workflow = createWorkflow({
     },
     retryConfig: {
       maxAttempts: 3,
-      backoff: 'exponential',
+      backoff: 'exponential', // 'fixed', 'exponential', 'linear'
       delay: 1000,
       retryableErrors: ['timeout', 'network'],
     },
@@ -734,11 +958,43 @@ const workflow = createWorkflow({
   .build();
 ```
 
-### RAG/Knowledge
+#### Workflow Step Types
+
+```typescript
+import {
+  createAgentStep,
+  createFunctionStep,
+  createConnectorStep
+} from '@runflow-ai/sdk';
+
+// Agent step
+const agentStep = createAgentStep('step-id', agent, {
+  promptTemplate: 'Process: {{input.data}}',
+});
+
+// Function step
+const functionStep = createFunctionStep('step-id', async (input, context) => {
+  // Custom logic
+  return { result: 'processed' };
+});
+
+// Connector step
+const connectorStep = createConnectorStep(
+  'step-id',
+  'hubspot',
+  'contacts',
+  'create',
+  { email: '{{input.email}}' }
+);
+```
+
+---
+
+### Knowledge (RAG)
 
-O módulo **Knowledge** (também chamado de RAG) gerencia busca semântica em bases de conhecimento.
+The **Knowledge** module (also called RAG) manages semantic search in vector knowledge bases.
 
-#### Knowledge Standalone
+#### Standalone Knowledge Manager
 
 ```typescript
 import { Knowledge } from '@runflow-ai/sdk';
@@ -749,7 +1005,7 @@ const knowledge = new Knowledge({
   threshold: 0.7,
 });
 
-// Busca básica
+// Basic search
 const results = await knowledge.search('How to reset password?');
 
 results.forEach(result => {
@@ -757,7 +1013,7 @@ results.forEach(result => {
   console.log('Score:', result.score);
 });
 
-// Get context formatado para LLM
+// Get formatted context for LLM
 const context = await knowledge.getContext('password reset', { k: 3 });
 console.log(context);
 ```
@@ -788,7 +1044,9 @@ const results = await knowledge.multiQuery(
 );
 ```
 
-#### Knowledge no Agent (Agentic RAG)
+#### Agentic RAG in Agent
+
+When RAG is configured in an agent, the SDK automatically creates a `searchKnowledge` tool that the LLM can decide when to use. This is more efficient than always searching, as the LLM only searches when necessary.
 
 ```typescript
 const agent = new Agent({
@@ -799,49 +1057,80 @@ const agent = new Agent({
     vectorStore: 'support-docs',
     k: 5,
     threshold: 0.7,
-    
-    // Prompt customizável - orienta quando buscar
+
+    // Custom search prompt - guides when to search
     searchPrompt: `Use searchKnowledge tool when user asks about:
 - Technical problems
 - Process questions
 - Specific information
 
 Don't use for greetings or casual chat.`,
-    
+
     toolDescription: 'Search in support documentation for solutions',
   },
 });
 
-// Agent tem tool 'searchKnowledge' gerada automaticamente
-// LLM decide quando buscar (não busca sempre - mais eficiente!)
+// Agent automatically has 'searchKnowledge' tool
+// LLM decides when to search (not always - more efficient!)
 const result = await agent.process({
   message: 'How do I reset my password?',
-  companyId: 'company_123',
 });
 ```
 
+#### Multiple Vector Stores
+
+```typescript
+const agent = new Agent({
+  name: 'Advanced Support Agent',
+  instructions: 'Help users with multiple knowledge bases.',
+  model: openai('gpt-4o'),
+  rag: {
+    vectorStores: [
+      {
+        id: 'support-docs',
+        name: 'Support Documentation',
+        description: 'General support articles',
+        threshold: 0.7,
+        k: 5,
+        searchPrompt: 'Use search_support-docs when user has technical problems or questions',
+      },
+      {
+        id: 'api-docs',
+        name: 'API Documentation',
+        description: 'Technical API reference',
+        threshold: 0.8,
+        k: 3,
+        searchPrompt: 'Use search_api-docs when user asks about API endpoints or integration',
+      },
+    ],
+  },
+});
+```
+
+---
+
 ### LLM Standalone
 
-O módulo **LLM** permite usar modelos de linguagem diretamente, sem criar agents.
+The **LLM** module allows you to use language models directly without creating agents.
 
-#### Uso Básico
+#### Basic Usage
 
 ```typescript
 import { LLM } from '@runflow-ai/sdk';
 
-// Criar LLM
+// Create LLM
 const llm = LLM.openai('gpt-4o', {
   temperature: 0.7,
   maxTokens: 2000,
 });
 
-// Gerar resposta
+// Generate response
 const response = await llm.generate('What is the capital of Brazil?');
 console.log(response.text);
 console.log('Tokens:', response.usage);
 ```
 
-#### Com Mensagens
+#### With Messages
 
 ```typescript
 const response = await llm.generate([
@@ -850,7 +1139,7 @@ const response = await llm.generate([
 ]);
 ```
 
-#### Com System Prompt
+#### With System Prompt
 
 ```typescript
 const response = await llm.generate(
@@ -882,7 +1171,7 @@ import { LLM } from '@runflow-ai/sdk';
 // OpenAI
 const gpt4 = LLM.openai('gpt-4o', { temperature: 0.7 });
 
-// Anthropic
+// Anthropic (Claude)
 const claude = LLM.anthropic('claude-3-5-sonnet-20241022', {
   temperature: 0.9,
   maxTokens: 4000,
@@ -894,39 +1183,42 @@ const bedrock = LLM.bedrock('anthropic.claude-3-sonnet-20240229-v1:0', {
 });
 ```
 
+---
+
 ### Observability
 
-O sistema de **Observability** coleta traces automáticos de execuções para análise e debugging.
+The **Observability** system automatically collects execution traces for analysis and debugging.
 
-#### Trace Automático (Agent)
+#### Automatic Tracing (Agent)
 
 ```typescript
-// Traces são coletados automaticamente
+// Traces are collected automatically
 const agent = new Agent({
   name: 'Support Agent',
   instructions: 'Help customers.',
   model: openai('gpt-4o'),
 });
 
-// Cada execução gera traces automaticamente
+// Each execution automatically generates traces
 await agent.process({
   message: 'Help me',
-  companyId: 'company_123',
-  sessionId: 'session_456',
-  executionId: 'exec_123', // Opcional
-  threadId: 'thread_789', // Opcional
+  companyId: 'company_123',   // Optional
+  sessionId: 'session_456',   // Optional
+  executionId: 'exec_123',    // Optional
+  threadId: 'thread_789',     // Optional
 });
 ```
 
-#### Trace Manual
+#### Manual Tracing
 
 ```typescript
 import { createTraceCollector } from '@runflow-ai/sdk';
 
-// Criar collector
+// Create collector
 const collector = createTraceCollector(apiClient, 'project_123', {
   batchSize: 10,
   flushInterval: 5000,
+  maxRetries: 3,
 });
 
 // Start span
@@ -938,14 +1230,18 @@ const span = collector.startSpan('custom_operation', {
 span.setInput({ data: 'input' });
 
 try {
-  // Executar operação
+  // Execute operation
   const result = await doSomething();
-  
+
   span.setOutput(result);
   span.setCosts({
     tokens: { input: 100, output: 50, total: 150 },
-    costs: { inputCost: 0.003, outputCost: 0.002, totalCost: 0.005, currency: 'USD' },
-    totalCost: 0.005,
+    costs: {
+      inputCost: 0.003,
+      outputCost: 0.002,
+      totalCost: 0.005,
+      currency: 'USD'
+    },
   });
 } catch (error) {
   span.setError(error);
@@ -953,172 +1249,51 @@ try {
 
 span.finish();
 
-// Forçar flush
+// Force flush
 await collector.flush();
 ```
 
-#### Decorator para Auto-Tracing
+#### Decorator for Auto-Tracing
 
 ```typescript
 import { traced } from '@runflow-ai/sdk';
 
 class MyService {
   private traceCollector: TraceCollector;
-  
+
   @traced('my_operation', { agentName: 'My Agent' })
   async myMethod(input: any) {
-    // Automaticamente traced
+    // Automatically traced
     return processData(input);
   }
 }
 ```
 
-#### Traces Locais (Development)
-
-```typescript
-// .env
-RUNFLOW_LOCAL_TRACES=true
-
-// Traces serão salvos em .runflow/traces.json
-// Formato estruturado por executionId para análise
-```
-
----
-
-## 🏗️ Arquitetura
-
-### Estrutura do SDK
-
-```
-@runflow-ai/sdk/
-├── core/               # Núcleo do SDK
-│   ├── agent.ts        # Classe Agent principal
-│   ├── api-client.ts   # Cliente da API Runflow
-│   ├── context.ts      # Runflow singleton (context management)
-│   └── models.ts       # Model providers (openai, anthropic, bedrock)
-│
-├── tools/              # Sistema de Tools
-│   └── tool-creator.ts # Factory para criar tools
-│
-├── connectors/         # Sistema de Connectors
-│   ├── connector-creator.ts
-│   └── built-in/       # HubSpot, Twilio, Email, Slack
-│
-├── workflows/          # Sistema de Workflows
-│   └── workflow.ts     # Workflow engine + builder
-│
-├── memory/             # Sistema de Memory
-│   └── memory-manager.ts
-│
-├── knowledge/          # Sistema de RAG
-│   └── knowledge-manager.ts
-│
-├── llm/                # LLM Standalone
-│   └── llm-manager.ts
-│
-├── observability/      # Sistema de Traces
-│   └── trace-collector.ts
-│
-├── providers/          # Provider interfaces
-│   ├── types.ts        # MemoryProvider, KnowledgeProvider, LLMProvider
-│   └── runflow/        # Implementações padrão
-│
-└── types/              # TypeScript types
-    └── all-types.ts    # Todos os tipos do SDK
-```
-
-### Fluxo de Execução
-
-```
-1. Developer cria Agent/Workflow
-2. SDK configura API Client (auto ou injetado)
-3. Agent.process() é chamado
-4. Context é resolvido (Runflow.identify() ou input direto)
-5. Memory é carregada (se configurado)
-6. RAG busca contexto (se configurado)
-7. LLM é chamado com prompt + context
-8. Tools são executadas (se chamadas)
-9. Response é gerada
-10. Memory é salva (se configurado)
-11. Traces são coletados (automático)
-12. Output é retornado
-```
-
-### Multi-Agent Pattern
-
-```typescript
-// Supervisor Pattern (automático)
-const agent = new Agent({
-  name: 'Supervisor',
-  instructions: 'Route tasks to appropriate agents.',
-  model: openai('gpt-4o'),
-  agents: {
-    support: {
-      name: 'Support Agent',
-      instructions: 'Handle support requests.',
-      model: openai('gpt-4o-mini'),
-    },
-    sales: {
-      name: 'Sales Agent',
-      instructions: 'Handle sales inquiries.',
-      model: openai('gpt-4o-mini'),
-    },
-  },
-});
-
-// Supervisor decide automaticamente qual agent usar
-await agent.process({
-  message: 'I want to buy your product',
-  companyId: 'company_123',
-});
-```
-
----
-
-## 🔧 Configuração
-
-### Variáveis de Ambiente
+#### Local Traces (Development)
 
 ```bash
-# API Configuration
-RUNFLOW_API_URL=http://localhost:3001
-RUNFLOW_API_KEY=your_api_key_here
-RUNFLOW_TENANT_ID=your_tenant_id
-RUNFLOW_AGENT_ID=your_agent_id
-
-# Execution Context (opcional - geralmente vem da engine)
-RUNFLOW_EXECUTION_ID=exec_123
-RUNFLOW_THREAD_ID=thread_456
-RUNFLOW_TENANT_ID=company_123
-
-# Development
-RUNFLOW_ENV=development
+# .env
 RUNFLOW_LOCAL_TRACES=true
 ```
 
-### Arquivo de Configuração (.runflow/rf.json)
+Traces will be saved to `.runflow/traces.json` in a structured format organized by `executionId` for analysis.
 
-```json
-{
-  "agentId": "your_agent_id",
-  "tenantId": "your_tenant_id",
-  "apiKey": "your_api_key",
-  "apiUrl": "http://localhost:3001"
-}
-```
+#### Trace Types
 
-O SDK busca automaticamente `.runflow/rf.json` no diretório atual e nos pais.
-
-**Prioridade de configuração:**
-
-1. Config explícito no código
-2. `.runflow/rf.json`
-3. Variáveis de ambiente
-4. Defaults
+The SDK supports various trace types:
+- `agent_execution` - Full agent processing
+- `workflow_execution` - Workflow processing
+- `workflow_step` - Individual workflow step
+- `tool_call` - Tool execution
+- `llm_call` - LLM API call
+- `vector_search` - Vector search operation
+- `memory_operation` - Memory access
+- `connector_call` - Connector execution
+- `streaming_session` - Streaming response
 
 ---
 
-## 📚 Exemplos Avançados
+## 🏗️ Advanced Examples
 
 ### Multi-Modal (Images)
 
@@ -1131,7 +1306,6 @@ const agent = new Agent({
 
 await agent.process({
   message: 'What is in this image?',
-  companyId: 'company_123',
   messages: [
     {
       role: 'user',
@@ -1147,7 +1321,7 @@ await agent.process({
 });
 ```
 
-### Streaming com Memory
+### Streaming with Memory
 
 ```typescript
 const agent = new Agent({
@@ -1155,7 +1329,6 @@ const agent = new Agent({
   instructions: 'You are helpful.',
   model: openai('gpt-4o'),
   memory: {
-    type: 'conversation',
     maxTurns: 10,
   },
   streaming: {
@@ -1165,7 +1338,6 @@ const agent = new Agent({
 
 const stream = await agent.processStream({
   message: 'Tell me a story',
-  companyId: 'company_123',
   sessionId: 'session_123',
 });
 
@@ -1183,26 +1355,33 @@ import { Memory, MemoryProvider } from '@runflow-ai/sdk';
 
 class RedisMemoryProvider implements MemoryProvider {
   async get(key: string): Promise<MemoryData> {
-    // Implementar com Redis
     const data = await redis.get(key);
     return JSON.parse(data);
   }
-  
+
   async set(key: string, data: MemoryData): Promise<void> {
     await redis.set(key, JSON.stringify(data));
   }
-  
-  // ... outros métodos
+
+  async append(key: string, message: MemoryMessage): Promise<void> {
+    const data = await this.get(key);
+    data.messages.push(message);
+    await this.set(key, data);
+  }
+
+  async clear(key: string): Promise<void> {
+    await redis.del(key);
+  }
 }
 
-// Usar custom provider
+// Use custom provider
 const memory = new Memory({
   provider: new RedisMemoryProvider(),
   maxTurns: 10,
 });
 ```
 
-### Complex Workflow
+### Complex E-Commerce Workflow
 
 ```typescript
 const workflow = createWorkflow({
@@ -1217,7 +1396,7 @@ const workflow = createWorkflow({
   .agent('analyzer', analyzerAgent, {
     promptTemplate: 'Analyze customer query: {{input.query}}',
   })
-  
+
   // 2. Load customer data in parallel
   .parallel([
     createFunctionStep('load-profile', async (input, ctx) => {
@@ -1230,7 +1409,7 @@ const workflow = createWorkflow({
       return await searchProducts(ctx.stepResults.get('analyzer').text);
     }),
   ])
-  
+
   // 3. Conditional: Sales vs Support
   .condition(
     'route',
@@ -1251,7 +1430,7 @@ const workflow = createWorkflow({
       }),
     ]
   )
-  
+
   // 4. Send response
   .agent('responder', responderAgent, {
     promptTemplate: 'Create final response based on context',
@@ -1266,50 +1445,658 @@ const result = await workflow.execute({
 
 ---
 
-## 📖 API Reference
+## 💡 Real-World Use Cases
+
+Complete, production-ready examples showcasing the platform's potential.
 
-### Exports Principais
+### 1. Customer Support Agent with RAG
+
+A sophisticated support agent that searches documentation, remembers context, and creates tickets in HubSpot.
 
 ```typescript
-// Core
-export { Agent, Runflow, openai, anthropic, bedrock } from '@runflow-ai/sdk';
+import { Agent, openai, createTool } from '@runflow-ai/sdk';
+import { hubspotConnector } from '@runflow-ai/sdk/connectors';
+import { z } from 'zod';
 
-// Tools & Connectors
-export { createTool, createConnectorTool } from '@runflow-ai/sdk';
-export { hubspot, twilio, email, slack } from '@runflow-ai/sdk';
+// Create a support agent with memory and RAG
+const supportAgent = new Agent({
+  name: 'Customer Support AI',
+  instructions: `You are a helpful customer support agent.
+  - Search the knowledge base for relevant information
+  - Remember previous conversations
+  - Create tickets for complex issues
+  - Always be professional and empathetic`,
 
-// Workflows
-export { 
-  Workflow, 
-  createWorkflow,
-  createStep,
-  createAgentStep,
-  createFunctionStep,
+  model: openai('gpt-4o'),
+
+  // Remember conversation history
+  memory: {
+    maxTurns: 20,
+    summarizeAfter: 10,
+    summarizePrompt: 'Summarize key customer issues and resolutions',
+  },
+
+  // Search in documentation
+  knowledge: {
+    vectorStore: 'support-docs',
+    k: 5,
+    threshold: 0.7,
+  },
+
+  // Available tools
+  tools: {
+    createTicket: hubspotConnector.tickets.create,
+    searchOrders: createTool({
+      id: 'search-orders',
+      description: 'Search customer orders',
+      inputSchema: z.object({
+        customerId: z.string(),
+      }),
+      execute: async ({ context }) => {
+        const orders = await fetchOrders(context.input.customerId);
+        return { orders };
+      },
+    }),
+  },
+});
+
+// Handle customer message
+const result = await supportAgent.process({
+  message: 'My order #12345 has not arrived yet',
+  sessionId: 'session_xyz',  // For conversation history
+  userId: 'user_123',         // For user identification
+});
+
+console.log(result.message);
+// Agent searches docs, retrieves order info, and provides solution
+```
+
+### 2. Sales Automation with Multi-Step Workflow
+
+Automate lead qualification, deal creation, and team notifications using workflows.
+
+```typescript
+import { createWorkflow, Agent, openai } from '@runflow-ai/sdk';
+import { hubspotConnector, slackConnector } from '@runflow-ai/sdk/connectors';
+import { z } from 'zod';
+
+// Qualification agent
+const qualifierAgent = new Agent({
+  name: 'Lead Qualifier',
+  instructions: 'Analyze lead data and assign a score (1-10) with reasoning.',
+  model: openai('gpt-4o-mini'),
+});
+
+// Sales copy agent
+const copywriterAgent = new Agent({
+  name: 'Sales Copywriter',
+  instructions: 'Write a personalized email for the lead based on their profile.',
+  model: openai('gpt-4o'),
+});
+
+// Complete workflow
+const salesWorkflow = createWorkflow({
+  id: 'lead-to-deal',
+  inputSchema: z.object({
+    leadEmail: z.string().email(),
+    leadName: z.string(),
+    company: z.string(),
+    notes: z.string(),
+  }),
+  outputSchema: z.any(),
+})
+  // Step 1: Qualify the lead
+  .agent('qualify', qualifierAgent, {
+    promptTemplate: `Analyze this lead:
+    Name: {{input.leadName}}
+    Company: {{input.company}}
+    Notes: {{input.notes}}
+
+    Provide score (1-10) and reasoning.`,
+  })
+
+  // Step 2: Conditional - Only proceed if score >= 7
+  .condition(
+    'check-score',
+    (ctx) => {
+      const score = parseInt(ctx.stepResults.get('qualify').text.match(/\d+/)?.[0] || '0');
+      return score >= 7;
+    },
+    // High quality lead path
+    [
+      // Create contact in HubSpot
+      {
+        id: 'create-contact',
+        type: 'connector',
+        config: {
+          connector: 'hubspot',
+          resource: 'contacts',
+          action: 'create',
+          parameters: {
+            email: '{{input.leadEmail}}',
+            firstname: '{{input.leadName}}',
+            company: '{{input.company}}',
+            lifecyclestage: 'lead',
+          },
+        },
+      },
+
+      // Create deal
+      {
+        id: 'create-deal',
+        type: 'connector',
+        config: {
+          connector: 'hubspot',
+          resource: 'deals',
+          action: 'create',
+          parameters: {
+            dealname: 'Deal - {{input.company}}',
+            amount: 5000,
+            dealstage: 'qualifiedtobuy',
+            pipeline: 'default',
+            hubspot_owner_id: '12345',
+          },
+        },
+      },
+
+      // Generate personalized email
+      {
+        id: 'write-email',
+        type: 'agent',
+        config: {
+          agent: copywriterAgent,
+          promptTemplate: `Write a personalized sales email for:
+          Name: {{input.leadName}}
+          Company: {{input.company}}
+          Qualification: {{qualify.text}}`,
+        },
+      },
+
+      // Notify sales team on Slack
+      {
+        id: 'notify-team',
+        type: 'connector',
+        config: {
+          connector: 'slack',
+          resource: 'messages',
+          action: 'send',
+          parameters: {
+            channel: '#sales',
+            text: `🎯 New qualified lead: *{{input.leadName}}* from *{{input.company}}*\nScore: High\nDeal created: {{create-deal.id}}`,
+          },
+        },
+      },
+    ],
+    // Low quality lead path
+    [
+      {
+        id: 'log-rejected',
+        type: 'function',
+        config: {
+          execute: async (input, ctx) => {
+            console.log(`Lead ${input.leadName} rejected - Low score`);
+            return { rejected: true };
+          },
+        },
+      },
+    ]
+  )
+  .build();
+
+// Execute workflow
+const result = await salesWorkflow.execute({
+  leadEmail: 'john@techcorp.com',
+  leadName: 'John Smith',
+  company: 'TechCorp Inc',
+  notes: 'Interested in enterprise plan. Budget: $10k/month. Timeline: Q1 2025.',
+});
+
+console.log('Workflow completed:', result);
+```
+
+### 3. Intelligent Collections Agent (WhatsApp)
+
+Automate debt collection with personalized WhatsApp messages using context-aware AI.
+
+```typescript
+import { Agent, openai, Runflow } from '@runflow-ai/sdk';
+import { twilioConnector } from '@runflow-ai/sdk/connectors';
+import { z } from 'zod';
+
+// Collections agent with empathy and context
+const collectionsAgent = new Agent({
+  name: 'Collections AI',
+  instructions: `You are an empathetic debt collection agent.
+  - Analyze customer history and payment patterns
+  - Create personalized, respectful messages
+  - Offer payment plan options
+  - Never be aggressive or rude`,
+
+  model: openai('gpt-4o'),
+
+  memory: {
+    maxTurns: 10,
+  },
+
+  tools: {
+    sendWhatsApp: twilioConnector.whatsapp.send,
+    getPaymentHistory: createTool({
+      id: 'get-payment-history',
+      description: 'Get customer payment history',
+      inputSchema: z.object({
+        customerId: z.string(),
+      }),
+      execute: async ({ context }) => {
+        const history = await fetchPaymentHistory(context.input.customerId);
+        return { history };
+      },
+    }),
+  },
+});
+
+// Process overdue invoice
+async function processOverdueInvoice(invoice: any) {
+  // Set customer context
+  Runflow.identify({
+    type: 'customer',
+    value: invoice.customerId,
+    userId: invoice.customerId,
+  });
+
+  const result = await collectionsAgent.process({
+    message: `Create a personalized WhatsApp message for customer ${invoice.customerName}.
+    Invoice: ${invoice.id}
+    Amount: $${invoice.amount}
+    Days overdue: ${invoice.daysOverdue}
+    Previous payment history: Check using the tool.
+
+    If history is good, offer a payment plan. Send via WhatsApp.`,
+    sessionId: `collection_${invoice.id}`,
+  });
+
+  console.log('Collection message sent:', result);
+}
+
+// Batch process overdue invoices
+const overdueInvoices = await fetchOverdueInvoices();
+for (const invoice of overdueInvoices) {
+  await processOverdueInvoice(invoice);
+}
+```
+
+### 4. Customer Onboarding Assistant
+
+Guide new users through onboarding with an interactive, multi-turn conversation.
+
+```typescript
+import { Agent, openai } from '@runflow-ai/sdk';
+import { emailConnector, slackConnector } from '@runflow-ai/sdk/connectors';
+
+const onboardingAgent = new Agent({
+  name: 'Onboarding Assistant',
+  instructions: `You are an onboarding specialist.
+  - Guide users step by step
+  - Celebrate their progress
+  - Provide helpful resources
+  - Detect when they're stuck and offer help
+  - Track completion of onboarding steps`,
+
+  model: openai('gpt-4o'),
+
+  memory: {
+    maxTurns: 50, // Long conversation
+    summarizeAfter: 20,
+    summarizePrompt: 'Summarize onboarding progress, completed steps, and next actions',
+  },
+
+  knowledge: {
+    vectorStore: 'onboarding-docs',
+    k: 3,
+  },
+
+  tools: {
+    sendEmail: emailConnector.messages.send,
+    notifyTeam: slackConnector.messages.send,
+    markStepComplete: createTool({
+      id: 'mark-step-complete',
+      description: 'Mark an onboarding step as complete',
+      inputSchema: z.object({
+        stepName: z.string(),
+        userId: z.string(),
+      }),
+      execute: async ({ context }) => {
+        await updateOnboardingProgress(
+          context.input.userId,
+          context.input.stepName
+        );
+        return { success: true };
+      },
+    }),
+  },
+});
+
+// Interactive onboarding session
+const sessionId = `onboarding_user_${userId}`;
+
+// Step 1
+await onboardingAgent.process({
+  message: 'Start onboarding for new user',
+  sessionId,
+  userId,
+});
+
+// User responds
+await onboardingAgent.process({
+  message: 'I want to create my first agent',
+  sessionId,
+  userId,
+});
+
+// Agent guides through agent creation...
+```
+
+### 5. Feedback Analysis System
+
+Collect customer feedback, analyze sentiment, and create actionable tickets.
+
+```typescript
+import { createWorkflow, Agent, openai } from '@runflow-ai/sdk';
+import { hubspotConnector, slackConnector } from '@runflow-ai/sdk/connectors';
+import { z } from 'zod';
+
+// Sentiment analyzer
+const sentimentAgent = new Agent({
+  name: 'Sentiment Analyzer',
+  instructions: 'Analyze feedback sentiment (positive/neutral/negative) and extract key themes.',
+  model: openai('gpt-4o-mini'),
+});
+
+// Action recommender
+const actionAgent = new Agent({
+  name: 'Action Recommender',
+  instructions: 'Recommend specific actions based on feedback analysis.',
+  model: openai('gpt-4o'),
+});
+
+const feedbackWorkflow = createWorkflow({
+  id: 'feedback-analysis',
+  inputSchema: z.object({
+    feedback: z.string(),
+    customerEmail: z.string(),
+    customerName: z.string(),
+    source: z.string(),
+  }),
+  outputSchema: z.any(),
+})
+  // Analyze sentiment
+  .agent('analyze', sentimentAgent, {
+    promptTemplate: 'Analyze: {{input.feedback}}',
+  })
+
+  // Recommend actions
+  .agent('recommend', actionAgent, {
+    promptTemplate: `Feedback: {{input.feedback}}
+    Sentiment: {{analyze.text}}
+
+    What actions should we take?`,
+  })
+
+  // Conditional: Create ticket if negative
+  .condition(
+    'check-negative',
+    (ctx) => ctx.stepResults.get('analyze').text.toLowerCase().includes('negative'),
+    // Negative feedback path
+    [
+      {
+        id: 'create-ticket',
+        type: 'connector',
+        config: {
+          connector: 'hubspot',
+          resource: 'tickets',
+          action: 'create',
+          parameters: {
+            subject: 'Negative Feedback - {{input.customerName}}',
+            content: '{{input.feedback}}\n\nAnalysis: {{analyze.text}}\n\nRecommended actions: {{recommend.text}}',
+            priority: 'high',
+            category: 'feedback',
+          },
+        },
+      },
+      {
+        id: 'alert-team',
+        type: 'connector',
+        config: {
+          connector: 'slack',
+          resource: 'messages',
+          action: 'send',
+          parameters: {
+            channel: '#customer-success',
+            text: `⚠️ Negative feedback from *{{input.customerName}}*\nTicket created: {{create-ticket.id}}`,
+          },
+        },
+      },
+    ],
+    // Positive/neutral feedback path
+    [
+      {
+        id: 'log-positive',
+        type: 'function',
+        config: {
+          execute: async (input, ctx) => {
+            console.log('Positive feedback logged');
+            return { logged: true };
+          },
+        },
+      },
+    ]
+  )
+  .build();
+
+// Process feedback
+const result = await feedbackWorkflow.execute({
+  feedback: 'The support team was unhelpful and the product is buggy',
+  customerEmail: 'unhappy@customer.com',
+  customerName: 'Jane Doe',
+  source: 'email',
+});
+```
+
+### 6. Multi-Agent System (Supervisor Pattern)
+
+Route requests to specialized agents based on intent.
+
+```typescript
+import { Agent, openai } from '@runflow-ai/sdk';
+
+// Specialized agents
+const salesAgent = new Agent({
+  name: 'Sales Specialist',
+  instructions: 'You are a sales expert. Help with pricing, demos, and purchasing.',
+  model: openai('gpt-4o'),
+  tools: { /* sales tools */ },
+});
+
+const supportAgent = new Agent({
+  name: 'Technical Support',
+  instructions: 'You are a technical support expert. Help with technical issues.',
+  model: openai('gpt-4o'),
+  knowledge: { vectorStore: 'tech-docs', k: 5 },
+});
+
+const billingAgent = new Agent({
+  name: 'Billing Specialist',
+  instructions: 'You handle billing, invoices, and payment issues.',
+  model: openai('gpt-4o'),
+  tools: { /* billing tools */ },
+});
+
+// Supervisor agent
+const supervisorAgent = new Agent({
+  name: 'Supervisor',
+  instructions: `You route customer requests to the right specialist:
+  - Sales: pricing, demos, purchasing
+  - Support: technical issues, bugs
+  - Billing: invoices, payments, subscriptions
+
+  Analyze the request and respond with: ROUTE_TO: [sales|support|billing]`,
+  model: openai('gpt-4o-mini'),
+});
+
+// Routing function
+async function handleCustomerRequest(message: string, context: any) {
+  // 1. Supervisor analyzes intent
+  const routing = await supervisorAgent.process({
+    message: `Analyze this request: "${message}"`,
+    ...context,
+  });
+
+  // 2. Extract route
+  const route = routing.message.match(/ROUTE_TO: (\w+)/)?.[1] || 'support';
+
+  // 3. Route to specialist
+  const agents = {
+    sales: salesAgent,
+    support: supportAgent,
+    billing: billingAgent,
+  };
+
+  const specialistAgent = agents[route];
+
+  // 4. Specialist handles request
+  const result = await specialistAgent.process({
+    message,
+    ...context,
+  });
+
+  return {
+    route,
+    response: result.message,
+  };
+}
+
+// Example usage
+const result = await handleCustomerRequest(
+  'I want to upgrade to the enterprise plan',
+  {
+    sessionId: 'session_456',
+    userId: 'user_789',
+  }
+);
+
+console.log(`Routed to: ${result.route}`);
+console.log(`Response: ${result.response}`);
+```
+
+---
+
+## 🔧 Configuration
+
+### Environment Variables
+
+```bash
+# API Configuration
+RUNFLOW_API_URL=http://localhost:3001
+RUNFLOW_API_KEY=your_api_key_here
+RUNFLOW_TENANT_ID=your_tenant_id
+RUNFLOW_AGENT_ID=your_agent_id
+
+# Execution Context (optional - usually comes from engine)
+RUNFLOW_EXECUTION_ID=exec_123
+RUNFLOW_THREAD_ID=thread_456
+
+# Development
+RUNFLOW_ENV=development
+RUNFLOW_LOCAL_TRACES=true
+NODE_ENV=development
+```
+
+### Configuration File (.runflow/rf.json)
+
+```json
+{
+  "agentId": "your_agent_id",
+  "tenantId": "your_tenant_id",
+  "apiKey": "your_api_key",
+  "apiUrl": "http://localhost:3001"
+}
+```
+
+The SDK automatically searches for `.runflow/rf.json` in the current directory and parent directories.
+
+**Configuration Priority:**
+
+1. Explicit config in code
+2. `.runflow/rf.json`
+3. Environment variables
+4. Defaults
+
+### Manual API Client Configuration
+
+```typescript
+import { createRunflowAPIClient, Agent, openai } from '@runflow-ai/sdk';
+
+const apiClient = createRunflowAPIClient({
+  apiUrl: 'https://api.runflow.ai',
+  apiKey: 'your_api_key',
+  tenantId: 'your_tenant_id',
+  agentId: 'your_agent_id',
+});
+
+// Inject into agent
+const agent = new Agent({
+  name: 'My Agent',
+  instructions: 'Help users',
+  model: openai('gpt-4o'),
+});
+
+agent._setAPIClient(apiClient);
+```
+
+---
+
+## 📖 API Reference
+
+### Main Exports
+
+```typescript
+// Core
+import { Agent, Runflow, openai, anthropic, bedrock } from '@runflow-ai/sdk';
+
+// Tools & Connectors
+import { createTool, createConnectorTool } from '@runflow-ai/sdk';
+import { hubspot, twilio, email, slack } from '@runflow-ai/sdk';
+
+// Workflows
+import {
+  Workflow,
+  createWorkflow,
+  createStep,
+  createAgentStep,
+  createFunctionStep,
   createConnectorStep,
+  WorkflowBuilder,
 } from '@runflow-ai/sdk';
 
 // Standalone Modules
-export { Memory, Knowledge, RAG, LLM } from '@runflow-ai/sdk';
+import { Memory, Knowledge, RAG, LLM } from '@runflow-ai/sdk';
 
 // Observability
-export { 
-  createTraceCollector, 
-  RunflowTraceCollector, 
-  traced 
+import {
+  createTraceCollector,
+  RunflowTraceCollector,
+  RunflowTraceSpan,
+  traced
 } from '@runflow-ai/sdk';
 
-// Types
-export type {
-  AgentConfig,
-  AgentInput,
-  AgentOutput,
-  ModelProvider,
-  RunflowTool,
-  ToolConfig,
-  WorkflowConfig,
-  MemoryConfig,
-  TraceData,
-  // ... etc
+// API Client
+import { createRunflowAPIClient } from '@runflow-ai/sdk';
+
+// Providers
+import {
+  MemoryProvider,
+  KnowledgeProvider,
+  LLMProvider,
+  RunflowMemoryProvider,
 } from '@runflow-ai/sdk';
 ```
 
@@ -1318,18 +2105,17 @@ export type {
 ```typescript
 // Core
 import { Agent } from '@runflow-ai/sdk/core';
-
-// Models
-import { openai, anthropic, bedrock } from '@runflow-ai/sdk/models';
+import { Runflow } from '@runflow-ai/sdk/core';
+import { openai, anthropic, bedrock } from '@runflow-ai/sdk/core';
 
 // Tools
 import { createTool } from '@runflow-ai/sdk/tools';
 
 // Connectors
-import { createConnectorTool, hubspot } from '@runflow-ai/sdk/connectors';
+import { createConnectorTool, hubspot, twilio, email, slack } from '@runflow-ai/sdk/connectors';
 
 // Workflows
-import { createWorkflow } from '@runflow-ai/sdk/workflows';
+import { createWorkflow, WorkflowBuilder } from '@runflow-ai/sdk/workflows';
 
 // Memory
 import { Memory } from '@runflow-ai/sdk/memory';
@@ -1341,22 +2127,261 @@ import { Knowledge, RAG } from '@runflow-ai/sdk/knowledge';
 import { LLM } from '@runflow-ai/sdk/llm';
 
 // Observability
-import { createTraceCollector } from '@runflow-ai/sdk/observability';
+import { createTraceCollector, traced } from '@runflow-ai/sdk/observability';
 
 // Types
-import type { AgentConfig } from '@runflow-ai/sdk/types';
+import type { AgentConfig, AgentInput, AgentOutput } from '@runflow-ai/sdk/types';
 
 // Providers
-import type { MemoryProvider } from '@runflow-ai/sdk/providers';
+import type { MemoryProvider, KnowledgeProvider, LLMProvider } from '@runflow-ai/sdk/providers';
+```
+
+---
+
+## 📝 TypeScript Types
+
+### Core Types
+
+```typescript
+interface AgentInput {
+  message: string;
+  companyId: string;
+  userId?: string;
+  sessionId?: string;
+  executionId?: string;
+  threadId?: string;
+  entityType?: string;
+  entityValue?: string;
+  channel?: string;
+  messages?: Message[];
+  metadata?: Record<string, any>;
+}
+
+interface AgentOutput {
+  message: string;
+  metadata?: Record<string, any>;
+}
+
+interface AgentConfig {
+  name: string;
+  instructions: string;
+  model: ModelProvider;
+  modelConfig?: ModelConfig;
+  tools?: Record<string, RunflowTool>;
+  maxToolIterations?: number;
+  rag?: RAGConfig;
+  memory?: MemoryConfig;
+  streaming?: StreamingConfig;
+  agents?: Record<string, AgentConfig>;
+  debug?: boolean | DebugConfig;
+}
+
+interface ModelConfig {
+  temperature?: number;
+  maxTokens?: number;
+  topP?: number;
+  frequencyPenalty?: number;
+  presencePenalty?: number;
+  stop?: string[];
+  seed?: number;
+}
+
+interface DebugConfig {
+  enabled: boolean;
+  logMessages?: boolean;
+  logLLMCalls?: boolean;
+  logToolCalls?: boolean;
+  logRAG?: boolean;
+  logMemory?: boolean;
+  truncateAt?: number;
+}
+```
+
+### Memory Types
+
+```typescript
+interface MemoryConfig {
+  type?: 'conversation' | 'entity' | 'summary' | 'hybrid';  // Optional - reserved for future
+  maxTurns?: number;              // Max conversation turns to keep
+  maxTokens?: number;             // Max tokens to keep
+  summarizeAfter?: number;        // Trigger summary after N turns
+  summarizePrompt?: string;       // Custom prompt for summarization
+  summarizeModel?: ModelProvider; // Custom model for summarization (e.g., gpt-4o-mini)
+  memoryKey?: string;             // Custom memory key
+}
+
+interface MemoryData {
+  sessionId: string;
+  messages: MemoryMessage[];
+  entities: Record<string, any>;
+  summary?: string;
+  metadata: {
+    createdAt: Date;
+    updatedAt: Date;
+    totalTurns: number;
+    totalTokens: number;
+  };
+}
+
+interface MemoryMessage {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  timestamp: Date;
+  metadata?: {
+    toolsUsed?: string[];
+    ragUsed?: boolean;
+    model?: string;
+    tokens?: number;
+  };
+}
+```
+
+### RAG Types
+
+```typescript
+interface RAGConfig {
+  vectorStore?: string;
+  vectorStores?: Array<{
+    id: string;
+    name: string;
+    threshold?: number;
+    k?: number;
+    description?: string;
+    searchPrompt?: string;         // Individual guidance for this KB
+  }>;
+  threshold?: number;
+  k?: number;
+  searchPrompt?: string;           // Global search guidance
+  toolDescription?: string;
+}
+
+interface SearchResult {
+  content: string;
+  score: number;
+  metadata?: Record<string, any>;
+}
+```
+
+### Tool Types
+
+```typescript
+interface ToolConfig<TInput = any, TOutput = any> {
+  id: string;
+  description: string;
+  inputSchema: z.ZodSchema<TInput>;
+  outputSchema?: z.ZodSchema<TOutput>;
+  execute: (params: {
+    context: TInput;
+    runflow: RunflowAPIClient;
+    projectId: string;
+  }) => Promise<TOutput>;
+}
+
+interface RunflowTool {
+  id: string;
+  name?: string;
+  description: string;
+  parameters: Record<string, ToolParameter>;
+  execute: (params: any, context: ToolContext) => Promise<any>;
+}
+
+interface ToolContext {
+  projectId: string;
+  companyId: string;
+  userId?: string;
+  sessionId?: string;
+  runflowAPI: RunflowAPIClient;
+}
+```
+
+### Workflow Types
+
+```typescript
+interface WorkflowConfig {
+  id: string;
+  name?: string;
+  description?: string;
+  inputSchema: z.ZodSchema;
+  outputSchema: z.ZodSchema;
+  steps: WorkflowStep[];
+  options?: WorkflowOptions;
+}
+
+interface WorkflowStep {
+  id: string;
+  name?: string;
+  description?: string;
+  type: 'agent' | 'function' | 'connector' | 'condition' | 'parallel';
+  config: StepConfig;
+  inputTransform?: (previousOutput: any, workflowInput: any) => any;
+  outputTransform?: (stepOutput: any) => any;
+  condition?: (context: WorkflowContext) => boolean;
+  retryConfig?: RetryConfig;
+}
+
+interface RetryConfig {
+  maxAttempts: number;
+  backoff: 'fixed' | 'exponential' | 'linear';
+  delay: number;
+  retryableErrors?: string[];
+}
+```
+
+### Trace Types
+
+```typescript
+interface TraceData {
+  traceId: string;
+  parentTraceId?: string;
+  projectId: string;
+  executionId?: string;
+  threadId?: string;
+  type: TraceType;
+  operation: string;
+  input: any;
+  output?: any;
+  status: 'success' | 'error' | 'timeout' | 'cancelled';
+  error?: string;
+  startTime: Date;
+  endTime?: Date;
+  duration: number;
+  metadata: TraceMetadata;
+  costs?: TraceCosts;
+}
+
+type TraceType =
+  | 'agent_execution'
+  | 'workflow_execution'
+  | 'workflow_step'
+  | 'tool_call'
+  | 'connector_call'
+  | 'vector_search'
+  | 'memory_operation'
+  | 'llm_call'
+  | 'streaming_session';
+
+interface TraceCosts {
+  tokens?: {
+    input: number;
+    output: number;
+    total: number;
+  };
+  costs?: {
+    inputCost: number;
+    outputCost: number;
+    totalCost: number;
+    currency: string;
+  };
+}
 ```
 
 ---
 
 ## 🔌 Providers
 
-O SDK suporta **providers plugáveis** para memória, knowledge e LLM.
+The SDK supports **pluggable providers** for memory, knowledge, and LLM.
 
-### Memory Providers
+### Memory Provider Interface
 
 ```typescript
 interface MemoryProvider {
@@ -1369,15 +2394,16 @@ interface MemoryProvider {
 }
 ```
 
-### Knowledge Providers
+### Knowledge Provider Interface
 
 ```typescript
 interface KnowledgeProvider {
   search(query: string, options: SearchOptions): Promise<SearchResult[]>;
+  embed?(text: string): Promise<number[]>;
 }
 ```
 
-### LLM Providers
+### LLM Provider Interface
 
 ```typescript
 interface LLMProvider {
@@ -1386,22 +2412,142 @@ interface LLMProvider {
 }
 ```
 
+### Built-in Providers
+
+```typescript
+import { RunflowMemoryProvider } from '@runflow-ai/sdk';
+
+// Use Runflow's built-in memory provider
+const memory = new Memory({
+  provider: new RunflowMemoryProvider(apiClient),
+  maxTurns: 10,
+});
+```
+
 ---
 
-## 🤝 Contribuindo
+## 🔍 Troubleshooting
+
+### Common Issues
+
+#### API Client Not Configured
 
-Contribuições são bem-vindas! Por favor:
+```
+Error: Runflow API Client is not configured
+```
+
+**Solution:** Ensure you have either:
+1. Environment variables set (`RUNFLOW_API_KEY`, `RUNFLOW_TENANT_ID`)
+2. A `.runflow/rf.json` file
+3. Manually configured the API client
+
+```typescript
+import { createRunflowAPIClient, Agent, openai } from '@runflow-ai/sdk';
+
+const apiClient = createRunflowAPIClient({
+  apiKey: 'your_api_key',
+  tenantId: 'your_tenant_id',
+});
+
+const agent = new Agent({
+  name: 'My Agent',
+  instructions: 'Help users',
+  model: openai('gpt-4o'),
+});
 
-1. Fork o projeto
-2. Crie uma branch para sua feature (`git checkout -b feature/amazing-feature`)
-3. Commit suas mudanças (`git commit -m 'Add amazing feature'`)
-4. Push para a branch (`git push origin feature/amazing-feature`)
-5. Abra um Pull Request
+agent._setAPIClient(apiClient);
+```
 
-### Desenvolvimento Local
+#### Memory Not Persisting
+
+**Issue:** Memory is not persisting between sessions
+
+**Solution:** Ensure you're passing the same `sessionId` or using `Runflow.identify()` consistently:
+
+```typescript
+// Use Runflow.identify() for automatic session management
+Runflow.identify({
+  type: 'phone',
+  value: '+5511999999999',
+});
+
+// OR pass sessionId explicitly
+await agent.process({
+  message: 'Hello',
+  sessionId: 'session_456', // Same session ID
+});
+```
+
+#### Tool Not Being Called
+
+**Issue:** Agent is not calling tools even when it should
+
+**Solution:**
+1. Make sure tool descriptions are clear and specific
+2. Use `debug: true` to see what the agent is doing
+3. Check that `maxToolIterations` is not set too low
+
+```typescript
+const agent = new Agent({
+  name: 'My Agent',
+  instructions: 'You MUST use the weather tool when users ask about weather.',
+  model: openai('gpt-4o'),
+  tools: {
+    weather: weatherTool,
+  },
+  maxToolIterations: 10, // Default
+  debug: true, // Enable debug logging
+});
+```
+
+#### RAG Not Finding Results
+
+**Issue:** Knowledge base search returns no results
+
+**Solution:**
+1. Check `threshold` value (lower = more results)
+2. Increase `k` value for more results
+3. Verify vector store name is correct
+
+```typescript
+rag: {
+  vectorStore: 'support-docs', // Verify this exists
+  k: 10,           // Increase for more results
+  threshold: 0.5,  // Lower for more lenient matching
+}
+```
+
+#### TypeScript Errors
+
+**Issue:** TypeScript errors when using the SDK
+
+**Solution:** Make sure you're using TypeScript >= 5.0.0 and have proper types:
 
 ```bash
-# Instalar dependências
+npm install --save-dev typescript@^5.0.0
+```
+
+```typescript
+// Use proper type imports
+import type { AgentConfig, AgentInput, AgentOutput } from '@runflow-ai/sdk';
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the project
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Local Development
+
+```bash
+# Install dependencies
 npm install
 
 # Build
@@ -1410,32 +2556,32 @@ npm run build
 # Watch mode
 npm run dev
 
-# Testes
+# Tests
 npm test
 
-# Validar antes de publicar
+# Validate before publishing
 npm run validate
 ```
 
 ---
 
-## 📄 Licença
+## 📄 License
 
-MIT License - veja [LICENSE](LICENSE) para detalhes.
+MIT License - see [LICENSE](LICENSE) for details.
 
 ---
 
 ## 🔗 Links
 
 - **Homepage**: https://runflow.ai
-- **Documentação**: https://docs.runflow.ai
+- **Documentation**: https://docs.runflow.ai
 - **GitHub**: https://github.com/runflow-ai/runflow-sdk
 - **NPM**: https://www.npmjs.com/package/@runflow-ai/sdk
 - **Discord**: https://discord.gg/runflow
 
 ---
 
-## 💡 Suporte
+## 💡 Support
 
 - 📧 Email: support@runflow.ai
 - 💬 Discord: https://discord.gg/runflow
@@ -1443,5 +2589,4 @@ MIT License - veja [LICENSE](LICENSE) para detalhes.
 
 ---
 
-**Feito com ❤️ pela equipe Runflow**
-
+**Built with ❤️ by the Runflow team**