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

# Record session

> Create a session record against a registered agent, append a transcript, and read the session back by ID.

A session is the Registry's record of one agent run. It captures who the agent
served, the conversation that happened, and how the run ended.

This guide shows you how to record a completed session against a registered
agent: create the session record, append a transcript, and read the session
back to confirm everything is stored.

## Before you begin

Before you start, make sure you have:

* **Bearer credential and shell variables**: `ATLAN_GATEWAY_URL` and
  `ATLAN_TOKEN` set in your shell. See
  [Connect to Agent Registry](/api/tutorials/quickstart#prepare-your-shell).
* **Agent ID**: The `AGENT_ID` of a registered agent. See
  [Register an agent](/api/tutorials/register-agent) if you do not have one.
* **Workspace ID**: The `WORKSPACE_ID` the agent belongs to.

Confirm `AGENT_ID` is set before continuing:

```bash theme={null}
echo $AGENT_ID   # should print your agent_... ID
```

## Record your session

These calls create the session record, add its transcript, and confirm both
are stored. Run them in order: the session must exist before you can append
messages to it.

<Steps>
  <Step title="Create your session record">
    A session record holds the metadata for one agent run: which agent ran, in
    which workspace, when it ran, and how it ended. Use the original execution
    time for `source_created_at`, not the current time. The Registry uses this
    field to represent when the run actually happened.

    ```js theme={null}
    const session = await atlan("/agent/v1/sessions", {
      method: "POST",
      body: JSON.stringify({
        name: "session-001",
        workspace_id: process.env.WORKSPACE_ID,
        subject_kind: "agent",
        subject_id: process.env.AGENT_ID,
        session_status: "completed",
        title: "My first session",
        model_id: "claude-sonnet-5",
        stop_reason: "end_turn",
        source_created_at: "2026-10-02T09:00:00Z",
      }),
    });

    console.log(session.id);
    ```

    Copy the session `id` from the response. You need it for every call
    in this guide.
  </Step>

  <Step title="Append your transcript">
    Messages are the actual conversation the agent had. `sequence_number` fixes
    the order and is zero-based. Send the user turn first, then the assistant
    reply.

    ```js theme={null}
    await atlan(`/agent/v1/sessions/${session.id}/messages`, {
      method: "POST",
      body: JSON.stringify({
        name: "session-001-msg-0",
        workspace_id: process.env.WORKSPACE_ID,
        sequence_number: 0,
        message_role: "user",
        content: "What can you help me with today?",
      }),
    });

    await atlan(`/agent/v1/sessions/${session.id}/messages`, {
      method: "POST",
      body: JSON.stringify({
        name: "session-001-msg-1",
        workspace_id: process.env.WORKSPACE_ID,
        sequence_number: 1,
        message_role: "assistant",
        content: "I can help you test and explore the Agent Registry API.",
      }),
    });
    ```

    <Warning>
      Session and message creates are not retried automatically. A retried
      create produces a duplicate record. `sequence_number` orders messages
      but does not deduplicate them. Read the transcript back before appending
      more, and retry only when you are certain a message was not recorded.
    </Warning>
  </Step>

  <Step title="Read your session back">
    A successful create response confirms the Registry accepted the request. A
    read back by ID confirms the session and its messages are stored and
    accessible to your credential.

    ```js theme={null}
    const record = await atlan(`/agent/v1/sessions/${session.id}`);
    console.log(record);

    const messages = await atlan(`/agent/v1/sessions/${session.id}/messages`);
    console.log(messages);
    ```

    Confirm the session shows the correct agent, workspace, and status.
    Confirm the messages list shows both turns in the right order. If either
    read returns an error, see
    [Errors and retries](/platform/references/errors-and-retries) before
    continuing.
  </Step>

  <Step title="Save your session ID">
    Export the session ID so it is ready without a lookup later:

    ```bash theme={null}
    export SESSION_ID="<your-session-id>"
    ```
  </Step>
</Steps>

## See also

[Inspect session](/api/how-tos/inspect-trace): list sessions for an agent,
read a session by ID, and explore its transcript and metadata.

[Errors and retries](/platform/references/errors-and-retries): error codes,
causes, and when to retry.


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