> ## 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.

# Operations

> Find management operations by resource and learn the client patterns, errors, and retry rules in atlanai SDK.

<Badge color="blue">SDK 0.4.0</Badge>

The atlanai SDK management client covers the gateway's whole published surface. Use this page to learn the client patterns once, then look up each operation in the per-resource reference. For HTTP access without the SDK, use the [HTTP API](/api/references/api-reference).

| Group | Resources |
| - | - |
| Agents and runs | [Agent frameworks](/tools/sdk/references/operations/agent_frameworks), [Agent providers](/tools/sdk/references/operations/agent_providers), [Agents](/tools/sdk/references/operations/agents), [Environments](/tools/sdk/references/operations/environments), [Harness vendors](/tools/sdk/references/operations/harness_vendors), [Harnesses](/tools/sdk/references/operations/harnesses), [Outputs](/tools/sdk/references/operations/outputs), [Sessions](/tools/sdk/references/operations/sessions), [Visitors](/tools/sdk/references/operations/visitors) |
| Artifacts and search | [Aggregation](/tools/sdk/references/operations/aggregate), [Artifacts](/tools/sdk/references/operations/artifacts), [Releases](/tools/sdk/references/operations/releases), [Root](/tools/sdk/references/operations/root) |
| Evaluations | [Datasets](/tools/sdk/references/operations/datasets), [Experiments](/tools/sdk/references/operations/experiments), [Scorer starters](/tools/sdk/references/operations/scorer_starters), [Scorers](/tools/sdk/references/operations/scorers) |
| Files | [Files](/tools/sdk/references/operations/files) |
| Identity and access | [Identity](/tools/sdk/references/operations/auth), [invitations](/tools/sdk/references/operations/invitations), [On-behalf-of tokens](/tools/sdk/references/operations/obo), [Service accounts](/tools/sdk/references/operations/service_accounts), [Users](/tools/sdk/references/operations/users) |
| MCP | [MCP servers](/tools/sdk/references/operations/servers), [MCP tools](/tools/sdk/references/operations/tools) |
| Models and proxies | [Anthropic-compatible](/tools/sdk/references/operations/anthropic), [API proxy](/tools/sdk/references/operations/apis), [Model providers](/tools/sdk/references/operations/model_providers), [OpenAI-compatible](/tools/sdk/references/operations/openai) |
| Skills | [Insights](/tools/sdk/references/operations/insights), [Skills](/tools/sdk/references/operations/skills) |
| Telemetry ingest | [Log ingest](/tools/sdk/references/operations/logs), [Metric ingest](/tools/sdk/references/operations/metrics), [Trace ingest](/tools/sdk/references/operations/traces) |
| Workspaces and projects | [Apps](/tools/sdk/references/operations/apps), [Organisations](/tools/sdk/references/operations/organisations), [Repos](/tools/sdk/references/operations/repos), [Workspaces](/tools/sdk/references/operations/workspaces) |

The per-resource pages are generated from the operation manifest that ships in the SDK packages.

## Client structure

One namespace per **resource** — not per generated service — with the verb as
the method name: `client.agents.create(...)`, not
`client.agents.agent_create_agent(...)`. A resource can nest: `client.agents`
has a `sessions` and a `traces` sub-resource, reached as
`client.agents.sessions.list(agent_id)`.

<CodeGroup>
  ```python Python theme={null}
  from atlanai import AtlanClient

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

  agent = client.agents.create({"name": "support-triage", "workspace_id": "workspace_01example"})
  page = client.agents.list(limit=10)
  one = client.agents.get(agent.id)
  client.agents.update(agent.id, {"instructions": "Be concise."})
  ```

  ```typescript TypeScript theme={null}
  import { AtlanClient } from "@atlanai/sdk";

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

  const agent = await client.agents.create({ name: "support-triage", workspaceId: "workspace_01example" });
  const page = await client.agents.list({ limit: 10 });
  const one = await client.agents.get(agent.id);
  await client.agents.update(agent.id, { instructions: "Be concise." });
  ```
</CodeGroup>

Path parameters come first, positionally; the request body is last, as a plain
object. Method and resource names are `snake_case` in Python, `camelCase` in
TypeScript. The per-resource reference marks the exceptions: `skills.create`
and `skills.bulk_create` upload as multipart forms, the API proxy methods take
no body, and `users.traces.delete_content` takes its workspace ID from the
client's `workspace`, so set one. Operations that upload an image or file take
raw bytes (`Blob` in TypeScript) as the body.

`with_workspace()` rebinds the whole client to another workspace over the same
generated clients, so a multi-tenant process does not need a second client:

```python theme={null}
other = client.with_workspace("workspace_01other")
```

## Resources you reach most

| Resource | Covers | Reference |
| - | - | - |
| `agents` | Register, read, list, search, update, archive; sub-resources `sessions` and `traces` | [Agents](/tools/sdk/references/operations/agents) |
| `sessions` | Record a run, append transcript messages, stream events | [Sessions](/tools/sdk/references/operations/sessions) |
| `skills` | Publish, list, search, update, archive; sub-resources `traces` and `versions` | [Skills](/tools/sdk/references/operations/skills) |
| `files` | The two-step upload-ticket flow, plus reading stored content | [Files](/tools/sdk/references/operations/files) |
| `workspaces` | Create and list the workspaces a credential can reach | [Workspaces](/tools/sdk/references/operations/workspaces) |
| `datasets`, `experiments`, `scorers` | Curate test cases, record runs and results, inspect their traces, and retain scored summaries | [Evals guides](/evals/index) |
| `auth` | `whoami()` — the cheapest way to confirm a credential and its scope before a write | [Auth](/tools/sdk/references/operations/auth) |

Content operations (file bytes, skill bundles) return the stored media type,
not JSON — check the content type before parsing or you will write a corrupt
file.

Prefer the [tracing SDK](/tools/sdk/how-tos/tracing) over building session records by hand.
Use `sessions`/`agents.sessions` directly only when the runtime cannot be
instrumented.

## Errors

Every error the gateway returns is normalised to a single `AtlanAPIError`
carrying its problem document, in place of the generated per-status exception
classes, so you handle a status and a stable code rather than parsing bodies:

<CodeGroup>
  ```python Python theme={null}
  from atlanai import AtlanAPIError

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

  ```typescript TypeScript theme={null}
  import { AtlanAPIError } from "@atlanai/sdk";

  try {
    await client.skills.getEnriched("skill_01example");
  } catch (error) {
    if (error instanceof AtlanAPIError) {
      console.log(error.status, error.code, error.traceId);
    }
  }
  ```
</CodeGroup>

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. Arguments the generated client rejects before
sending, such as a missing required parameter, raise its own
validation error instead: `pydantic.ValidationError` in Python and
`RequiredError` in TypeScript.

Writes are **not** retried automatically. A retried create can duplicate an
artifact, so retry deliberately — see
[Errors and retries](/platform/references/errors-and-retries).

## Find omitted operations

Start with the [per-resource reference](/tools/sdk/references/operations/agents): together those pages list all 259. Beyond that, the operation manifest ships inside both packages and is the
canonical inventory, so you can enumerate the surface at runtime:

<CodeGroup>
  ```python Python theme={null}
  from atlanai import operations

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

  ```typescript TypeScript theme={null}
  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);
  }
  ```
</CodeGroup>

The underlying generated clients also sit under `client.raw.<service>.apis`,
keyed by the contract's service name (`agent`, `skill`, `file`, `mcp`, `model`,
`api`, `otel`, `registry`, `secret`, `eval`) rather than by resource, when you want a
generated signature rather than the facade's forwarded call.

## See also

* [Agents cookbook](/cookbooks/how-tos/agents): register an agent, attach tools and files, record a run.
* [Skills cookbook](/cookbooks/how-tos/skills): publish, retrieve, and inspect skills.
* [Trace agent runs](/tools/sdk/how-tos/tracing): spans, cost, scores, and visitor identity.
* [HTTP API](/api/references/api-reference): the underlying HTTP contract.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.