Sessions - AgentMark Docs

Sessions group related traces together, making it easier to monitor and debug complex workflows. Track entire user interactions or multi-step processes as a single unit.

What are sessions?

A session represents a logical grouping of traces. Common examples:

A conversation with a user
A batch processing job
A multi-step workflow
A user’s session on your application

Creating sessions

There are two ways to create sessions: via span() / span_context() with session options (recommended), or via telemetry metadata on individual prompt calls.

Using `span()` with session options

TypeScript
Python

import { span } from "@agentmark-ai/sdk";
import { client } from "./agentmark.client";
import { generateText } from "ai";

const sessionId = `session-${Date.now()}`;

const { result: greeting } = await span(
  {
    name: 'handle-greeting',
    sessionId,
    sessionName: 'Customer Support Chat #12345',
    userId: 'user-123'
  },
  async (ctx) => {
    const prompt = await client.loadTextPrompt('chat.prompt.mdx');
    const input = await prompt.format({
      props: { message: 'Hello!' },
      telemetry: { isEnabled: true }
    });
    return await generateText(input);
  }
);

// Later, another trace in the same session
const { result: followUp } = await span(
  {
    name: 'handle-follow-up',
    sessionId,
    sessionName: 'Customer Support Chat #12345',
    userId: 'user-123'
  },
  async (ctx) => {
    const prompt = await client.loadTextPrompt('chat.prompt.mdx');
    const input = await prompt.format({
      props: { message: 'What can you help me with?' },
      telemetry: { isEnabled: true }
    });
    return await generateText(input);
  }
);

import time
from agentmark_sdk import span_context, SpanOptions
from agentmark_pydantic_ai_v0 import run_text_prompt
from agentmark_client import client

session_id = f"session-{int(time.time() * 1000)}"

async with span_context(SpanOptions(
    name="handle-greeting",
    session_id=session_id,
    session_name="Customer Support Chat #12345",
    user_id="user-123",
)) as ctx:
    prompt = await client.load_text_prompt("chat.prompt.mdx")
    params = await prompt.format(props={"message": "Hello!"})
    greeting = await run_text_prompt(params)

async with span_context(SpanOptions(
    name="handle-follow-up",
    session_id=session_id,
    session_name="Customer Support Chat #12345",
    user_id="user-123",
)) as ctx:
    prompt = await client.load_text_prompt("chat.prompt.mdx")
    params = await prompt.format(props={"message": "What can you help me with?"})
    follow_up = await run_text_prompt(params)

Using telemetry metadata

For cases where you don’t need explicit spans, pass session info through telemetry metadata:

TypeScript
Python

In telemetry metadata, the session/user keys must be snake_case — session_id, session_name, user_id. The gateway only promotes these snake_case keys to session fields; camelCase keys (sessionId, …) are stored as ordinary metadata and will not group traces into a session.

const sessionId = `session-${Date.now()}`;

async function handleUserMessage(message: string) {
  const prompt = await client.loadTextPrompt('chat.prompt.mdx');
  const input = await prompt.format({
    props: { message },
    telemetry: {
      isEnabled: true,
      functionId: 'chat-handler',
      metadata: { user_id: 'user-123', session_id: sessionId, session_name: 'Customer Support Chat' }
    }
  });
  return await generateText(input);
}

await handleUserMessage('Hello!');
await handleUserMessage('What can you help me with?');

session_id = f"session-{int(time.time() * 1000)}"

async def handle_user_message(message: str):
    prompt = await client.load_text_prompt("chat.prompt.mdx")
    params = await prompt.format(
        props={"message": message},
        telemetry={
            "isEnabled": True,
            "functionId": "chat-handler",
            "metadata": {"user_id": "user-123", "session_id": session_id, "session_name": "Customer Support Chat"}
        }
    )
    return await run_text_prompt(params)

await handle_user_message("Hello!")
await handle_user_message("What can you help me with?")

Viewing sessions

Sessions page with search, filters, and sortable columns

The Sessions page lists each session with columns for ID, name, user, duration, cost, tokens, and trace count. Search by session ID or name, filter by date range and user, and sort by any column. Access sessions under the Sessions tab in the Dashboard or at http://localhost:3000 locally.

Sessions API

You can list sessions and retrieve a session’s traces programmatically using the CLI or REST API. Both the local dev server and the AgentMark Cloud gateway expose /v1/sessions and /v1/sessions/{sessionId}/traces.

REST API (Cloud)
REST API (local)

# List sessions
curl "https://api.agentmark.co/v1/sessions?limit=10" \
  -H "Authorization: Bearer am_live_abc123" \
  -H "X-Agentmark-App-Id: app_abc123"

# List the traces belonging to a session
curl "https://api.agentmark.co/v1/sessions/session-1712764245/traces" \
  -H "Authorization: Bearer am_live_abc123" \
  -H "X-Agentmark-App-Id: app_abc123"

# No auth required locally
curl "http://localhost:9418/v1/sessions?limit=10"

curl "http://localhost:9418/v1/sessions/session-1712764245/traces"

Both endpoints support pagination with limit and offset. The list endpoint also supports filtering by name and userId. See the Sessions API reference for full request and response details.

Best practices

Use consistent session IDs — session-${userId}-${Date.now()}, not ${Math.random()}
Provide descriptive names — "Customer Support: Billing Issue #4532", not "Session 1"
Limit session scope — One ticket, one conversation, one batch job
Create new sessions for new interactions — Don’t reuse sessions across unrelated workflows

Tracing setup

Full span() API reference

Filtering and search

Find sessions across dimensions

Have Questions?

We’re here to help! Choose the best way to reach us:

Email us at hello@agentmark.co for support
Schedule an Enterprise Demo to learn about our business solutions

Documentation Index

​What are sessions?

​Creating sessions

​Using span() with session options

​Using telemetry metadata

​Viewing sessions

​Sessions API

​Best practices

Tracing setup

Filtering and search

​Have Questions?

What are sessions?

Creating sessions

Using `span()` with session options

Using telemetry metadata

Viewing sessions

Sessions API

Best practices

Have Questions?