Skip to content

Quickstart

Get Coalex traces flowing from your AI agent in under 5 minutes.

Prerequisites

  • Python 3.11 or later
  • A Coalex account with an API key (get one at coalex.ai)
  • An LLM provider key (OpenAI, Anthropic, Vertex AI, etc.)
  • Node.js 18 or later
  • A Coalex account with an API key (get one at coalex.ai)
  • An LLM provider key (OpenAI, Anthropic, Vertex AI, etc.)

1. Install the SDK

pip install coalex[auto-instrument]

This installs the core SDK plus auto-instrumentation support for all 15 supported LLM frameworks.

npm install @coalex-ai/sdk openai @arizeai/openinference-instrumentation-openai

This installs the core SDK, the OpenAI client, and the OpenInference instrumentor for OpenAI.

Prefer minimal installs?

You can install framework-specific extras instead. See Installation for all options.

2. Set environment variables

export COALEX_API_KEY="your-coalex-api-key"
export OPENAI_API_KEY="your-openai-key"  # or any other LLM provider
# COALEX_ENDPOINT is optional — defaults to Azure cloud (traces.azure.coalex.ai)

Never hardcode secrets

Always use environment variables or a secrets manager. Never commit API keys to source control.

3. Instrument your agent

Create a file called agent.py:

import os
import coalex
from openai import OpenAI

# --- Coalex setup (once at startup) ---

coalex.register(
    api_key=os.environ["COALEX_API_KEY"],
    service_name="quickstart-agent",
)

coalex.auto_instrument()

# Declare agent (recommended)
coalex.declare_agent(agent_id="quickstart-bot", display_name="Quickstart Bot")

# --- Your agent logic ---

client = OpenAI()

with coalex.coalex_context(agent_id="quickstart-bot", request_id="req-001"):
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "What is AI governance?"},
        ],
    )
    print(response.choices[0].message.content)

Create a file called agent.ts:

import { register, coalexContext, autoInstrument, declareAgent } from "@coalex-ai/sdk";
import OpenAI from "openai";

// --- Coalex setup (once at startup) ---

register({
    apiKey: process.env.COALEX_API_KEY!,
    serviceName: "quickstart-agent",
});

autoInstrument();

// Declare agent (recommended)
await declareAgent({ agentId: "quickstart-bot", displayName: "Quickstart Bot" });

// --- Your agent logic ---

const client = new OpenAI();

await coalexContext({ agentId: "quickstart-bot", requestId: "req-001" }, async () => {
    const response = await client.chat.completions.create({
        model: "gpt-4o",
        messages: [
            { role: "system", content: "You are a helpful assistant." },
            { role: "user", content: "What is AI governance?" },
        ],
    });
    console.log(response.choices[0].message.content);
});

What each call does

Python TypeScript Purpose
coalex.register() register() Configures the OTLP exporter with your endpoint and API key
coalex.auto_instrument() autoInstrument() Patches all supported LLM frameworks to emit OpenInference spans
coalex.declare_agent() declareAgent() Pre-registers the agent so the dashboard recognizes it immediately
coalex.coalex_context() coalexContext() Sets agent_id, request_id, and optional version on all spans within the block

4. Run it

python agent.py

npx tsx agent.ts

You should see your agent's response printed to the console. Behind the scenes, Coalex has captured the full trace -- including the LLM call, token counts, latency, and model parameters.

5. Verify traces

Open your Coalex dashboard and navigate to Traces. You should see a trace for quickstart-agent with:

  • The OpenAI chat completion span
  • Input and output messages
  • Token usage (prompt tokens, completion tokens)
  • Latency breakdown

You are all set

Traces are flowing. Every LLM call your agent makes is now automatically captured and sent to Coalex.

Next steps

  • Add human-in-the-loop

    Use coalex.evaluate() to assess risk and coalex.resolve() for human review.

    Protect

  • Manual instrumentation

    Use extension decorators like @retrieval_span and @tool_span for custom spans.

    Extensions

  • Key concepts

    Understand traces, spans, evaluations, and the Coalex data model.

    Concepts

  • SDK Reference

    Full API documentation for every function and decorator.

    SDK Reference