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

# Operations reference

> Every management operation the SDK exposes, by resource, for Python and TypeScript.

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:

<CardGroup cols={2}>
  <Card title="Agents" href="/sdk/reference/agents">17 operations</Card>
  <Card title="Skills" href="/sdk/reference/skills">16 operations</Card>
  <Card title="Harnesses" href="/sdk/reference/harnesses">12 operations</Card>
  <Card title="Sessions" href="/sdk/reference/sessions">11 operations</Card>
  <Card title="Outputs" href="/sdk/reference/outputs">10 operations</Card>
  <Card title="Users" href="/sdk/reference/users">9 operations</Card>
  <Card title="Projects" href="/sdk/reference/projects">8 operations</Card>
  <Card title="Workspaces" href="/sdk/reference/workspaces">8 operations</Card>
</CardGroup>

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

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

## How the client is organised

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

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

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:

```python theme={null}
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](/sdk/tracing) 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:

<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({ skillId: "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.

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

## Reaching an operation this page omits

Start with the [per-resource reference](/sdk/reference/agents) — 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:

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

<Note>
  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.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Agents cookbook" icon="robot" href="/developers/agents">
    Register an agent, attach tools and files, record a run.
  </Card>

  <Card title="Skills cookbook" icon="files" href="/developers/skills">
    Publish, retrieve and inspect skills.
  </Card>

  <Card title="Tracing" icon="diagram-project" href="/sdk/tracing">
    Spans, cost, scores and Visitor identity.
  </Card>

  <Card title="API reference" icon="globe" href="/developers/api-reference">
    The underlying HTTP contract.
  </Card>
</CardGroup>