Conversation Management

// typescript
const sessionStore = context.store.claudeSessionStore()

// python
session_store = context.store.claude_session_store()

// agents/chat/index.ts
const conversationId = context.conversation_id ?? ''
const sessionStore = context.store.claudeSessionStore()

// Maps any business ID to a stable UUID sessionId (returns it as is if it's already a UUID; otherwise, generates one and persists it).
const sessionId = await context.store.claudeSessionBinding(conversationId)

// Checks if this sessionId has been persisted before: if yes, resumes the session; if not, treats it as a new session.
// The `dir` parameter cannot be omitted. The blob key for SessionStore is derived from the project directory. If `dir` is missing, the data can never be retrieved.
const info = await getSessionInfo(sessionId, { dir: process.cwd(), sessionStore })

const options: Record<string, any> = { model, systemPrompt, sessionStore }
if (info) {
  options.resume = sessionId       // Resumes an existing session
} else {
  options.sessionId = sessionId    // Creates a new session
}

const q = query({ prompt: message, options })

session_store = context.store.claude_session_store()
session_id = await context.store.claude_session_binding(conversation_id)
# Similarly, when calling `getSessionInfo`, determine whether to resume or create a new session. Then, include `session_store` and either `resume` or `session_id` in the options.

// openaiSession automatically resumes sessions based on the conversation id.
// typescript
const session = context.store.openaiSession(context.conversation_id)

// python
session = context.store.openai_session(context.conversation_id)

// agents/hitl/index.ts
import { RunState, run } from '@openai/agents'
const RUN_STATE_KEY = 'openai.run-state'

// — First round: Start the run. If it is interrupted, store the RunState into state. —
const result = await run(agent, message, { signal })
if (result.state.getInterruptions().length > 0) {
  await context.store.state.set(RUN_STATE_KEY, result.state.toString())  // Key: Store the RunState
  return json({ status: 'awaiting_approval' })
}
await context.store.state.delete(RUN_STATE_KEY)   // No interruption, run completed, clean up

// — Next round: Bring in the approval/rejection, read back the RunState to restore it, and resume the run. —
const stored = await context.store.state.get<string>(RUN_STATE_KEY)
const state = await RunState.fromString(agent, stored)   // Restore the interrupted state
const [approval] = state.getInterruptions()
body.approved ? state.approve(approval) : state.reject(approval)
const resumed = await run(agent, state, { signal })      // Resume the run from the breakpoint

// typescript
const checkpointer = context.store.langgraphCheckpointer
const store = context.store.langgraphStore

// python
checkpointer = context.store.langgraph_checkpointer
store = context.store.langgraph_store

// typescript
const checkpointer = context.store.langgraphCheckpointer
const store = context.store.langgraphStore

// python
checkpointer = context.store.langgraph_checkpointer
store = context.store.langgraph_store

const messageId = await context.store.appendMessage({
  conversationId: context.conversation_id,
  role: 'user',
  content: context.request.body.message,
  userId: context.request.body.userId,
  metadata: { source: 'web' },
})

message_id = await context.store.append_message(
    conversation_id=context.conversation_id,
    role="user",
    content=context.request.body["message"],
    user_id=context.request.body.get("user_id"),
    metadata={"source": "web"},
)

const messages = await context.store.getMessages({
  conversationId: context.conversation_id,
  limit: 50,
})
const reply = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: context.store.toOpenAIInput(messages),
})

messages = await context.store.get_messages(
    conversation_id=context.conversation_id,
    limit=50,
)
reply = await openai_client.chat.completions.create(
    model="gpt-4o",
    messages=context.store.to_openai_input(messages),
)

const updated = await context.store.updateMessage({
  conversationId: context.conversation_id,
  messageId: 'msg_abc123',
  content: 'corrected answer',
  metadata: { edited: true },
})

updated = await context.store.update_message(
    conversation_id=context.conversation_id,
    message_id="msg_abc123",
    content="corrected answer",
    metadata={"edited": True},
)

await context.store.deleteMessage({
  conversationId: context.conversation_id,
  messageId: 'msg_abc123',
})

await context.store.delete_message(
    conversation_id=context.conversation_id,
    message_id="msg_abc123",
)

await context.store.clearMessages({ conversationId: context.conversation_id })

await context.store.clear_messages(conversation_id=context.conversation_id)

const meta = await context.store.getConversation({
  conversationId: context.conversation_id,
})
console.log(meta.messageCount, meta.metadata?.title)

meta = await context.store.get_conversation(
    conversation_id=context.conversation_id,
)
print(meta.message_count, (meta.metadata or {}).get("title"))

const { items, nextCursor } = await context.store.listConversations({
  userId: 'u_123',
  limit: 20,
})

result = await context.store.list_conversations(user_id="u_123", limit=20)
items, next_cursor = result.items, result.next_cursor

await context.store.updateConversation({
  conversationId: context.conversation_id,
  metadata: { title: 'Product Inquiry', tag: null },  // Sets the title and removes the tag.
})

await context.store.update_conversation(
    conversation_id=context.conversation_id,
    metadata={"title": "Product Inquiry", "tag": None},
)

await context.store.deleteConversation({
  conversationId: context.conversation_id,
})

await context.store.delete_conversation(
    conversation_id=context.conversation_id,
)

const history = await context.store.getMessages({
  conversationId: context.conversation_id,
})
const resp = await anthropic.messages.create({
  model: 'claude-sonnet-4',
  max_tokens: 1024,
  messages: context.store.toAnthropicMessages(history),
})

history = await context.store.get_messages(
    conversation_id=context.conversation_id,
)
resp = await anthropic_client.messages.create(
    model="claude-sonnet-4",
    max_tokens=1024,
    messages=context.store.to_anthropic_messages(history),
)

const history = await context.store.getMessages({
  conversationId: context.conversation_id,
})
const resp = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: context.store.toOpenAIInput(history),
})

history = await context.store.get_messages(
    conversation_id=context.conversation_id,
)
resp = await openai_client.chat.completions.create(
    model="gpt-4o",
    messages=context.store.to_openai_input(history),
)

// Request start: read back the state from the previous round (or null if none exists)
const saved = await context.store.state.get<MyState>('session')

// ... Run a conversation round ...

// Request end: save the latest state back.
await context.store.state.set('session', latestState)

saved = await context.store.state.get("session")
# ... Run a round ...
await context.store.state.set("session", latest_state)

interface Message {
  messageId: string                       // msg_xxx (automatically generated by appendMessage)
  role: 'user' | 'assistant' | 'system' | 'tool'
  content: any                            // string / array / object (multimodal)
  createdAt: number                       // Timestamp in milliseconds
  metadata?: Record<string, any>          // Custom (e.g., token count, tool_call, etc.)
  updatedAt?: number                      // Present only after updateMessage
}

interface ConversationMeta {
  conversationId: string
  createdAt: number                       // Timestamp in milliseconds
  lastMessageAt: number                   // Timestamp in milliseconds
  messageCount: number
  metadata?: Record<string, any>          // Business-defined (e.g., title, user, tags, etc.)
}

interface ListConversationsResult {
  items: ConversationMeta[]
  nextCursor?: string                     // The cursor for the next page, to be passed to the after parameter.
  previousCursor?: string                 // The cursor for the previous page, to be passed to the before parameter.
}