Skip to content

Context

The coalex_context() function creates a parent span that tags all child spans with agent metadata, making them queryable in the dashboard.

Usage

with coalex.coalex_context(
    agent_id="support-bot",
    request_id="req-123",
    version="2.1.0",
):
    # All LLM calls, retrieval queries, etc. inside this block
    # inherit the agent_id, request_id, and version.
    response = client.chat.completions.create(...)

await coalexContext(
    { agentId: "support-bot", requestId: "req-123", version: "2.1.0" },
    async () => {
        const response = await client.chat.completions.create(...);
    },
);

What Context Propagates

Attribute Description
agent_id The agent that owns this request
request_id Unique identifier for the request (links traces to evaluations)
version Agent version string (optional, for A/B testing)

These attributes are attached as span attributes to every child span, enabling you to:

  • Filter traces by agent in the dashboard
  • Link evaluations to their corresponding traces via request_id
  • Compare versions side-by-side in metrics views

Best Practices

  1. One context per user request — Create a new coalex_context() for each incoming request to your agent.
  2. Use unique request IDs — Use UUIDs or your application's request ID to avoid collisions.
  3. Reuse the same request ID in evaluate() — The request_id in coalex_context() must match the one in evaluate() to link traces and evaluations.
  4. Set version for A/B tests — When testing different prompt versions, set version to differentiate traces.

Nesting

Coalex contexts can be nested. Inner contexts create child spans of the outer context:

with coalex.coalex_context(agent_id="orchestrator", request_id="req-001"):
    # Orchestrator span
    with coalex.coalex_context(agent_id="sub-agent", request_id="req-001"):
        # Sub-agent span (child of orchestrator)
        response = client.chat.completions.create(...)

SDK Reference