@runflow-ai/sdk 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,656 @@
+# 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
+  searchVectorStore,   // Buscar em knowledge base
+  getSession,         // Gerenciar sessão
+  log,               // Log estruturado
+  trace             // Tracing para LangSmith
+} 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 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 para LangSmith
+const trace = await sdk.trace({
+  operation: 'agent.search',
+  inputs: {
+    query: 'Como configurar pagamentos?',
+    vectorStore: 'knowledge-base'
+  },
+  outputs: {
+    results: searchResults.results.length,
+    answered: true
+  },
+  status: 'success',
+  metadata: {
+    model: 'gpt-4',
+    tokens: 150
+  }
+});
+
+console.log(`Trace ID: ${trace.traceId}`);
+```
+
+## 🏗️ Arquitetura
+
+### Classes Principais
+
+#### `RunflowSDK`
+Classe principal que oferece acesso a todos os recursos da plataforma:
+
+```typescript
+class RunflowSDK {
+  constructor(context?: AgentContext)
+  
+  // Métodos principais
+  async getCredential(name: string): Promise<Credential>
+  async getPrompt(name: string, variables?: Record<string, any>): Promise<string>
+  async getAvailableVectorStores(): Promise<VectorStore[]>
+  async searchVectorStore(vectorStore: string, query: string, options?: SearchOptions): Promise<SearchResponse>
+  log(message: string, data?: any): void
+  async trace(traceData?: TraceData): Promise<TraceResponse>
+  
+  // Propriedades
+  session: { get(sessionId: string): SessionManager }
+}
+```
+
+#### `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
+  userId?: string;          // ID do usuário
+  sessionId?: string;       // ID da sessão
+  companyId?: string;       // ID da empresa
+  channel?: string;         // Canal de origem
+  metadata?: Record<string, any>; // Metadados adicionais
+}
+```
+
+#### `AgentOutput`
+Saída padrão dos handlers:
+
+```typescript
+interface AgentOutput {
+  success: boolean;
+  data?: {
+    answer: string;           // Resposta do agente
+    answered_by?: string;     // Quem respondeu
+    sources?: any[];          // Fontes utilizadas
+    metadata?: any[];         // Metadados da resposta
+  };
+  error?: string;             // Erro (se houver)
+}
+```
+
+## 🌍 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`)
+
+## 📚 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 Commands
+
+The SDK provides helper methods for common operations:
+
+- `login`
+- `tenants`
+- `agents` – list, get, create, update, delete, clone, deploy
+- `health`
+- `prompts`
+- `connectors`
+- `credentials`
+- `getCredential`
+- `datasources`
+- `triggers`
+- `executions`
+- `users` – list, get, create, update, delete
+- `searchTools`
+- `searchVectorStore`
+- `session`
+- `trace`
+
+### 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
+
+```typescript
+import { RunflowSDK } from '@runflow-ai/sdk';
+
+const sdk = new RunflowSDK({ tenantId: 't', agentId: 'a', requestId: 'r' });
+const content = await sdk.getPrompt('welcome');
+console.log(content);
+```
+
+### Example: create user
+
+```typescript
+import { RunflowSDK } from '@runflow-ai/sdk';
+
+const sdk = new RunflowSDK({ tenantId: 't', agentId: 'a', requestId: 'r' });
+const user = await sdk.createUser({ email: 'user@example.com' });
+console.log(user);
+```
+
+### 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

package/dist/agents/runflow-agent.d.ts

@@ -0,0 +1,53 @@
+import { RunflowSDK } from '../runflow-sdk';
+import { AgentInput, AgentOutput } from '../types';
+export interface RunflowTool {
+    name: string;
+    description: string;
+    parameters: Record<string, {
+        type: 'string' | 'number' | 'boolean';
+        required?: boolean;
+        description?: string;
+    }>;
+    execute: (params: any, context: ToolContext) => Promise<any>;
+}
+export interface ToolContext {
+    sdk: RunflowSDK;
+    companyId: string;
+    userId?: string;
+    sessionId?: string;
+}
+export interface RunflowAgentConfig {
+    llm: {
+        provider: 'anthropic' | 'openai';
+        model: string;
+        credential: string;
+        temperature?: number;
+    };
+    systemPrompt: string;
+    toolsPath?: string;
+    tools?: string[];
+    customTools?: Record<string, RunflowTool>;
+    session?: {
+        enabled?: boolean;
+        historyLimit?: number;
+    };
+}
+export declare class RunflowAgent {
+    private sdk;
+    private config;
+    private llm;
+    private tools;
+    private systemPromptContent;
+    constructor(config: RunflowAgentConfig);
+    private initialize;
+    private loadTools;
+    private loadCustomToolsFromPath;
+    private isRunflowTool;
+    private createDynamicTool;
+    private currentCompanyId;
+    private currentUserId?;
+    private currentSessionId?;
+    process(input: AgentInput): Promise<AgentOutput>;
+    createHandler(): (input: AgentInput) => Promise<AgentOutput>;
+}
+//# sourceMappingURL=runflow-agent.d.ts.map

package/dist/agents/runflow-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runflow-agent.d.ts","sourceRoot":"","sources":["../../src/agents/runflow-agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAUnD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QACzB,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;QACtC,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IACH,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,UAAU,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE;QACH,QAAQ,EAAE,WAAW,GAAG,QAAQ,CAAC;QACjC,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,GAAG,CAAa;IACxB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,mBAAmB,CAAc;gBAE7B,MAAM,EAAE,kBAAkB;YAKxB,UAAU;YA6BV,SAAS;YAkCT,uBAAuB;IA4BrC,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,iBAAiB;IAgCzB,OAAO,CAAC,gBAAgB,CAAc;IACtC,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,gBAAgB,CAAC,CAAS;IAE5B,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IA4FtD,aAAa,KACG,OAAO,UAAU,KAAG,OAAO,CAAC,WAAW,CAAC;CAIzD"}