Skip to content

Examples

Learn how to use Coalex with real AI agents through these step-by-step walkthroughs. Each example is a fully runnable script in the monorepo's examples/ directory.

Available Examples

  • Medical Agent

    A LangGraph ReAct agent that searches PubMed for medical literature, instrumented with Coalex for full observability.

    Demonstrates @retrieval_span, Document dataclass, multi-provider support, and coalex_context() per query.

    Medical Agent walkthrough

  • LangChain Agent

    Three LangChain examples: simple invocation, LCEL chain, and multi-step reasoning workflow.

    Demonstrates auto_instrument() capturing all LangChain spans automatically.

    LangChain Agent walkthrough

Prerequisites

All examples require:

  1. Local stack running -- the Coalex services must be available:

    docker compose up -d

  2. Coalex API key -- generate one from the admin dashboard (Settings page) or use the default dev key:

    export COALEX_API_KEY="ck_live_..."

  3. LLM provider credentials -- at least one of:

    gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT="your-project"

    export OPENAI_API_KEY="sk-..."

    export ANTHROPIC_API_KEY="sk-ant-..."

  4. Python dependencies -- install from the monorepo root:

    uv pip install "coalex[auto-instrument]"

Provider selection

All examples default to Vertex AI (Gemini). Override with environment variables:

export COALEX_LLM_PROVIDER=openai    # or: vertex, anthropic
export COALEX_MODEL=gpt-4o-mini      # optional: override default model

Source Code

All example source code lives in the monorepo:

Example Path Main file
Medical Agent examples/agent-python/ medical_agent_example.py
LangChain Agent examples/agent-python/ langchain_example.py
TypeScript Agent examples/agent-typescript/ src/index.ts

What Gets Captured

When you run any example with a running local stack, Coalex captures:

  • LLM spans -- model name, input/output messages, token counts, latency
  • Retrieval spans -- queries, retrieved documents, document IDs
  • Chain spans -- LCEL chain composition, intermediate steps
  • Trace context -- agent ID, request ID, version
  • Enrichments -- PII detection, cost estimation, CO2 impact (computed by the transformer)

View captured traces in the admin dashboard or query them directly via the API:

curl http://localhost:8080/v1/traces \
  -H "Authorization: Bearer $COALEX_API_KEY"