Skip to main content

sdac-start-conversation

Purpose​

Initializes a new conversation session for SDAC cost report analysis by creating an initial system turn in SDAC.fact_ConversationHistory. If a valid (non-expired) conversation already exists for the given sessionId, it returns the existing session rather than creating a duplicate.

Tool type​

Deterministic (write / idempotent)

Tool ID​

sdac-start-conversation

Inputs​

  • reportId (string, required, UUID) -- Cost report ID
  • userId (string, required) -- User identifier from authentication
  • sessionId (string, required) -- Browser session ID (UUID recommended)

Outputs​

  • conversationId (string) -- Session ID to use for all subsequent session tool calls
  • createdAt (string) -- ISO 8601 timestamp of when this call ran
  • isNew (boolean) -- True if a new conversation was created, false if resuming an existing one

Example output​

{
  "conversationId": "conv-7f2c6e2b",
  "createdAt": "2026-05-08T14:20:00.000Z",
  "isNew": true
}

Functional details​

  • Checks whether a conversation already exists for sessionId before inserting.
  • New conversations receive a turn 0 system message: "Conversation started for report {reportId}".
  • Conversations expire after 90 days; expired sessions are treated as non-existent and a new one is created.

Usage notes​

  • Call once at the start of each chat handler before calling sdac-log-conversation-turn.
  • The returned conversationId is always equal to the input sessionId -- it is the stable identifier for the session.
  • Use isNew to decide whether to greet the user fresh or acknowledge a resumed session.
  • Part of the session management trio: sdac-start-conversation → sdac-get-conversation-history → sdac-log-conversation-turn.

Implementation details​

  • Reads from and writes to SDAC.fact_ConversationHistory via conversationExists and insertConversationTurn DB helpers.

Code Location: packages/domain-sdac/src/tools/session/start-conversation.tool.ts