Skip to main content
Recording a session stores one completed agent run in the Registry, with who the agent served, the conversation, and how the run ended, so you can read it back and attribute it to the agent. Use it for a runtime you cannot instrument with the tracing SDK. For runs you can instrument, Send and verify traces instead; the SDK records sessions for you.

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 Atlan Trident.
  • Agent ID: The AGENT_ID of a registered agent. See Register your first Agent if you do not have one.
  • Workspace ID: The WORKSPACE_ID the agent belongs to.
Confirm AGENT_ID is set before continuing:

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

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.
A session is public by default. To omit one from other people’s project chat lists, set is_private: true in the create body. A project’s Claw skips private sessions when it reads its project’s chats. Reads of a private session are served to its person alone (the person the run was for, else its creator): anyone else’s read returns not found, and in the app a link to such a chat says This chat isn’t available.Copy the session id from the response. You need it for every call in this guide.
2

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

Verify stored session

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.
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 before continuing.
4

Save your session ID

Export the session ID so it is ready without a lookup later:

Troubleshooting

If a retried create duplicated the session, see Retried create duplicated session.

Next steps

See also