Thanks — I’ll walk you through two straightforward options to persist chat history to an external DB and what to watch for. Which option you use depends on whether you want full real-time storage or a one-time save when a session ends. Acknowledgement • You want to save chat history to an external database. Below are ways to do that using the LiveKit Agents session APIs. Options 1) Save at session shutdown (batch) • When the session ends, read

session.history

(contains messages, roles, timestamps, tool calls, handoffs). • Convert each history item to a serializable form (e.g.,

item.to_dict()

). • Insert the serialized array into your DB (store room/session ID, timestamps, and any metadata you need). • Use a shutdown callback to perform this save. Keep the callback fast — processes may be terminated after ~60s by default. If needed, increase

shutdown_process_timeout

. Example (Python outline)

async def entrypoint(ctx: JobContext):
    session = AgentSession(...)

    async def save_history_to_db():
        history_data = [item.to_dict() for item in session.history]
        await db.insert("chat_history", {"room": ctx.room.name, "history": history_data})

    ctx.add_shutdown_callback(save_history_to_db)

When to use: simpler, smaller write volume, full-session snapshot. 2) Persist incrementally (real-time) • Listen for

conversation_item_added

events and write each new item as it arrives. • Store each item with session/room ID, timestamps, role, and any tool output so you can reconstruct the conversation later. • This reduces risk of data loss if the session crashes and supports real-time search/monitoring. Example (Python outline)

@session.on("conversation_item_added")
async def on_conversation_item(item):
    await db.insert("conversation_items", {"room": ctx.room.name, "item": item.to_dict()})

When to use: required for real-time analytics, large sessions, or low-loss requirements. Post-processing and storage tips • Normalize/store: keep separate columns/fields for role, text, timestamp, tool outputs, and any structured data (e.g., attachments). • Serialize complex contents (e.g., images) either as references (S3) or as encoded blobs depending on size and query needs. • For large histories, consider paginated retrieval or splitting per conversation item. • If you need persistent per-user state across sessions, use

userdata

or store session metadata alongside the history record. Questions to help me tailor the steps • Which language/DB are you using (Postgres, MongoDB, DynamoDB, etc.)? • Do you prefer batch saves at shutdown or incremental real-time saves? • Do you need an example schema or code sample for your specific stack? Pick one of the options above and tell me your stack and preference — I’ll provide a concrete code example and schema. Sources: Agents and handoffs | LiveKit docs | Job lifecycle | LiveKit docs | Agent session | LiveKit docs