> ## 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 Identity

> Add stable agent IDs and display names so Catalyst groups agent executions correctly.

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.

<CodeGroup>
  <Metadata text="integrations/traces/agent-identity-manual" />

  ```typescript TypeScript theme={"system"}
  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",
      agentName: "Refund Review Agent",
      spanName: "refund-review.run",
      sessionId: "conversation-refund-1842",
      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();
  ```

  <Metadata text="integrations/traces/agent-identity-manual" />

  ```python Python theme={"system"}
  import os

  from inference_catalyst_tracing import agent_span, setup
  from openai import OpenAI

  tracing = setup()
  client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

  with agent_span(
      tracing.tracer,
      agent_id="refund-review-agent",
      agent_name="Refund Review Agent",
      span_name="refund-review.run",
      session_id="conversation-refund-1842",
      agent_role="refunds",
      system="openai",
  ) as span:
      user_input = "Review refund request #1842."
      span.set_input(user_input)
      response = client.responses.create(model="gpt-4o-mini", input=user_input)
      span.set_output(response.output_text)

  tracing.shutdown()
  ```
</CodeGroup>

## Choosing IDs

Use IDs that are stable, readable, and unique within a project:

| Good                   | Avoid                                    |
| ---------------------- | ---------------------------------------- |
| `support-triage-agent` | `SupportAgent v2`                        |
| `refund-review-agent`  | random UUID per process                  |
| `billing-agent-prod`   | user-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.

<CodeGroup>
  <Metadata text="integrations/traces/agent-identity-session" />

  ```typescript TypeScript theme={"system"}
  await agentSpan(
    tracing.tracer,
    {
      agentId: "support-agent",
      agentName: "Support Agent",
      spanName: "support-agent.run",
      sessionId: conversationId,
      role: "support",
      system: "openai",
    },
    async (span) => {
      // ...
    },
  );
  ```

  <Metadata text="integrations/traces/agent-identity-session" />

  ```python Python theme={"system"}
  with agent_span(
      tracing.tracer,
      agent_id="support-agent",
      agent_name="Support Agent",
      span_name="support-agent.run",
      session_id=conversation_id,
      agent_role="support",
      system="openai",
  ) as span:
      ...
  ```
</CodeGroup>

## Existing OpenTelemetry Spans

If you author spans directly, set `openinference.span.kind = "AGENT"` plus
`agent.id`, `agent.name`, optional `agent.role`, and optional `session.id` on
the span attributes.

<Metadata text="integrations/traces/agent-identity-custom-span" />

```typescript TypeScript theme={"system"}
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]: "Support Agent",
    [Attr.AGENT_ROLE]: "support",
    [Attr.SESSION_ID]: "conversation-1842",
  },
});

span.end();
```

## 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. The raw
attributes remain on the span, and ingestion promotes them into dashboard fields
used by the Agents page.