@runflow-ai/sdk 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,893 @@
+# Runflow SDK
+
+Uma SDK completa para desenvolvimento de agentes na plataforma Runflow, oferecendo integração fácil e poderosa com os serviços da plataforma.
+
+## 📦 Instalação
+
+```bash
+npm install @runflow-ai/sdk
+```
+
+## ⚙️ Configuração
+
+### Arquivo .runflow
+
+Para usar o SDK, crie um arquivo `.runflow` na raiz do seu projeto com as seguintes configurações:
+
+```json
+{
+  "agentId": "123-456-789",
+  "tenantId": "tenant-123", 
+  "apiKey": "sk-...",
+  "apiUrl": "https://api.runflow.ai"
+}
+```
+
+O SDK carregará automaticamente essas configurações e definirá as seguintes variáveis de ambiente:
+- `RUNFLOW_AGENT_ID`
+- `RUNFLOW_TENANT_ID`
+- `RUNFLOW_API_KEY`
+- `RUNFLOW_API_URL`
+
+> **Nota:** O arquivo `.runflow` é buscado a partir do diretório atual, subindo na hierarquia até encontrar o arquivo ou chegar na raiz do sistema.
+
+### Configuração Manual (Alternativa)
+
+Se preferir, você pode definir as variáveis de ambiente manualmente:
+
+```bash
+export RUNFLOW_AGENT_ID="123-456-789"
+export RUNFLOW_TENANT_ID="tenant-123"
+export RUNFLOW_API_KEY="sk-..."
+export RUNFLOW_API_URL="https://api.runflow.ai"
+```
+
+### Utilitários de Configuração
+
+O SDK fornece funções utilitárias para gerenciar configurações:
+
+```typescript
+import { 
+  loadRunflowConfig, 
+  ensureRunflowConfig, 
+  checkEnvironmentVariables 
+} from '@runflow-ai/sdk';
+
+// Carregar configurações manualmente (opcional - feito automaticamente no construtor)
+const config = loadRunflowConfig();
+
+// Forçar carregamento e falhar se não encontrar
+const config = ensureRunflowConfig();
+
+// Verificar se todas as variáveis estão definidas
+const hasAllVars = checkEnvironmentVariables();
+```
+
+## 🚀 Início Rápido
+
+Agora você tem **4 formas diferentes** de usar o SDK, desde a mais simples até a mais avançada:
+
+### 1. 🎯 **Forma Ultra-Simples** (Recomendada para iniciantes)
+
+```typescript
+import { getPrompt, getCredential, log } from '@runflow-ai/sdk';
+
+export const handler = async (input, context) => {
+  // Usa singleton interno - sem "new" necessário!
+  const prompt = await getPrompt('welcome-message');
+  const credential = await getCredential('azure-gpt4');
+  
+  log('Handler executado', { message: input.message });
+  
+  return {
+    success: true,
+    data: {
+      answer: prompt,
+      answered_by: "assistant"
+    }
+  };
+};
+```
+
+### 2. ⚡ **Forma Simplificada com Helper**
+
+```typescript
+import { createAgentHandler } from '@runflow-ai/sdk';
+
+export const handler = createAgentHandler(async (sdk, input, context) => {
+  // SDK já vem pronto, sem instanciar!
+  const prompt = await sdk.getPrompt('welcome-message');
+  
+  return {
+    success: true,
+    data: {
+      answer: prompt,
+      answered_by: "assistant"
+    }
+  };
+});
+```
+
+### 3. 🔄 **Forma com Singleton Explícito**
+
+```typescript
+import { getSDK } from '@runflow-ai/sdk';
+
+export const handler = async (input, context) => {
+  const sdk = getSDK(context); // Reutiliza a mesma instância
+  const prompt = await sdk.getPrompt('welcome-message');
+  
+  return {
+    success: true,
+    data: {
+      answer: prompt,
+      answered_by: "assistant"
+    }
+  };
+};
+```
+
+### 4. 🛠️ **Forma Tradicional** (Para casos avançados)
+
+```typescript
+import { RunflowSDK, createHandler } from '@runflow-ai/sdk';
+
+export const handler = createHandler(async (input, context) => {
+  const sdk = new RunflowSDK(context); // Nova instância sempre
+  
+  return {
+    success: true,
+    data: {
+      answer: "Olá! Como posso ajudar?",
+      answered_by: "assistant"
+    }
+  };
+});
+```
+
+### 🤔 **Qual Forma Usar?**
+
+| Cenário | Forma Recomendada | Por que? |
+|---------|-------------------|-----------|
+| **Agente simples, poucos métodos** | 🎯 Ultra-Simples | Menos código, mais direto |
+| **Agente complexo, muitos métodos SDK** | ⚡ Helper `createAgentHandler` | SDK injetado, tipagem completa |
+| **Múltiplos handlers no mesmo arquivo** | 🔄 Singleton Explícito | Reutiliza instância, melhor performance |
+| **Controle total sobre instância** | 🛠️ Tradicional | Máxima flexibilidade |
+| **Testes unitários** | 🛠️ Tradicional + `resetSDK()` | Isolamento entre testes |
+
+### 💡 **Funções de Conveniência Disponíveis**
+
+```typescript
+// Todas essas funções usam o singleton interno
+import { 
+  getCredential,        // Buscar credencial
+  getPrompt,           // Buscar prompt
+  getAvailableVectorStores, // Listar vector stores
+  searchVectorStore,   // Buscar em knowledge base
+  addDocument,         // Adicionar documento ao vector store
+  listDocuments,       // Listar documentos do vector store
+  deleteDocument,      // Remover documento do vector store
+  getSession,         // Gerenciar sessão
+  log,               // Log estruturado
+  trace,            // Tracing e observabilidade
+  // Utilitários
+  validateAgentInput,   // Validação de entrada
+  sanitizeMetadata,     // Limpeza de metadados
+  maskSensitiveData,    // Mascarar dados sensíveis
+  HttpClient,           // Cliente HTTP com retry
+  batchRequests,        // Requests em lote
+  withTimeout,          // Timeout para promises
+  debounce             // Debounce para funções
+} from '@runflow-ai/sdk';
+```
+
+## 🔧 Funcionalidades Principais
+
+### 🔐 Gerenciamento de Credenciais
+
+O SDK fornece acesso seguro às credenciais configuradas na plataforma:
+
+```typescript
+// Buscar uma credencial específica
+const credential = await sdk.getCredential('api-key-openai');
+
+console.log(credential.name);    // 'api-key-openai'
+console.log(credential.type);    // 'API_KEY', 'OAUTH', ou 'JWT'
+console.log(credential.apiKey);  // A chave de acesso
+console.log(credential.config);  // Configurações adicionais
+```
+
+**Tipos de Credenciais Suportadas:**
+- `API_KEY`: Chaves de API simples
+- `OAUTH`: Tokens OAuth
+- `JWT`: JSON Web Tokens
+
+### 📝 Sistema de Prompts
+
+Gerencie e utilize prompts dinâmicos com variáveis:
+
+```typescript
+// Prompt simples
+consgit stt prompt = await sdk.getPrompt('greeting');
+
+// Prompt com variáveis
+const prompt = await sdk.getPrompt('personalized-greeting', {
+  name: 'João',
+  company: 'Acme Corp'
+});
+
+// O prompt pode conter: "Olá {{name}}, bem-vindo à {{company}}!"
+// Resultado: "Olá João, bem-vindo à Acme Corp!"
+```
+
+### 🔍 Busca em Vector Stores
+
+Realize buscas semânticas em bases de conhecimento:
+
+```typescript
+// Listar vector stores disponíveis
+const vectorStores = await sdk.getAvailableVectorStores();
+
+vectorStores.forEach(store => {
+  console.log(`${store.name}: ${store.description} (${store.type})`);
+});
+
+// Realizar busca semântica
+const searchResults = await sdk.searchVectorStore(
+  'knowledge-base',
+  'Como configurar pagamentos?',
+  {
+    k: 5,           // Número de resultados
+    threshold: 0.7  // Threshold de similaridade
+  }
+);
+
+searchResults.results.forEach(result => {
+  console.log(`Score: ${result.score}`);
+  console.log(`Conteúdo: ${result.content}`);
+  console.log(`Fonte: ${result.metadata.source}`);
+});
+```
+
+**Tipos de Vector Stores Suportados:**
+- Pinecone
+- Weaviate  
+- Qdrant
+
+### 📄 Gerenciamento de Documentos
+
+Gerencie documentos nos vector stores:
+
+```typescript
+// Adicionar um documento
+const documentResponse = await sdk.addDocument({
+  vectorStore: 'knowledge-base',
+  content: 'Como configurar pagamentos via PIX...',
+  metadata: {
+    source: 'manual-pagamentos.pdf',
+    category: 'financeiro',
+    version: '1.0'
+  }
+});
+
+console.log(`Documento adicionado: ${documentResponse.id}`);
+
+// Listar documentos
+const documents = await sdk.listDocuments('knowledge-base', {
+  limit: 20,
+  offset: 0
+});
+
+console.log(`Total de documentos: ${documents.total}`);
+documents.documents.forEach(doc => {
+  console.log(`${doc.id}: ${doc.content.substring(0, 100)}...`);
+});
+
+// Remover um documento
+const deleteResult = await sdk.deleteDocument('doc-123');
+console.log(`Documento removido: ${deleteResult.success}`);
+```
+
+### 💬 Gerenciamento de Sessões
+
+Mantenha contexto e histórico de conversas:
+
+```typescript
+// Obter gerenciador de sessão
+const session = sdk.session.get('session-123');
+
+// Adicionar mensagens
+await session.addMessage('human', 'Qual é o status do meu pedido?');
+await session.addMessage('ai', 'Seu pedido #1234 está em processamento.');
+
+// Buscar histórico
+const history = await session.getHistory({
+  limit: 10,
+  offset: 0
+});
+
+history.forEach(message => {
+  console.log(`[${message.role}] ${message.content}`);
+  console.log(`Timestamp: ${message.timestamp}`);
+});
+
+// Limpar histórico
+await session.clear();
+```
+
+### 📊 Logs e Tracing
+
+Sistema completo de observabilidade:
+
+```typescript
+// Log simples
+sdk.log('Processando requisição do usuário');
+
+// Log com dados estruturados
+sdk.log('Busca realizada', {
+  query: 'pagamentos',
+  results: 5,
+  vectorStore: 'knowledge-base'
+});
+
+// Enviar trace - Formato Padrão (Recomendado)
+const trace = await sdk.trace({
+  input: [
+    { type: 'human', content: 'Como configurar pagamentos?' },
+    { type: 'system', content: 'Contexto adicional...' }
+  ],
+  output: 'Para configurar pagamentos via PIX...',
+  status: 'success'
+});
+
+console.log(`Trace ID: ${trace.traceId}`);
+```
+
+## 🛠️ Utilitários
+
+### Validação e Segurança
+
+```typescript
+import { validateAgentInput, sanitizeMetadata, maskSensitiveData } from '@runflow-ai/sdk';
+
+// Validar entrada do agente
+const validation = validateAgentInput(input, {
+  requireCompanyId: true,
+  maxMessageLength: 5000,
+  allowedChannels: ['web', 'whatsapp', 'telegram']
+});
+
+if (!validation.isValid) {
+  console.log('Errors:', validation.errors);
+  return { success: false, error: validation.errors.join(', ') };
+}
+
+// Usar entrada sanitizada
+const cleanInput = validation.sanitized;
+
+// Limpar metadados
+const cleanMetadata = sanitizeMetadata(rawMetadata, {
+  allowedKeys: ['source', 'version', 'category'],
+  maxDepth: 2,
+  maxStringLength: 500
+});
+
+// Mascarar dados sensíveis em logs
+const logData = {
+  userEmail: 'user@example.com',
+  phone: '+5511999999999',
+  password: 'secret123'
+};
+
+const maskedData = maskSensitiveData(logData);
+// Resultado: { userEmail: 'us***@example.com', phone: '***********', password: '***' }
+```
+
+### Cliente HTTP Avançado
+
+```typescript
+import { HttpClient, batchRequests, withTimeout, debounce } from '@runflow-ai/sdk';
+
+// Cliente HTTP com retry automático
+const client = new HttpClient();
+
+const response = await client.post('https://api.external.com/data', {
+  query: 'example'
+}, {
+  timeout: 5000,
+  retries: 3,
+  retryDelay: 1000
+});
+
+// Requests em lote com controle de concorrência
+const requests = [
+  () => client.get('/api/data/1'),
+  () => client.get('/api/data/2'),
+  () => client.get('/api/data/3')
+];
+
+const results = await batchRequests(requests, { concurrent: 2 });
+
+// Timeout para qualquer Promise
+const timedResult = await withTimeout(
+  sdk.searchVectorStore('knowledge', 'query'),
+  3000
+);
+
+// Debounce para buscas
+const debouncedSearch = debounce(async (query: string) => {
+  return await sdk.searchVectorStore('knowledge', query);
+}, 300);
+```
+
+## 🏗️ Arquitetura
+
+### Classes Principais
+
+#### `RunflowSDK`
+Classe principal que oferece acesso a todos os recursos da plataforma:
+
+```typescript
+class RunflowSDK {
+  constructor(context?: AgentContext)
+  
+  // 🔐 Credenciais
+  async getCredential(name: string): Promise<Credential>
+  
+  // 📝 Prompts
+  async getPrompt(name: string, variables?: Record<string, any>): Promise<string>
+  
+  // 🔍 Vector Stores & Busca
+  async getAvailableVectorStores(): Promise<VectorStore[]>
+  async searchVectorStore(vectorStore: string, query: string, options?: SearchOptions): Promise<SearchResponse>
+  
+  // 📄 Gerenciamento de Documentos
+  async addDocument(request: AddDocumentRequest): Promise<AddDocumentResponse>
+  async listDocuments(vectorStore: string, options?: ListDocumentsOptions): Promise<ListDocumentsResponse>
+  async deleteDocument(documentId: string): Promise<DeleteDocumentResponse>
+  
+  // 📊 Observabilidade
+  log(message: string, data?: any): void
+  async trace(traceData: TraceData): Promise<TraceResponse>
+  
+  // 💬 Sessões
+  session: { get(sessionId: string): SessionManager }
+  
+  // ⚙️ Utilitários
+  async health(): Promise<any>
+}
+```
+
+#### `SessionManager`
+Gerenciador de sessões e histórico de conversas:
+
+```typescript
+class SessionManager {
+  async addMessage(role: 'human' | 'ai', content: string, metadata?: any): Promise<void>
+  async getHistory(options?: SessionHistoryOptions): Promise<SessionMessage[]>
+  async clear(): Promise<void>
+}
+```
+
+### Interfaces e Tipos
+
+#### `AgentContext`
+Contexto de execução do agente:
+
+```typescript
+interface AgentContext {
+  tenantId: string;     // ID do tenant
+  agentId: string;      // ID do agente
+  requestId: string;    // ID da requisição
+  sessionId?: string;   // ID da sessão (opcional)
+  companyId?: string;   // ID da empresa (opcional)
+}
+```
+
+#### `AgentInput`
+Entrada padrão dos handlers:
+
+```typescript
+interface AgentInput {
+  message: string;           // Mensagem do usuário
+  companyId: string;        // ID da empresa (obrigatório)
+  userId?: string;          // ID do usuário
+  sessionId?: string;       // ID da sessão
+  channel?: string;         // Canal de origem
+  metadata?: Record<string, any>; // Metadados adicionais
+  // Compatibilidade com versões antigas
+  tab?: string;
+  preChatInfo?: string;
+}
+```
+
+#### `AgentOutput`
+Saída padrão dos handlers:
+
+```typescript
+interface AgentOutput {
+  message: string;          // Resposta do agente
+  metadata?: {
+    llmProvider?: string;   // Provedor do LLM usado
+    model?: string;         // Modelo usado
+    toolsUsed?: string[];   // Ferramentas utilizadas
+    steps?: number;         // Número de passos executados
+    [key: string]: any;     // Metadados adicionais
+  };
+}
+```
+
+## 🌍 Variáveis de Ambiente
+
+O SDK utiliza as seguintes variáveis de ambiente, automaticamente configuradas pela plataforma Runflow:
+
+### Obrigatórias
+- `RUNFLOW_TENANT_ID`: ID do tenant
+- `RUNFLOW_AGENT_ID`: ID do agente
+- `RUNFLOW_API_KEY`: Chave de API para autenticação
+
+### Opcionais
+- `RUNFLOW_REQUEST_ID`: ID da requisição (gerado automaticamente se não fornecido)
+- `RUNFLOW_SESSION_ID`: ID da sessão
+- `RUNFLOW_API_URL`: URL da API (padrão: `http://localhost:3001`)
+
+## 🤖 Agentes Avançados
+
+O SDK inclui suporte completo para criação de agentes inteligentes:
+
+### `RunflowAgent`
+Classe para criar agentes inteligentes com IA e ferramentas:
+
+```typescript
+import { RunflowAgent } from '@runflow-ai/sdk';
+
+const agent = new RunflowAgent({
+  llm: {
+    provider: 'anthropic', // ou 'openai'
+    model: 'claude-3-sonnet',
+    credential: 'claude-api',
+    temperature: 0.7
+  },
+  systemPrompt: 'customer-support', // Nome do prompt na plataforma
+  toolsPath: './tools', // Pasta com ferramentas customizadas
+  tools: ['search-knowledge'], // Ferramentas built-in
+  session: {
+    enabled: true,
+    historyLimit: 10
+  }
+});
+
+// Processar mensagem
+const response = await agent.process({
+  message: 'Como posso cancelar meu pedido?',
+  companyId: 'company-123',
+  userId: 'user-456',
+  sessionId: 'session-789'
+});
+
+console.log(response.message);
+```
+
+### Ferramentas Customizadas
+Crie ferramentas que o agente pode usar:
+
+```typescript
+// tools/order-lookup.ts
+export const orderLookup = {
+  name: 'order_lookup',
+  description: 'Busca informações de um pedido pelo ID',
+  parameters: {
+    orderId: {
+      type: 'string',
+      required: true,
+      description: 'ID do pedido'
+    }
+  },
+  execute: async (params: { orderId: string }, context: ToolContext) => {
+    // Usar o SDK dentro da ferramenta
+    const orderData = await fetch(`/api/orders/${params.orderId}`);
+    
+    // Log da operação
+    context.sdk.log('Pedido consultado', {
+      orderId: params.orderId,
+      companyId: context.companyId
+    });
+    
+    return orderData;
+  }
+};
+```
+
+### Servidor de Agente
+Crie um servidor HTTP completo para seu agente:
+
+```typescript
+import { createAgentServer } from '@runflow-ai/sdk';
+
+const server = createAgentServer({
+  llm: {
+    provider: 'anthropic',
+    model: 'claude-3-sonnet',
+    credential: 'claude-api'
+  },
+  systemPrompt: 'customer-support',
+  toolsPath: './tools'
+}, {
+  port: 3000,
+  cors: true,
+  rateLimiting: true,
+  tracing: true, // Trace automático
+  hooks: {
+    beforeChat: async (req, res) => {
+      // Validações customizadas
+      console.log('Nova conversa iniciada');
+    },
+    afterChat: async (input, output, ctx) => {
+      // Pós-processamento
+      console.log(`Conversa processada em ${ctx.durationMs}ms`);
+    }
+  }
+});
+
+server.start(); // Inicia na porta 3000
+```
+
+## 📚 Exemplos Avançados
+
+### Agente com Busca em Conhecimento
+
+```typescript
+import { createAgentHandler } from '@runflow-ai/sdk';
+
+export const handler = createAgentHandler(async (sdk, input, context) => {
+  try {
+    // Buscar informações relacionadas
+    const searchResults = await sdk.searchVectorStore(
+      'company-knowledge',
+      input.message,
+      { k: 3, threshold: 0.8 }
+    );
+
+    // Preparar contexto para o prompt
+    const context_info = searchResults.results
+      .map(r => r.content)
+      .join('\n\n');
+
+    // Buscar prompt personalizado
+    const prompt = await sdk.getPrompt('answer-with-context', {
+      question: input.message,
+      context: context_info,
+      user_id: input.userId
+    });
+
+    // Log da operação
+    sdk.log('Busca realizada', {
+      query: input.message,
+      results: searchResults.results.length,
+      sources: searchResults.results.map(r => r.metadata.source)
+    });
+
+    // Trace para observabilidade
+    await sdk.trace({
+      operation: 'knowledge.search',
+      inputs: { query: input.message },
+      outputs: { results: searchResults.results.length },
+      status: 'success'
+    });
+
+    return {
+      success: true,
+      data: {
+        answer: prompt,
+        answered_by: 'knowledge-agent',
+        sources: searchResults.results.map(r => ({
+          content: r.content,
+          source: r.metadata.source,
+          score: r.score
+        }))
+      }
+    };
+
+  } catch (error) {
+    sdk.log('Erro no agente', error);
+    
+    await sdk.trace({
+      operation: 'knowledge.search',
+      inputs: { query: input.message },
+      status: 'error',
+      error: error.message
+    });
+
+    return {
+      success: false,
+      error: 'Desculpe, ocorreu um erro interno.'
+    };
+  }
+});
+```
+
+### Agente com Integração Externa
+
+```typescript
+import { createAgentHandler } from '@runflow-ai/sdk';
+
+export const handler = createAgentHandler(async (sdk, input, context) => {
+  // Buscar credenciais para API externa
+  const apiCredential = await sdk.getCredential('external-api-key');
+  
+  // Fazer chamada para API externa
+  const response = await fetch('https://api.externa.com/data', {
+    headers: {
+      'Authorization': `Bearer ${apiCredential.apiKey}`,
+      'Content-Type': 'application/json'
+    },
+    method: 'POST',
+    body: JSON.stringify({ query: input.message })
+  });
+
+  const data = await response.json();
+
+  // Gerenciar sessão
+  const session = sdk.session.get(input.sessionId || 'default');
+  await session.addMessage('human', input.message);
+  
+  const answer = `Baseado nos dados externos: ${data.result}`;
+  await session.addMessage('ai', answer);
+
+  return {
+    success: true,
+    data: {
+      answer,
+      answered_by: 'external-api-agent',
+      metadata: [{ external_data: data }]
+    }
+  };
+});
+```
+
+## 🔧 Desenvolvimento e Debug
+
+### Configuração Local
+
+Para desenvolvimento local, você pode configurar as variáveis de ambiente manualmente:
+
+```bash
+export RUNFLOW_TENANT_ID="your-tenant-id"
+export RUNFLOW_AGENT_ID="your-agent-id"
+export RUNFLOW_API_KEY="your-api-key"
+export RUNFLOW_API_URL="http://localhost:3001"
+```
+
+### Debug de Sessões
+
+```typescript
+// Verificar estado da sessão
+const history = await session.getHistory({ limit: 50 });
+console.log(`Sessão tem ${history.length} mensagens`);
+
+// Log detalhado
+sdk.log('Estado da sessão', {
+  sessionId: input.sessionId,
+  messageCount: history.length,
+  lastMessage: history[0]?.content
+});
+```
+
+## 🚨 Tratamento de Erros
+
+O SDK fornece tratamento robusto de erros:
+
+```typescript
+try {
+  const credential = await sdk.getCredential('non-existent');
+} catch (error) {
+  if (error.message.includes('HTTP 404')) {
+    console.log('Credencial não encontrada');
+  } else if (error.message.includes('RUNFLOW_API_KEY')) {
+    console.log('SDK não configurado corretamente');
+  } else {
+    console.log('Erro desconhecido:', error.message);
+  }
+}
+```
+
+### Erros Comuns
+
+1. **Variáveis de ambiente não configuradas**: Certifique-se de que o agente está sendo executado na plataforma Runflow
+2. **Credencial não encontrada**: Verifique se a credencial foi configurada na plataforma
+3. **Vector store indisponível**: Confirme se o vector store está ativo e acessível
+4. **Prompt não encontrado**: Verifique se o prompt foi criado na plataforma
+
+## 🌐 English Version
+
+For English speakers, here's a concise overview of the SDK:
+
+### Basic Usage
+
+```typescript
+import { createHandler } from '@runflow-ai/sdk';
+
+export const handler = createHandler(async (input, context) => {
+  return { success: true };
+});
+```
+
+### Available Methods
+
+The SDK provides essential methods for daily development:
+
+- `getCredential` – Get API credentials
+- `getPrompt` – Get prompts with variable substitution
+- `getAvailableVectorStores` – List available vector stores
+- `searchVectorStore` – Semantic search in knowledge base
+- `addDocument` – Add documents to vector store
+- `listDocuments` – List documents in vector store
+- `deleteDocument` – Remove documents from vector store
+- `session.get()` – Session management
+- `log` – Structured logging
+- `trace` – Send traces for observability
+- `health` – Health check
+
+### Example: Health check
+
+```typescript
+import { RunflowSDK } from '@runflow-ai/sdk';
+
+const sdk = new RunflowSDK({ tenantId: 't', agentId: 'a', requestId: 'r' });
+const status = await sdk.health();
+console.log(status);
+```
+
+### Example: Fetch prompt with variables
+
+```typescript
+import { RunflowSDK } from '@runflow-ai/sdk';
+
+const sdk = new RunflowSDK({ tenantId: 't', agentId: 'a', requestId: 'r' });
+const content = await sdk.getPrompt('welcome', {
+  userName: 'João',
+  company: 'Acme Corp'
+});
+console.log(content);
+```
+
+### Example: Search knowledge base
+
+```typescript
+import { searchVectorStore } from '@runflow-ai/sdk';
+
+const results = await searchVectorStore(
+  'knowledge-base',
+  'How to configure payments?',
+  { k: 5, threshold: 0.8 }
+);
+
+results.results.forEach(result => {
+  console.log(`${result.score}: ${result.content}`);
+});
+```
+
+### Flow Diagram
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant SDK
+    participant API
+    Client->>SDK: createHandler(fn)
+    SDK->>API: calls /sdk endpoints
+    API-->>SDK: responses
+```
+
+## 📄 Licença
+
+MIT License - veja o arquivo LICENSE para detalhes.
+
+## 🤝 Contribuindo
+
+Contribuições são bem-vindas! Por favor, abra uma issue ou pull request no repositório do projeto.
+
+## 📞 Suporte
+
+Para suporte técnico, entre em contato através dos canais oficiais da Runflow ou consulte a documentação completa da plataforma.
+>>>>>>> 6435d75437a22d2d974b5406d5c881d3d016d76d