Skip to main content

​
API Client Not Configured

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
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'),
});

agent._setAPIClient(apiClient);

​
Memory Not Persisting

Issue: Memory is not persisting between sessions Solution: Ensure you’re passing the same sessionId or using identify() consistently: 
import { identify } from '@runflow-ai/sdk/observability';

// Use identify() for automatic session management
identify('+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
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
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: 
npm install --save-dev typescript@^5.0.0

// Use proper type imports
import type { AgentConfig, AgentInput, AgentOutput } from '@runflow-ai/sdk';

​
Next Steps

Configuration

Review configuration

API Reference

Check API documentation