Operations reference

The management client is generated from the gateway’s contracts, so it covers the whole published surface — 189 operations across seven services. This page explains how the client is organised and lists the operations you reach for most. Every one of the 189 is in the per-resource reference — 37 pages, the largest of which are:

Agents

17 operations

Skills

16 operations

Harnesses

12 operations

Sessions

11 operations

Outputs

10 operations

Users

9 operations

Projects

8 operations

Workspaces

8 operations

Those pages are generated from the same operation manifest the SDKs ship, so they cannot drift from what the client actually exposes.

client.secrets and client.api exist on the client but publish no operations today, which is why seven services carry all 189.

How the client is organised

One namespace per service, each delegating to the generated APIs beneath it:

from atlanai import AtlanClient

client = AtlanClient(
    "https://agentgateway.atlan.engineering",
    bearer_token="...",
    workspace="workspace_01example",   # sent as X-Atlan-Workspace-Id
)

for namespace in (
    client.registry,
    client.skills,
    client.files,
    client.agents,
    client.mcp,
    client.secrets,
    client.models,
    client.api,
    client.otel,
):
    print(namespace.name)

import { AtlanClient } from "@atlanai/sdk";

const client = new AtlanClient({
  gatewayOrigin: "https://agentgateway.atlan.engineering",
  bearerToken: "...",
  workspace: "workspace_01example",
});

for (const ns of [client.registry, client.skills, client.files, client.agents, client.mcp]) {
  console.log(ns.name);
}

Method names are the operation IDs from the contract: snake_case in Python, camelCase in TypeScript. So agent_create_agent in Python is agentCreateAgent in TypeScript. Everything below lists the Python spelling. with_workspace() rebinds a namespace or the whole client to another workspace over the same generated clients, so a multi-tenant process does not need a second client:

other = client.with_workspace("workspace_01other")

Agents

Operation	Does
`agent_create_agent`	Register an agent. Requires `name`, `workspace_id`.
`agent_get_agent`	Read one by id.
`agent_list_agents`	List in scope.
`agent_search_agents`	Ranked search; query goes in the body.
`agent_patch_agent`	Change instructions, model, tools, ownership.
`agent_archive_agent`	Retire it. There is no destructive delete.
`agent_create_provider`	Register where the agent runs.
`agent_create_environment`	Register its environment.
`agent_create_agent_framework`	Register its framework.
`agent_identify_visitor`	Upsert a Visitor from the management client.

Sessions and transcripts

Operation	Does
`agent_create_session_record`	Record a completed run.
`agent_create_session_message`	Append one transcript message.
`agent_list_agent_sessions`	Sessions for one agent.
`agent_list_session_messages`	Transcript for one session.
`agent_list_agent_traces`	Traces attributed to one agent.
`agent_list_outputs`	Agent outputs and their versions.

Prefer the tracing submodule over building session records by hand. Use these when the runtime cannot be instrumented.

Skills

Operation	Does
`skill_create`	Publish a skill from a bundle.
`skill_bulk_create`	Publish up to 100 in one request.
`skill_list`	List in scope.
`skill_search`	Ranked search.
`skill_get_enriched`	Read one with its metadata and file manifest.
`skill_get_bundle`	Download the current bundle as bytes.
`skill_get_version_bundle`	Download a pinned version’s bundle.
`skill_patch`	Rename or re-describe.
`skill_archive`	Retire it.
`skill_list_insights`	Computed insights for one skill.
`skill_insight_schemas`	What insights exist.

Files

Uploading is a two-step ticket flow, and both steps are now wrapped:

Operation	Does
`file_create_upload`	Ask for an upload ticket.
`file_ingest_upload`	Send the bytes for that ticket.
`file_list`	List files in scope.
`file_get_content`	Current bytes.
`file_get_version_content`	A pinned version’s bytes.

Content operations return the stored media type, not JSON. Check the content type before parsing or you will write a corrupt file.

Registry

Operation	Does
`registry_whoami`	Resolve the calling identity and its scope.
`registry_search`	Search across artifact kinds.
`registry_aggregate`	Counts grouped by a field.
`registry_list_workspaces`	Workspaces you can reach.
`registry_create_workspace`	Create one.
`registry_list_projects`	Projects in scope.

registry_whoami is the cheapest way to confirm a credential and see which workspace it resolves to before a write.

MCP

Operation	Does
`mcp_list_servers`	Registered MCP servers.
`mcp_list_tools`	Their tools.
`mcp_test_server`	Connection test for one server.

Use these to find the server and tool values an agent’s tools list needs.

Errors

Every generated exception — including the per-status subclasses — is normalised to a single AtlanAPIError carrying the gateway’s problem document, so you handle a status and a stable code rather than parsing bodies:

from atlanai import AtlanAPIError

try:
    client.skills.get_enriched("skill_01example")
except AtlanAPIError as error:
    print(error.status, error.code, error.trace_id)

import { AtlanAPIError } from "@atlanai/sdk";

try {
  await client.skills.getEnriched({ skillId: "skill_01example" });
} catch (error) {
  if (error instanceof AtlanAPIError) {
    console.log(error.status, error.code, error.traceId);
  }
}

The fields are status, code, title, detail, and the request’s trace_id / traceId — quote that trace ID when reporting a gateway problem. detail is deliberately kept out of the exception message so an error that reaches a log or a user-facing surface cannot carry a server-supplied string. Catch AtlanAPIError and branch on status or code. You never need to catch a per-status exception class. Writes are not retried automatically. A retried create can duplicate an artifact, so retry deliberately — see Errors and retries.

Reaching an operation this page omits

Start with the per-resource reference — it lists all 189. Beyond that, the operation manifest ships inside both packages and is the canonical inventory, so you can enumerate the surface at runtime:

from atlanai import operations

for operation in operations():
    print(operation["operation_id"], operation["method"], operation["path"])

import { operations } from "@atlanai/sdk";

// A frozen array in TypeScript; `operations()` is a function in Python.
for (const operation of operations) {
  console.log(operation.operation_id, operation.method, operation.path);
}

The generated APIs also sit under client.<namespace>.apis, keyed by the contract’s OpenAPI tag, when you want a generated signature rather than the facade’s forwarded call.

Do not hard-code an OpenAPI tag to reach an API. Tags are renamed upstream — skills became skill and files became file in a recent refresh — so reach operations by their method name, which is stable.

Overview

CLI

SDK

Cookbooks

Operate safely

API reference

Agents

Skills

Harnesses

Sessions

Outputs

Users

Projects

Workspaces

How the client is organised

Agents

Sessions and transcripts

Skills

Files

Registry

MCP

Errors

Reaching an operation this page omits

Next steps

Agents cookbook

Skills cookbook

Tracing

API reference

Agents

Skills

Harnesses

Sessions

Outputs

Users

Projects

Workspaces

​How the client is organised

​Agents

​Sessions and transcripts

​Skills

​Files

​Registry

​MCP

​Errors

​Reaching an operation this page omits

​Next steps

Agents cookbook

Skills cookbook

Tracing

API reference

How the client is organised

Agents

Sessions and transcripts

Skills

Files

Registry

MCP

Errors

Reaching an operation this page omits

Next steps