Record session

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.
Agent ID: The AGENT_ID of a registered agent. See Register an agent if you do not have one.
Workspace ID: The WORKSPACE_ID the agent belongs to.

Confirm AGENT_ID is set before continuing:

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.

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.

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.

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.

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.",
  }),
});

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.

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.

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

Save your session ID

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

export SESSION_ID="<your-session-id>"

Get started

Work with agents

Reference

Before you begin

Record your session

See also

​Before you begin

​Record your session

​See also

Before you begin

Record your session

See also