> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the atlanai CLI; `atlanai --map json` prints its command map. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.
# SDK
> Python and TypeScript SDKs for the Atlan Agent Gateway: manage agents, skills, and evaluations, and trace what your agents did.
One package per language covers both halves of working with Agent Registry
from code:
* **Management** — read and write Registry artifacts: agents, skills, files,
sessions, workspaces, datasets, experiments, and scorers. Generated from the
gateway's contracts, covering the full published surface.
* **Tracing** — report what your agent did: which model it called, what it
cost, who it ran for, how well it scored. Hand-authored, OpenTelemetry-native,
and installed only if you ask for it.
The tracing half is a thin layer over the stock OpenTelemetry SDK. It adds
Atlan authentication, the `agent-sdk.v1` semantic conventions, a GenAI-tuned
export pipeline, and privacy controls. Everything already instrumented with
OTel in your process — OpenLLMetry, OpenInference, or a framework with native
OTel — flows through the same pipeline once you initialize a client.
## Why use the tracing half
* **Sessions and traces.** Each run becomes a trace of typed observations —
`task`, `llm`, `tool` — grouped into sessions, so a run is inspectable step by
step rather than as a log line.
* **Cost and usage accounting.** Record model, provider, token usage, and cost
on the span that spent it, and get it aggregated per agent, workspace, and
session.
* **Scores.** Attach evaluation results to a trace so quality is queryable next
to latency and cost.
* **Deterministic trace IDs.** Derive a trace ID from a stable external key so
retries and multi-service handling converge on one trace instead of
fragmenting.
* **Third-party instrumentation, unified.** OpenLLMetry, OpenInference, and
frameworks with native OTel flow through the same allowlisted pipeline, with
your association attributes stamped on them.
* **Attribution.** Optionally identify a Visitor per request so every span in
scope carries the same `visitor_id`.
* **Privacy by default.** Masking hooks and a content switch that the Gateway
enforces server-side, not just client-side.
The management half covers reading and writing Registry artifacts directly —
publishing and versioning skills, registering agents and harnesses, sessions,
workspaces — from the same package. The [CLI](/tools/cli/overview),
[MCP](/tools/mcp/overview), and [HTTP API](/api/references/api-reference) reach the same
surface for other integration shapes: a coding-agent session with no code
change, a downstream server calling tools, or a language with no SDK.
## The two packages
| | Python | TypeScript |
| - | - | - |
| Package | `atlanai` (PyPI) | `@atlanai/sdk` (npm) |
| Current version | 0.1.1 | 0.1.1 |
| Management import | `from atlanai import AtlanClient` | `import { AtlanClient } from "@atlanai/sdk"` |
| Tracing import | `import atlanai.tracing as atlan` | `import * as atlan from "@atlanai/tools/sdk/how-tos/tracing"` |
| Runtimes | Python 3.10–3.13 | Node 20+, Cloudflare Workers |
| Framework helper | `atlanai.tracing.langchain` | — |
Python is the normative implementation: `SPEC.md` and
`schema/agent-sdk.v1.yaml` in the `atlanai-sdk-python` repository define the
behavior, and the TypeScript SDK is verified against the same conformance
vectors. Seeded trace IDs and serialized payloads are byte-identical between
the two, so a Python service and a TypeScript service can derive the same
trace ID from the same external key and land on one trace.
Plain JavaScript works identically to TypeScript — the published package is
compiled JS with type declarations, so no TypeScript toolchain is required.
## Choose your integration path
You want to read or write Registry artifacts from your own code — register
an agent, publish a skill, list sessions.
You control the agent's source and want spans, scores, cost, and Visitor
identity. Start with the quickstart below.
Build datasets, record experiments, retain results, and compare a candidate
against a baseline.
You want an agent to read Registry artifacts or call tools from a registered
downstream server, not to report its own telemetry.
You are integrating from a language with no SDK.
If you cannot change the agent's code, the CLI captures coding-agent sessions
without an SDK — see [the CLI overview](/tools/cli/overview).
## Boundaries
* The management client and the tracing client are independent by design:
separate credentials, separate lifecycles. Tracing does not reuse the
management bearer token, so a process doing both configures both — see
[Install](/tools/sdk/how-tos/install).
* `client.identify()` calls the Registry over HTTP and returns a Visitor. Every
other tracing operation only produces spans.
* Tracing degrades to a no-op rather than failing your request. The one
exception is exporting to an Atlan endpoint without a workspace, which raises
at `init()` — see [Configuration](/tools/sdk/references/configuration).
* Management writes are **not** retried automatically — see
[Errors and retries](/platform/references/errors-and-retries).
* TypeScript tracing is a separately owned implementation. Treat a behavior
difference from Python as a bug against the spec.
## Next steps
Install for Python and TypeScript.
Every management operation, by resource.
Build a dataset, run a candidate, and retain evidence for later diagnosis.
Initialize, trace one run, and verify it in Agent Registry.
Spans, observation types, usage and cost, deterministic trace IDs.