Skip to main content
Agent dashboards group executions by agent identity. For production agents, emit a stable agent.id and a readable agent.name. Keep agent.id stable across deploys, environments, and display-name changes; use agent.name as the human-readable label. If you only provide agent.name, Catalyst can still show observed agents, but renames and duplicate names are harder to group. Prefer both fields whenever you control the agent wrapper.

​
Agent Span Wrapper

Use agentSpan() or agent_span() around the product-level agent run. Child model and tool spans created inside the wrapper inherit the active agent identity in supported Catalyst tracing integrations. 
import { agentSpan, setup } from "@inference/tracing";
import OpenAI from "openai";

const tracing = await setup({ modules: { openai: OpenAI } });
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

await agentSpan(
  {
    agentId: "refund-review-agent",
    agentName: "Refund Review Agent",
    spanName: "refund-review.run",
    sessionId: "conversation-refund-1842",
    userId: "user_8675309",
    role: "refunds",
    system: "openai",
  },
  async (span) => {
    const input = "Review refund request #1842.";
    span.setInput(input);
    const response = await client.responses.create({
      model: "gpt-4o-mini",
      input,
    });
    span.setOutput(response.output_text);
  },
);

await tracing.shutdown();

​
Choosing IDs

Use IDs that are stable, readable, and unique within a project:
GoodAvoid
support-triage-agentSupportAgent v2
refund-review-agentrandom UUID per process
billing-agent-produser-specific or request-specific values
agent.role is optional. Use it when one workflow has multiple agents with clear responsibilities, such as triage, refunds, or billing.

​
Conversation Grouping

sessionId / session_id is an optional field that emits session.id on the agent span. Use it to group agent runs that belong to the same conversation, chat thread, or multi-turn request. Pass an ID that is stable for one conversation and is already available in the calling code — do not treat it as process-wide setup. 
await agentSpan(
  {
    agentId: "support-agent",
    agentName: "Support Agent",
    spanName: "support-agent.run",
    sessionId: conversationId,
    role: "support",
    system: "openai",
  },
  async (span) => {
    // ...
  },
);

​
User Grouping

userId / user_id is an optional field that emits user.id on the agent span. The trace dashboard lets you filter to all traces for that user.

​
What Catalyst Uses

Catalyst reads agent.id first and falls back to agent.name when no stable ID is present. session.id is read separately for conversation grouping, and user.id for filtering traces by user. The raw attributes remain on the span, and ingestion promotes them into dashboard fields used by the Agents page.