Skip to content

TraceStore Interface

TraceStore is the abstract interface for persisting agent traces, spans, sessions, and configuration snapshots. It defines both the write path (called during agent execution) and the read path (used by the UI and export tools).

Import

import {
  TraceStore,
  TraceStoreConfig,
  TraceFilter,
  TracePage,
  SessionFilter,
  SessionPage,
  TraceInput,
  TraceEndInput,
  SpanInput,
} from "@modernpath/agent-framework";

TraceStoreConfig

interface TraceStoreConfig {
  captureContent: boolean;
  defaultTags?: string[];
}
Property Type Description
captureContent boolean When true, full prompts and responses are stored in spans (for dev/eval). When false, only metadata (lengths, keys) is stored (for production audit).
defaultTags string[] Tags automatically added to every new trace.

TraceStore Methods

Write Path

Method Signature Description
startTrace startTrace(trace: TraceInput): Promise<void> Creates a trace in "running" state. Called at the start of BaseAgent.execute().
endTrace endTrace(traceId: string, result: TraceEndInput): Promise<void> Finalizes a trace with output, status, timing, and token counts.
addSpan addSpan(span: SpanInput): Promise<void> Records a sub-operation span (LLM call, tool call, retrieval, etc.).
setApiIO setApiIO(traceId: string, io: { apiInput?: any; apiOutput?: any }): Promise<void> Stamps API-level input/output onto an existing trace (called from the handler layer).

Session Management

Method Signature Description
upsertSession upsertSession(session: Session): Promise<void> Creates or updates a session document.

Config Snapshots

Method Signature Description
ensureConfigSnapshot ensureConfigSnapshot(snapshot: ConfigSnapshot): Promise<void> Idempotent write: if the snapshotId already exists, this is a no-op.
getConfigSnapshot getConfigSnapshot(snapshotId: string): Promise<ConfigSnapshot \| null> Reads a config snapshot (immutable, cacheable).

Read Path

Method Signature Description
getTrace getTrace(traceId: string): Promise<Trace \| null> Retrieves a single trace by ID.
listTraces listTraces(filter: TraceFilter): Promise<TracePage> Lists traces matching the filter, ordered by startedAt descending.
getSpans getSpans(traceId: string): Promise<Span[]> Retrieves all spans for a trace, ordered by startedAt ascending.
getSession getSession(sessionId: string): Promise<Session \| null> Retrieves a session by ID.
listSessions listSessions(filter: SessionFilter): Promise<SessionPage> Lists sessions matching the filter, ordered by updatedAt descending.

Post-hoc Evaluation

Method Signature Description
setTraceScores setTraceScores(traceId: string, scores: Record<string, number>): Promise<void> Adds or updates evaluation scores on a trace. Scores are merged with existing scores.
setTraceTags setTraceTags(traceId: string, tags: string[]): Promise<void> Replaces the tags array on a trace.

Core Types

Trace

interface Trace {
  schemaVersion: 1;
  traceId: string;
  configSnapshotId?: string;
  sessionId?: string;
  parentTraceId?: string;
  agentName: string;
  agentVersion: string;
  input: {
    prompt: string;
    parameters: Record<string, any>;
    history?: Array<{ role: string; content: string }>;
    metadata?: Record<string, any>;
  };
  output?: {
    success: boolean;
    data?: any;
    error?: string;
    toolsUsed?: string[];
  };
  apiInput?: any;
  apiOutput?: any;
  status: TraceStatus;
  userId: number;
  auditingId: number;
  startedAt: Date;
  completedAt?: Date;
  durationMs?: number;
  tokens?: { input: number; output: number; total: number };
  cost?: TraceCost;
  tags: string[];
  scores?: Record<string, number>;
  metadata?: Record<string, any>;
}

Span

interface Span {
  schemaVersion: 1;
  spanId: string;
  traceId: string;
  parentSpanId?: string;
  kind: SpanKind;
  name: string;
  input?: any;
  output?: any;
  status: SpanStatus;
  error?: string;
  startedAt: Date;
  durationMs: number;
  genAiAttributes?: {
    "gen_ai.operation.name"?: string;
    "gen_ai.request.model"?: string;
    "gen_ai.response.model"?: string;
    "gen_ai.usage.input_tokens"?: number;
    "gen_ai.usage.output_tokens"?: number;
    "gen_ai.request.temperature"?: number;
    "gen_ai.request.max_tokens"?: number;
    "gen_ai.response.finish_reasons"?: string[];
    "gen_ai.system_instructions"?: string;
    [key: string]: any;
  };
  toolType?: "framework" | "mcp" | "dynamic";
  metadata?: Record<string, any>;
}

SpanKind

type SpanKind = "llm" | "retrieval" | "tool" | "agent" | "grounding" | "api" | "custom";
Kind Description
llm A Gemini LLM call (generateContent or generateContentStream).
retrieval A knowledge base / RAG search operation.
tool A tool execution via ToolRegistry.
agent A child agent execution (orchestrator delegation).
grounding A grounding decision step.
api An external API call.
custom Any other operation.

TraceStatus and SpanStatus

type TraceStatus = "running" | "completed" | "failed" | "timeout";
type SpanStatus = "ok" | "error";

TraceCost

interface TraceCost {
  total: number;
  byModel?: Record<string, number>;
  currency: string;
}

Session

interface Session {
  schemaVersion: 1;
  sessionId: string;
  userId: number;
  auditingId: number;
  createdAt: Date;
  updatedAt: Date;
  traceCount: number;
  tags: string[];
  metadata?: Record<string, any>;
}

ConfigSnapshot

interface ConfigSnapshot {
  schemaVersion: 1;
  snapshotId: string;
  agentName: string;
  agentVersion: string;
  model: string;
  modelParams: {
    temperature?: number;
    maxOutputTokens?: number;
    responseMimeType?: string;
  };
  prompts: Record<string, string>;
  responseSchemas?: Record<string, any>;
  store?: string;
  groundingConfig?: any;
  executionPlan?: any;
  tags: string[];
  source?: {
    gitSha?: string;
    deployedAt?: string;
    promptsPath?: string;
  };
  createdAt: Date;
}

Query Filters

TraceFilter

interface TraceFilter {
  agentName?: string;
  sessionId?: string;
  userId?: number;
  status?: TraceStatus;
  tags?: string[];
  after?: Date;
  before?: Date;
  limit?: number;
  offset?: number;
}

TracePage

interface TracePage {
  traces: Trace[];
  total: number;
  hasMore: boolean;
}

SessionFilter

interface SessionFilter {
  userId?: number;
  tags?: string[];
  limit?: number;
  offset?: number;
}