Quickstart

Traces is currently in beta. Please share any feedback or suggestions.

Create new account in Keywords AI

Go to Keywords AI and create a new account.
Get your API key from the API Keys page in Settings.

Set up Traces

Install the SDK

Install the package using your preferred package manager:

pip install keywordsai-tracing

Set up Environment Variables

Get your API key from the API Keys page in Settings, then configure it in your environment:

.env
KEYWORDSAI_BASE_URL="https://api.keywordsai.co/api"
KEYWORDSAI_API_KEY="YOUR_KEYWORDSAI_API_KEY"

Annotate your workflows

Use the @workflow and @task decorators to instrument your code:

Python
from keywordsai_tracing.decorators import workflow, task
from keywordsai_tracing.main import KeywordsAITelemetry

k_tl = KeywordsAITelemetry()

@workflow(name="my_workflow")
def my_workflow():
    @task(name="my_task")
    def my_task():
        pass
    my_task()

A full example with LLM calls

In this example, you will see how to implement a workflow that includes LLM calls. We use OpenAI SDK as an example.

main.py
from openai import OpenAI
from keywordsai_tracing.decorators import workflow, task
from keywordsai_tracing.main import KeywordsAITelemetry

k_tl = KeywordsAITelemetry()
client = OpenAI()

@workflow(name="create_joke")
def create_joke():
    completion = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Tell me a joke about opentelemetry"}],
        temperature=0.5,
        max_tokens=100,
        frequency_penalty=0.5,
        presence_penalty=0.5,
    )
    return completion.choices[0].message.content

Install the SDK

Install the package using your preferred package manager:

pip install keywordsai-tracing

Set up Environment Variables

Get your API key from the API Keys page in Settings, then configure it in your environment:

.env
KEYWORDSAI_BASE_URL="https://api.keywordsai.co/api"
KEYWORDSAI_API_KEY="YOUR_KEYWORDSAI_API_KEY"

Annotate your workflows

Use the @workflow and @task decorators to instrument your code:

Python
from keywordsai_tracing.decorators import workflow, task
from keywordsai_tracing.main import KeywordsAITelemetry

k_tl = KeywordsAITelemetry()

@workflow(name="my_workflow")
def my_workflow():
    @task(name="my_task")
    def my_task():
        pass
    my_task()

A full example with LLM calls

In this example, you will see how to implement a workflow that includes LLM calls. We use OpenAI SDK as an example.

main.py
from openai import OpenAI
from keywordsai_tracing.decorators import workflow, task
from keywordsai_tracing.main import KeywordsAITelemetry

k_tl = KeywordsAITelemetry()
client = OpenAI()

@workflow(name="create_joke")
def create_joke():
    completion = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Tell me a joke about opentelemetry"}],
        temperature=0.5,
        max_tokens=100,
        frequency_penalty=0.5,
        presence_penalty=0.5,
    )
    return completion.choices[0].message.content

Install the SDK

Install the package using your preferred package manager:

npm install @keywordsai/tracing
# or yarn

yarn add @keywordsai/tracing

Set up Environment Variables

Get your API key from the API Keys page in Settings, then configure it in your environment:

.env
KEYWORDSAI_BASE_URL="https://api.keywordsai.co/api"
KEYWORDSAI_API_KEY="YOUR_KEYWORDSAI_API_KEY"

Create a simple task

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

// Initialize clients
// Make sure to set these environment variables or pass them directly
const keywordsAi = new KeywordsAITelemetry({
    apiKey: process.env.KEYWORDSAI_API_KEY || "",
    appName: 'test-app',
    disableBatch: true  // For testing, disable batching
});

const openai = new OpenAI();

// This demonstrates a simple LLM call wrapped in a task
async function createJoke() {
    return await keywordsAi.withTask(
        { name: 'joke_creation' },
        async () => {
            const completion = await openai.chat.completions.create({
                messages: [{ role: 'user', content: 'Tell me a joke about TypeScript' }],
                model: 'gpt-4o-mini',
                temperature: 0.7
            });
            return completion.choices[0].message.content;
        }
    );
}

Create a workflow combining tasks

In this example, we create a workflow pirate_joke_workflow that combines the createJoke task with a translateJoke task.

server.ts
async function jokeWorkflow() {
    return await keywordsAi.withWorkflow(
        { name: 'pirate_joke_workflow' },
        async () => {
            const joke = await createJoke();
            const pirateJoke = await translateJoke(joke);
            return pirateJoke;
        }
    );
}

The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows.

Install the SDK

Install the package using your preferred package manager:

pip
pip install openai-agents

pip
pip install keywordsai-tracing

pip
pip install "keywordsai-tracing[openai-agents]"

Set up Keywords AI trace processor

Get your API key from the API Keys page in Settings, then configure it in your environment.

agent.py
import os
from agents.tracing import set_trace_processors
from keywordsai_tracing.integrations.openai_agents_integration import KeywordsAITraceProcessor

set_trace_processors(
    [
        KeywordsAITraceProcessor(
            api_key=os.getenv("KEYWORDSAI_API_KEY"),
            endpoint="https://api.keywordsai.co/api/openai/v1/traces/ingest"
        ),
    ]
)

Call the agent

Now you can call the agent and it will be traced by Keywords AI automatically.

agent.py
import asyncio
import os
from agents import Agent, Runner
from agents.tracing import set_trace_processors
from keywordsai_tracing.integrations.openai_agents_integration import KeywordsAITraceProcessor

set_trace_processors(
    [
        KeywordsAITraceProcessor(
            api_key=os.getenv("KEYWORDSAI_API_KEY"),
            endpoint="https://api.keywordsai.co/api/openai/v1/traces/ingest"
        ),
    ]
)

async def main():
    agent = Agent(
        name="Assistant",
        instructions="You only respond in haikus.",
    )

    result = await Runner.run(agent, "Tell me about recursion in programming.")
    print(result.final_output)
    # Function calls itself,
    # Looping in smaller pieces,
    # Endless by design.

if __name__ == "__main__":
    asyncio.run(main())

Understanding Workflows and Tasks

A workflow is a sequence of tasks that you want to monitor. Each task represents a single unit of work within that workflow.

Example

Below is an example that demonstrates how to use tasks and workflows. We’ll create a workflow that:

Generates a joke
Translates it to pirate speak
Adds a signature

Each operation is implemented as a separate task that can be used independently or as part of the workflow.

Python
@task(name="joke_creation")
def create_joke():
    completion = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": "Tell me a joke about opentelemetry"}],
        temperature=0.5,
        max_tokens=100,
        frequency_penalty=0.5,
        presence_penalty=0.5,
        stop=["\n"],
        logprobs=True,
    )
    return completion.choices[0].message.content

@task(name="signature_generation")
def generate_signature(joke: str):
    completion = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "user", "content": "add a signature to the joke:\n\n" + joke}
        ],
    )
    return completion.choices[0].message.content

@task(name="pirate_joke_translation")
def translate_joke_to_pirate(joke: str):
    completion = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {
                "role": "user",
                "content": "translate the joke to pirate language:\n\n" + joke,
            }
        ],
    )
    return completion.choices[0].message.content

Chain these tasks together in a workflow:

Python
@workflow(name="joke_workflow")
def joke_workflow():
    joke = create_joke()
    pirate_joke = translate_joke_to_pirate(joke)
    signature = generate_signature(pirate_joke)
    return signature

You can then see the trace in Traces.

Example adapted from Traceloop

Decorating Classes (Python only)

While the examples above shows how to decorate functions, you can also decorate classes. In this case, you will also need to provide the name of the method that runs the workflow and task.

Python
from openai import OpenAI
from keywordsai_tracing import KeywordsAITelemetry
from keywordsai_tracing.decorators import workflow, task

k_tl = KeywordsAITelemetry()
client = OpenAI()

@workflow(name="joke_agent", method_name="run")
class JokeAgent:
    @task(name="joke_creation")
    def create_joke(self):
        completion = client.chat.completions.create(
            model="gpt-3.5-turbo",
            messages=[{"role": "user", "content": "Tell me a joke about opentelemetry"}],
        )
        joke = completion.choices[0].message.content
        return joke
    def run(self):
        return self.create_joke()

Get started

AI observability

Prompt engineering

Evaluations

AI gateway

Organization management

Resources

Create new account in Keywords AI

Set up Traces

Understanding Workflows and Tasks

Example

Decorating Classes (Python only)

Get started

AI observability

Prompt engineering

Evaluations

AI gateway

Organization management

Resources

​Create new account in Keywords AI

​Set up Traces

​Understanding Workflows and Tasks

​Example

​Decorating Classes (Python only)

Create new account in Keywords AI

Set up Traces

Understanding Workflows and Tasks

Example

Decorating Classes (Python only)