Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentmark.co/llms.txt

Use this file to discover all available pages before exploring further.

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

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);
  }
);

​
Using telemetry metadata

For cases where you don’t need explicit spans, pass session info through telemetry metadata: 
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: { userId: 'user-123', sessionId, sessionName: 'Customer Support Chat' }
    }
  });
  return await generateText(input);
}

await handleUserMessage('Hello!');
await handleUserMessage('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. 
# List sessions from the local dev server
npx agentmark api sessions list --limit 10

# List traces in a specific session
npx agentmark api sessions traces <sessionId>

# Target AgentMark Cloud
npx agentmark api sessions list --remote --limit 10
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: