Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.inference.net/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
Manual Agent 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(
  tracing.tracer,
  {
    agentId: "refund-review-agent",
    name: "RefundReviewAgent",
    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.

​
Existing OpenTelemetry Spans

If you author spans directly, set openinference.span.kind = "AGENT" plus agent.id, agent.name, and optional agent.role on the span attributes.
TypeScript
import { trace } from "@opentelemetry/api";
import { Attr, SpanKindValues } from "@inference/tracing";

const span = trace.getTracer("app").startSpan("support-agent.step", {
  attributes: {
    [Attr.SPAN_KIND]: SpanKindValues.AGENT,
    [Attr.AGENT_ID]: "support-agent",
    [Attr.AGENT_NAME]: "SupportAgent",
    [Attr.AGENT_ROLE]: "support",
  },
});

span.end();

​
What Catalyst Uses

Catalyst reads agent.id first and falls back to agent.name when no stable ID is present. The raw attributes remain on the span, and ingestion promotes them into dashboard fields used by the Agents page.