atlanai

Python SDK for the Atlan Agent Gateway: manage agents, skills, sessions, and workspaces, and optionally trace what your agents do.

Install

pip install atlanai

Tracing is a separate extra — it pulls in OpenTelemetry, which a management-only install doesn't need:

pip install 'atlanai[tracing]'

Quickstart

from atlanai import AtlanClient

client = AtlanClient(
    "https://<your-gateway-host>",
    bearer_token="<your-api-token>",
)

agent = client.agents.create({
    "name": "support-triage",
    "workspace_id": "workspace_01example",
})

page = client.agents.list(limit=10)
print(f"{len(page.items)} agents")

Methods read as client.<resource>.<action> — client.agents.get(agent_id), client.sessions.messages.create(session_id, {...}), and so on. Every public Agent Gateway operation is reachable this way; nothing requires reaching into a generated client directly.

Pass a default workspace once instead of repeating it on every call:

client = AtlanClient(gateway_url, bearer_token=token, workspace="workspace_01example")

Tracing

import atlanai.tracing as atlan

tracer = atlan.init(api_key="<your-tracing-key>", workspace_id="workspace_01example")

with tracer.start_as_current_span("handle-request", as_type="task") as span:
    span.update(model="claude-sonnet-5", usage={"input_tokens": 120, "output_tokens": 40})

Tracing has its own API key and lifecycle — it does not reuse the management client's bearer token or transport.

Errors

Every non-2xx response raises AtlanAPIError, with .status, .code, and (where the gateway includes one) .trace_id:

from atlanai import AtlanAPIError

try:
    client.agents.get("agent_does_not_exist")
except AtlanAPIError as error:
    print(error.status, error.code)