Quickstart

Get started with the @keywordsai/tracing TypeScript SDK

Give us a star on GitHub!

The Keywords AI Tracing SDK for TypeScript/JavaScript provides comprehensive observability for your AI applications with automatic instrumentation for OpenAI, Anthropic, and other providers.

Installation

Node.js Requirement: This package requires Node.js 18 or later.

npm install @keywordsai/tracing

Configure credentials

Set up your environment variables:

.env

KEYWORDSAI_API_KEY=your-api-key
KEYWORDSAI_BASE_URL=https://api.keywordsai.co

Initialize the SDK:

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

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

await keywordsAi.initialize();

Trace a workflow and task

Use withWorkflow and withTask to create structured traces:

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

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

await keywordsAi.initialize();

// Simple task
const generateResponse = async (prompt: string) => {
    return await keywordsAi.withTask(
        { name: 'generate_response' },
        async () => {
            return `Response to: ${prompt}`;
        }
    );
};

// Workflow with nested task
const chatWorkflow = async (userMessage: string) => {
    return await keywordsAi.withWorkflow(
        { 
            name: 'chat_workflow',
            associationProperties: { 'user_type': 'demo' }
        },
        async () => {
            const response = await generateResponse(userMessage);
            console.log(`User: ${userMessage}`);
            console.log(`Assistant: ${response}`);
            return response;
        }
    );
};

const result = await chatWorkflow('Hello, how are you?');
console.log(result);

await keywordsAi.shutdown();

OpenAI Integration

Automatically instrument OpenAI SDK calls:

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

const keywordsAi = new KeywordsAITelemetry({
    apiKey: process.env.KEYWORDSAI_API_KEY,
    appName: 'openai-example',
    instrumentModules: {
        openAI: OpenAI,  // Automatically instrument OpenAI
    }
});

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

await keywordsAi.initialize();

await keywordsAi.withWorkflow(
    { name: 'ai_chat' },
    async () => {
        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 joke about programming.' }
            ],
        });
        
        console.log(completion.choices[0].message.content);
    }
);

await keywordsAi.shutdown();

Agent and Tool Tracing

For agentic workflows, use withAgent and withTool:

const assistantAgent = async (query: string) => {
    return await keywordsAi.withAgent(
        { 
            name: 'assistant_agent',
            associationProperties: { 'agent_type': 'general' }
        },
        async () => {
            // Use a tool within the agent
            const analysis = await keywordsAi.withTool(
                { name: 'query_analyzer' },
                async () => {
                    return {
                        intent: query.includes('?') ? 'question' : 'statement',
                        complexity: query.split(' ').length > 10 ? 'high' : 'low'
                    };
                }
            );
            
            const response = await keywordsAi.withTool(
                { name: 'response_generator' },
                async () => {
                    return `Response based on analysis: ${JSON.stringify(analysis)}`;
                }
            );
            
            return { analysis, response };
        }
    );
};

const result = await assistantAgent('Can you explain quantum computing?');
console.log(result);

Configuration Options

apiKey · string · required

Your Keywords AI API key

baseURL · string · default: "https://api.keywordsai.co"

Keywords AI API base URL

appName · string

Name of your application for tracing identification

instrumentModules · object

Modules to automatically instrument

Supported modules

{
  openAI: OpenAI,      // OpenAI SDK
  anthropic: Anthropic  // Anthropic SDK
}

disableBatch · boolean · default: false

If true, sends spans immediately instead of batching

logLevel · string · default: "warn"

Logging level: "debug", "info", "warn", "error"

Next Steps

• Explore comprehensive examples
• Learn about multi-provider tracing
• Understand span management
• View all examples on GitHub