Identify visitors

Identifying visitors records who each agent run was for, such as a chat user, a ticket requester, or a calling agent, so the same visitor appears on every session your agent reports. Use it when you need to see an agent’s work per person or account, with any framework, for a new agent or one already in production. To group a conversation’s runs without naming who it was for, Group runs into sessions instead.

Before you begin

Before you start, make sure you have:

Tracing SDK: Installed with tracing:

pip install 'atlanai[tracing]'

npm install @atlanai/sdk

Agent credentials: The agent’s own API key in ATLAN_API_KEY and its workspace in ATLAN_WORKSPACE_ID, from an approved secret store. See Send and verify traces.

Initialize client at startup

Call init once when the process starts:

import atlanai.tracing as atlan

client = atlan.init(
    service_name="support-rover",   # your agent's name
    api_key=None,                   # reads ATLAN_API_KEY
    workspace_id="...",             # or env ATLAN_WORKSPACE_ID
)

import * as atlan from "@atlanai/sdk/tracing";

const client = atlan.init({
  serviceName: "support-rover",
  apiKey: process.env.ATLAN_API_KEY,
  workspaceId: process.env.ATLAN_WORKSPACE_ID,
});

Identify visitor per request

At the start of each request, identify the visitor with a stable ID from where the request came from, such as a Slack user ID, a ticket requester’s ID, or a calling agent’s handle, not only an email:

visitor = client.identify(
    identity_source="slack",
    external_id="U0123ABC",
    traits={"name": "Jordan Lee", "email": "jordan@example.com"},
)

const visitor = await client.identify({
  identitySource: "slack",
  externalId: "U0123ABC",
  traits: { name: "Jordan Lee", email: "jordan@example.com" },
});

identify is idempotent on (identity_source, external_id): calling it on every request refreshes the existing visitor instead of creating a duplicate.

Carry visitor through run

Wrap the call into your agent, whether LangGraph, CrewAI, the OpenAI Agents SDK, Google ADK, the Claude Agent SDK, or a plain loop, in attribute propagation. It stamps the visitor ID on every span inside, including third-party instrumentation, without changing how the framework runs:

from atlanai.tracing import propagate_attributes

with propagate_attributes(visitor_id=visitor.id if visitor else None):
    result = my_agent.invoke({"input": user_message})  # LangGraph .invoke,
    # CrewAI .kickoff(), an OpenAI Agents SDK Runner.run(), or your own loop

await atlan.propagateAttributes({ visitorId: visitor?.id }, async () => {
  const result = await myAgent.invoke({ input: userMessage }); // same idea —
  // whatever your framework's run/invoke/kickoff call is
});

Verify visitor on session

Open the agent’s profile, select Sessions, and find the session the run reported. Confirm it shows the visitor’s name or email that you sent in traits.

Pre-seed known visitors (optional)

If you already have an export of known users, such as ticket requesters or chat members, identify them up front instead of waiting for each one’s next request:

known_users = [
    {"external_id": "zendesk_1001", "name": "Priya Shah", "email": "priya@example.com"},
    {"external_id": "zendesk_1002", "name": "Alex Kim", "email": "alex@example.com"},
    # ... however you exported these from Zendesk, Salesforce, or your CRM
]

for user in known_users:
    client.identify(
        identity_source="zendesk",
        external_id=user["external_id"],
        traits={"name": user["name"], "email": user["email"]},
    )

const knownUsers = [
  { externalId: "zendesk_1001", name: "Priya Shah", email: "priya@example.com" },
  { externalId: "zendesk_1002", name: "Alex Kim", email: "alex@example.com" },
  // ... however you exported these from Zendesk, Salesforce, or your CRM
];

for (const user of knownUsers) {
  await client.identify({
    identitySource: "zendesk",
    externalId: user.externalId,
    traits: { name: user.name, email: user.email },
  });
}

Pre-seeding resolves each known user’s directory match the first time their ID comes through. It does not relink anything already reported: sessions are create-only, so a session created before you called identify keeps the visitor snapshot it was created with, usually none. There is no bulk relink for past sessions or traces.

Troubleshooting

If the agent’s sessions do not appear at all, its runs were probably sent with a personal API key. See Traces appear under person instead of agent.

Next steps

How agent sessions work: Read a session and its turns.

Register and manage agents

Give agents business context

Observe agent runs

Evaluate and improve agents

Track agent cost

Before you begin

Troubleshooting

Next steps

See also