Before you begin
Before you start, make sure you have:- Bearer credential and shell variables:
ATLAN_GATEWAY_URLandATLAN_TOKENset in your shell. See Connect to Atlan Trident. - Agent ID: The
AGENT_IDof a registered agent. See Register your first Agent if you do not have one. - Workspace ID: The
WORKSPACE_IDthe agent belongs to.
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 A session is public by default. To omit one from other people’s
project chat lists, set
source_created_at, not the current time. The Registry uses this
field to represent when the run actually happened.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.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
- Inspect session: List an agent’s sessions and read a transcript.
See also
- Register agents through API: Providers, tools, tracing, and the session lifecycle.
- Errors and retries: Error codes, causes, and when to retry.