Core API Deep Dive

const agent = await client.createPersona({
  name: 'Financial Advisory Agent',
  instructions: `You are a financial advisory agent. Provide general guidance only.
    Never give specific investment advice or make financial recommendations.`,
  traits: ['professional', 'cautious', 'educational'],
  guardrails: [
    'no_financial_advice',     // Built-in financial guardrail
    'no_personal_info',        // Prevent personal data collection
    'stay_professional',       // Maintain professional tone
    'cite_sources'            // Require source citations
  ],
  model: 'gpt-4',
  temperature: 0.3,           // Lower temperature for consistency
  maxTokens: 500,             // Limit response length
  customGuardrails: {
    outputFilter: {
      enabled: true,
            monitoringModel: 'gpt-3.5-turbo',  // Cheap model for output review
      blockedPatterns: [
        'invest in',
        'guaranteed returns',
        'buy this stock'
      ]
    },
    inputSanitization: {
      enabled: true,
      removePersonalData: true,
      maxInputLength: 1000
    }
  }
});

// Creative writing agent - high creativity
const creativeAgent = await client.createPersona({
  name: 'Creative Writing Assistant',
  model: 'gpt-4',
  temperature: 0.8,        // High creativity
  topP: 0.9,              // Diverse word selection
  maxTokens: 1000,        // Longer responses
  frequencyPenalty: 0.3   // Reduce repetition
});

// Customer support agent - consistent and reliable
const supportAgent = await client.createPersona({
  name: 'Support Agent',
  model: 'gpt-4',
  temperature: 0.2,        // Low creativity, consistent responses
  topP: 0.5,              // More focused word selection
  maxTokens: 300,         // Concise responses
  presencePenalty: 0.1    // Slight topic diversity
});

// Code review agent - precise and analytical
const codeReviewAgent = await client.createPersona({
  name: 'Code Review Assistant',
  model: 'gpt-4',
  temperature: 0.1,        // Very low creativity
  maxTokens: 500,
  systemPrompt: 'Focus on code quality, security, and best practices.'
});

// Add knowledge with advanced chunking strategy
await client.addKnowledge(agentId, {
  type: 'url',
  source: 'https://docs.yourcompany.com/api',
  metadata: {
    title: 'API Documentation',
    category: 'technical',
    priority: 'high',
    version: '2.1'
  },
  processingOptions: {
    chunkingStrategy: 'sentence_window',
    chunkSize: 3,           // 3 sentences per chunk
    chunkOverlap: 1,        // 1 sentence overlap
    windowSize: 7,          // ±3 sentences context window
    enableHybridSearch: true // Combine vector + keyword search
  }
});

// Query with advanced retrieval options
const response = await client.query(agentId, {
  message: 'How do I authenticate API requests?',
  retrievalOptions: {
    maxChunks: 5,           // Limit retrieved chunks
    minSimilarity: 0.7,     // Similarity threshold
    enableReranking: true,  // Re-rank results for relevance
    hybridWeight: 0.7       // 70% vector, 30% keyword search
  }
});

// Update knowledge source with versioning
await client.updateKnowledge(knowledgeSourceId, {
  content: updatedContent,
  metadata: {
    version: '2.0',
    changelog: 'Updated API endpoints and added new examples',
    deprecated: false
  }
});

// Rollback to previous version if needed
await client.rollbackKnowledge(knowledgeSourceId, '1.5');

// Archive outdated knowledge
await client.archiveKnowledge(oldKnowledgeSourceId);

class ConversationManager {
  async handleQuery(agentId: string, message: string, userId: string) {
    // Maintain conversation context with session ID
    const sessionId = `user-${userId}-${Date.now()}`;
    
    // Get conversation history for context
    const history = await client.getSessionHistory(sessionId);
    
    // Send query with context
    const response = await client.query(agentId, {
      message,
      sessionId,
      context: {
        previousQueries: history.slice(-3), // Last 3 interactions
        userPreferences: await this.getUserPreferences(userId),
        conversationTopic: this.detectTopic(history)
      }
    });

    return response;
  }

  private detectTopic(history: any[]): string {
    // Simple topic detection based on recent messages
    const recentMessages = history.slice(-5).map(h => h.message).join(' ');
    
    if (recentMessages.includes('billing') || recentMessages.includes('payment')) {
      return 'billing';
    } else if (recentMessages.includes('technical') || recentMessages.includes('api')) {
      return 'technical';
    }
    
    return 'general';
  }
}

// Stream responses for better user experience
async function* streamQuery(agentId: string, message: string) {
  const stream = await client.queryStream(agentId, {
    message,
    stream: true
  });

  for await (const chunk of stream) {
    if (chunk.type === 'token') {
      yield chunk.content;
    } else if (chunk.type === 'metadata') {
      // Handle metadata like token usage, confidence scores
      console.log('Query metadata:', chunk.data);
    } else if (chunk.type === 'error') {
      throw new Error(chunk.message);
    }
  }
}

// Usage with async generator
const responseStream = streamQuery(agentId, userMessage);
for await (const token of responseStream) {
  process.stdout.write(token); // Real-time output
}