Add Visitor identity to your agent stack

A Visitor is the stable identity for whoever an agent run was for — a chat user, a ticket requester, a calling agent. Identify them once per request and the same visitor_id shows up on every session your agent reports afterward, regardless of which framework ran it.

Internal release. @atlanai/sdk and atlan-ai are distributed org-internal today (GitHub Packages / release artifacts, not npm or PyPI). Confirm access with your Atlan contact before wiring this into a customer-facing deployment.

1. Install the tracing SDK

# Internal distribution — install the wheel from the atlanai-sdk-python repo
pip install releases/0.1.0/atlan_ai-0.1.0-py3-none-any.whl

# .npmrc: @atlanai:registry=https://npm.pkg.github.com
npm install @atlanai/sdk

2. Initialize the client once at startup

import atlan_ai

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

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

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

Fresh integration: identify on every new run

For an agent that doesn’t call identify yet — new or already live, it’s the same one-time code change either way. 3. Identify the visitor at the start of each request. Use a stable id from wherever the request came from — a Slack user id, a ticket requester’s id, a calling agent’s handle — not just 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) — call it again on every request and it refreshes the existing profile instead of creating a duplicate. 4. Carry the visitor through the run, whatever framework runs it. Wrap the call into your agent — LangGraph, CrewAI, the OpenAI Agents SDK, Google ADK, the Claude Agent SDK, or a plain loop — in the SDK’s attribute propagation. This stamps the visitor id on every span emitted inside, including third-party instrumentation, without changing how the framework itself runs:

from atlan_ai 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
});

5. Verify it in Agent Registry. Open the agent’s profile, select Sessions, find the session the run above just reported, and confirm its visitor fields — id, name, email, link status — match what you sent in step 3.

Backfill: an agent already running in prod

Your agent already has sessions and traces in Agent Registry from before you added identify. “Backfill” here means two different things — they are not the same operation. Pre-seed the Visitor directory from your own user list. If you already have an export of known users (Zendesk requesters, Slack members, CRM contacts), identify them all up front instead of waiting for each one’s next request — the same identify call as above, looped over your existing list:

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 },
  });
}

Then add the two-line change from steps 3–4 above to the agent’s request handler so every run from now on carries the link. Pre-seeding just means the directory match (link_status) is already resolved the first time a known user’s id comes through, instead of resolving cold on their next visit.

This does not relink sessions or traces you already reported. Sessions are create-only in Agent Registry — a session created before you called identify keeps whatever visitor snapshot it was created with (typically none), permanently. Identifying a visitor today does not retroactively attach them to yesterday’s sessions or traces; the link only applies to runs reported after this point. There is no supported bulk-relink operation for historical sessions today — if that matters for your rollout, confirm the current state with your Atlan contact before assuming it’s covered.

Agent API reference

Browse the session and visitor operations.

Welcome

Desktop app

Administration

Add Visitor identity to your agent stack

Add Visitor identity to your agent stack

1. Install the tracing SDK

2. Initialize the client once at startup

Fresh integration: identify on every new run

Backfill: an agent already running in prod

Agent API reference

​Add Visitor identity to your agent stack

​1. Install the tracing SDK

​2. Initialize the client once at startup

​Fresh integration: identify on every new run

​Backfill: an agent already running in prod

Agent API reference

Add Visitor identity to your agent stack

1. Install the tracing SDK

2. Initialize the client once at startup

Fresh integration: identify on every new run

Backfill: an agent already running in prod