Examples

All examples are available on GitHub: keywordsai-example-projects/typescript/tracing_sdk_example

Setup

All examples require:

npm install @keywordsai/tracing

Configure your .env file:

.env

KEYWORDSAI_API_KEY=your_keywordsai_api_key
KEYWORDSAI_BASE_URL=https://api.keywordsai.co
OPENAI_API_KEY=your_openai_api_key  # Optional
ANTHROPIC_API_KEY=your_anthropic_api_key  # Optional

Basic Usage

From basic_usage.ts. Core concepts: withWorkflow, withTask, withAgent, withTool.

import { KeywordsAITelemetry } from '@keywordsai/tracing';

const keywordsAi = new KeywordsAITelemetry({
    apiKey: process.env.KEYWORDSAI_API_KEY,
    baseURL: process.env.KEYWORDSAI_BASE_URL,
    appName: 'basic-example',
    disableBatch: true,
    logLevel: 'info'
});

const generateResponse = async (prompt: string) => {
    return await keywordsAi.withTask(
        { name: 'generate_response', version: 1 },
        async () => {
            await new Promise(resolve => setTimeout(resolve, 100));
            return `Response to: ${prompt}`;
        }
    );
};

const chatWorkflow = async (userMessage: string) => {
    return await keywordsAi.withWorkflow(
        { 
            name: 'chat_workflow', 
            version: 1,
            associationProperties: { 'user_type': 'demo' }
        },
        async () => {
            const response = await generateResponse(userMessage);
            
            await keywordsAi.withTask(
                { name: 'log_interaction' },
                async () => {
                    console.log(`User: ${userMessage}`);
                    console.log(`Assistant: ${response}`);
                    return 'logged';
                }
            );
            
            return response;
        }
    );
};

async function main() {
    await keywordsAi.initialize();
    
    console.log('=== Workflow Example ===');
    const workflowResponse = await chatWorkflow('What is the weather like?');
    console.log('Workflow Response:', workflowResponse);
    
    await keywordsAi.shutdown();
}

main();

Run it:

npx tsx basic_usage.ts

OpenAI Integration

From openai_integration.ts. Automatic instrumentation of the OpenAI SDK.

import OpenAI from "openai";
import { KeywordsAITelemetry } from "@keywordsai/tracing";

const keywordsai = new KeywordsAITelemetry({
  apiKey: process.env.KEYWORDSAI_API_KEY,
  appName: "openai-integration-test",
  instrumentModules: {
    openAI: OpenAI,  // Automatically instrument OpenAI SDK
  },
  logLevel: 'info'
});

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

async function runOpenAIIntegrationTest() {
  console.log("🚀 Starting OpenAI Integration Test\n");

  await keywordsai.initialize();

  await keywordsai.withWorkflow(
    { name: "openai_chat_completion" },
    async () => {
      console.log("📝 Sending request to OpenAI...");
      
      const completion = await openai.chat.completions.create({
        model: "gpt-3.5-turbo",
        messages: [
            { role: "system", content: "You are a helpful assistant." },
            { role: "user", content: "Tell me a short joke about programming." }
        ],
      });

      console.log("📥 OpenAI Response:", completion.choices[0].message.content);
    }
  );

  await keywordsai.shutdown();
  console.log("✅ Done!");
}

runOpenAIIntegrationTest();

Run it:

npx tsx openai_integration.ts

Advanced Agentic Workflow

From advanced_tracing.ts. Demonstrates withAgent, withTool, and custom metadata for complex agent workflows.

import { KeywordsAITelemetry } from '@keywordsai/tracing';
import OpenAI from 'openai';

const keywordsAi = new KeywordsAITelemetry({
    apiKey: process.env.KEYWORDSAI_API_KEY,
    baseURL: process.env.KEYWORDSAI_BASE_URL,
    appName: 'advanced-tracing-example',
    instrumentModules: {
        openAI: OpenAI,
    },
    disableBatch: true,
    logLevel: 'info'
});

const openai = new OpenAI({
    apiKey: process.env.OPENAI_API_KEY,
});

const runAgentExample = async (query: string) => {
    return await keywordsAi.withAgent(
        { 
            name: 'research_assistant',
            associationProperties: { 
                'user_id': 'user_123',
                'session_id': 'session_abc' 
            }
        },
        async () => {
            console.log(`🤖 Agent received query: ${query}`);

            // Tool 1: Query analyzer
            const analysis = await keywordsAi.withTool(
                { name: 'query_analyzer' },
                async () => {
                    console.log('🔍 Analyzing query...');
                    await new Promise(resolve => setTimeout(resolve, 300));
                    return {
                        topic: query.toLowerCase().includes('ai') ? 'technology' : 'general',
                        sentiment: 'neutral'
                    };
                }
            );

            // Tool 2: Web search
            const searchResults = await keywordsAi.withTool(
                { name: 'web_search' },
                async () => {
                    console.log('🌐 Searching the web...');
                    return `Found some information about ${analysis.topic}`;
                }
            );

            // Task: Final generation with OpenAI
            const finalResponse = await keywordsAi.withTask(
                { name: 'final_generation' },
                async () => {
                    console.log('✍️ Generating final response...');
                    const completion = await openai.chat.completions.create({
                        model: 'gpt-3.5-turbo',
                        messages: [
                            { role: 'system', content: `You are a research assistant. Topic: ${analysis.topic}. Info: ${searchResults}` },
                            { role: 'user', content: query }
                        ],
                    });
                    return completion.choices[0].message.content;
                }
            );

            return {
                analysis,
                searchResults,
                finalResponse
            };
        }
    );
};

async function main() {
    await keywordsAi.initialize();
    console.log('🚀 Starting Advanced Tracing Example\n');

    const result = await runAgentExample('How is AI changing software development?');
    console.log('\n✨ Agent Execution Result:', JSON.stringify(result, null, 2));

    await keywordsAi.shutdown();
}

main();

Run it:

npx tsx advanced_tracing.ts

Span Management

Using getClient() API to manually update spans, add events, and record exceptions.

import { KeywordsAITelemetry } from '@keywordsai/tracing';

const keywordsAi = new KeywordsAITelemetry({
    apiKey: process.env.KEYWORDSAI_API_KEY,
    appName: 'span-management-example',
});

await keywordsAi.initialize();

await keywordsAi.withTask(
    { name: 'data_processing' },
    async () => {
        const client = keywordsAi.getClient();
        
        // Update current span with custom metadata
        client.updateCurrentSpan({
            keywordsai_params: {
                customer_identifier: 'user_123',
                metadata: { stage: 'processing' }
            },
            attributes: { 'custom.stage': 'validation' }
        });
        
        // Add an event to the span
        client.addSpanEvent('validation_started', { 
            input_length: 100 
        });
        
        try {
            // Your processing logic here
            const data = await processData();
            
            // Record success
            client.updateCurrentSpan({
                status: 'OK',
                attributes: { 'validation.result': 'success' }
            });
            
            return data;
        } catch (error) {
            // Record exception
            client.recordSpanException(error);
            client.updateCurrentSpan({
                status: 'ERROR',
                attributes: { 'validation.result': 'failed' }
            });
            throw error;
        }
    }
);

await keywordsAi.shutdown();

Multi-Provider Tracing

From multi_provider.ts. Trace across multiple AI providers (OpenAI + Anthropic) in a single workflow.

import OpenAI from 'openai';
import Anthropic from '@anthropic-ai/sdk';
import { KeywordsAITelemetry } from '@keywordsai/tracing';

const keywordsAi = new KeywordsAITelemetry({
    apiKey: process.env.KEYWORDSAI_API_KEY,
    appName: 'multi-provider-example',
    instrumentModules: {
        openAI: OpenAI,
        anthropic: Anthropic
    }
});

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

await keywordsAi.initialize();

await keywordsAi.withWorkflow(
    { name: 'multi_provider_comparison' },
    async () => {
        // OpenAI call
        const openaiResponse = await keywordsAi.withTask(
            { name: 'openai_completion' },
            async () => {
                return await openai.chat.completions.create({
                    model: 'gpt-3.5-turbo',
                    messages: [{ role: 'user', content: 'Hello!' }]
                });
            }
        );

        // Anthropic call
        const anthropicResponse = await keywordsAi.withTask(
            { name: 'anthropic_completion' },
            async () => {
                return await anthropic.messages.create({
                    model: 'claude-3-haiku-20240307',
                    max_tokens: 100,
                    messages: [{ role: 'user', content: 'Hello!' }]
                });
            }
        );

        return { openaiResponse, anthropicResponse };
    }
);

await keywordsAi.shutdown();

Run it:

npx tsx multi_provider.ts

Agent with Multiple Tools

Example of an assistant agent using multiple tools for analysis and response generation.

const assistantAgent = async (query: string) => {
    return await keywordsAi.withAgent(
        { 
            name: 'assistant_agent',
            associationProperties: { 'agent_type': 'general' }
        },
        async () => {
            // Tool 1: Query analyzer
            const analysis = await keywordsAi.withTool(
                { name: 'query_analyzer' },
                async () => {
                    return {
                        intent: query.includes('?') ? 'question' : 'statement',
                        length: query.length,
                        complexity: query.split(' ').length > 10 ? 'high' : 'low'
                    };
                }
            );
            
            // Tool 2: Response generator
            const response = await keywordsAi.withTool(
                { name: 'response_generator' },
                async () => {
                    await new Promise(resolve => setTimeout(resolve, 100));
                    return `Response based on analysis: ${JSON.stringify(analysis)}`;
                }
            );
            
            return {
                analysis,
                response
            };
        }
    );
};

// Usage
const result = await assistantAgent('Can you explain quantum computing?');
console.log('Agent Response:', result);

API Reference

Method	Description
`withWorkflow`	High-level grouping of tasks (top-level trace)
`withTask`	Discrete step within a workflow
`withAgent`	Specialized for agentic patterns
`withTool`	Tool/function calls within agents
`getClient()`	Access manual span management methods
`initialize()`	Initialize tracing (required)
`shutdown()`	Gracefully shutdown and flush spans

Client Methods

Method	Description
`updateCurrentSpan`	Update name, attributes, status, KeywordsAI params
`addSpanEvent`	Add a timestamped event to current span
`recordSpanException`	Record an error on current span
`getCurrentTraceId`	Get the current trace ID
`getCurrentSpanId`	Get the current span ID
`flush`	Manually flush pending spans

More Examples

Explore additional examples in the GitHub repository:

Instrumentation Management (instrumentation_management.ts): Disabling specific instrumentations, explicit module loading
Manual Instrumentation (manual_instrumentation.ts): For Next.js and environments where dynamic imports don’t work
Span Buffering (span_buffering.ts): Manual control over span creation and batch processing
Noise Filtering (noise_filtering.ts): How the SDK filters out auto-instrumentation noise
Multi-Processor (multi_processor.ts): Custom span processors with routing and filters

View all TypeScript examples on GitHub →

Python Tracing SDK

TypeScript Tracing SDK

Keywords AI SDK

Setup

Basic Usage

OpenAI Integration

Advanced Agentic Workflow

Span Management

Multi-Provider Tracing

Agent with Multiple Tools

API Reference

Client Methods

More Examples

Python Tracing SDK

TypeScript Tracing SDK

Keywords AI SDK

Documentation Index

​Setup

​Basic Usage

​OpenAI Integration

​Advanced Agentic Workflow

​Span Management

​Multi-Provider Tracing

​Agent with Multiple Tools

​API Reference

​Client Methods

​More Examples

Setup

Basic Usage

OpenAI Integration

Advanced Agentic Workflow

Span Management

Multi-Provider Tracing

Agent with Multiple Tools

API Reference

Client Methods

More Examples