Skip to main content
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.
The two halves of the SDK: tracing is a thin layer over the stock OpenTelemetry SDK that adds Atlan authentication, agent-sdk.v1 conventions, an export pipeline, and privacy controls, and also carries OpenLLMetry and OpenInference spans to Agent Registry. Management is a separate client with separate credentials that reads and writes Registry artifacts.The two halves of the SDK: tracing is a thin layer over the stock OpenTelemetry SDK that adds Atlan authentication, agent-sdk.v1 conventions, an export pipeline, and privacy controls, and also carries OpenLLMetry and OpenInference spans to Agent Registry. Management is a separate client with separate credentials that reads and writes Registry artifacts.

​
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, MCP, and HTTP API 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 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

Management SDK

You want to read or write Registry artifacts from your own code — register an agent, publish a skill, list sessions.

Tracing SDK

You control the agent’s source and want spans, scores, cost, and Visitor identity. Start with the quickstart below.

Evaluations

Build datasets, record experiments, retain results, and compare a candidate against a baseline.

MCP

You want an agent to read Registry artifacts or call tools from a registered downstream server, not to report its own telemetry.

HTTP API

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.

​
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.
  • 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.
  • Management writes are not retried automatically — see 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

Install for Python and TypeScript.

Operations reference

Every management operation, by resource.

Evaluate an agent

Build a dataset, run a candidate, and retain evidence for later diagnosis.

Quickstart

Initialize, trace one run, and verify it in Agent Registry.

Trace your agent

Spans, observation types, usage and cost, deterministic trace IDs.