Conversations¶

Gaia tracks dialogue sessions through conversations — persistent, server-side threads that accumulate query/response pairs so the LLM can reference prior context when answering follow-up questions.

This page covers how conversations are created, continued, listed, and managed.

How Conversations Work¶

sequenceDiagram
    participant User
    participant Gaia

    User->>Gaia: POST /ask (no conversationId)
    Gaia-->>User: response + conversationId: "abc-123"

    User->>Gaia: POST /ask (conversationId: "abc-123")
    Gaia-->>User: response (includes prior context)

    User->>Gaia: POST /ask (conversationId: "abc-123")
    Gaia-->>User: response (includes full history)

Every call to /ask (or /ask/stream) can include a conversationId. If you omit it, Gaia creates a new conversation and returns its ID in the response. If you include it, Gaia appends the new exchange to the existing thread.

The LLM sees the accumulated history when generating its answer, which allows it to resolve pronouns ("it", "that service") and follow-up references naturally.

Starting a New Conversation¶

Simply call ask() without a conversationId:

import asyncio
from gaia_sdk import GaiaClient

async def main():
    async with GaiaClient(api_key="YOUR_API_KEY") as gaia:
        response = await gaia.ask(
            dataset_names=["engineering-docs"],
            query="What databases do we use in production?",
        )

        print(response.response_string)
        print(f"Conversation ID: {response.conversation_id}")
        print(f"Conversation Name: {response.conversation_name}")

asyncio.run(main())

Gaia auto-generates a conversationName based on the first query (e.g., "Production databases"). You can rename it later.

Continuing a Conversation¶

Pass the conversationId from the previous response:

async with GaiaClient(api_key="YOUR_API_KEY") as gaia:

    # Turn 1
    r1 = await gaia.ask(
        dataset_names=["engineering-docs"],
        query="What databases do we use in production?",
    )
    conv_id = r1.conversation_id

    # Turn 2 — Gaia knows "them" refers to the databases
    r2 = await gaia.ask(
        dataset_names=["engineering-docs"],
        query="How do we back them up?",
        conversation_id=conv_id,
    )

    # Turn 3
    r3 = await gaia.ask(
        dataset_names=["engineering-docs"],
        query="What is the RPO for each?",
        conversation_id=conv_id,
    )

    print(r3.response_string)

Listing Conversations¶

GET /conversations¶

Retrieve all conversations for the authenticated user.

async with GaiaClient(api_key="YOUR_API_KEY") as gaia:
    conversations = await gaia.list_conversations()

    for conv in conversations:
        print(
            f"  {conv['conversationId']}  "
            f"name={conv.get('conversationName', 'Untitled')!r}  "
            f"pinned={conv.get('isPinned', False)}"
        )

curl -s \
  -H "apiKey: $GAIA_API_KEY" \
  "https://helios.cohesity.com/v2/mcm/gaia/conversations" \
  | python -m json.tool

Response Fields¶

Getting Chat History¶

GET /chat-history¶

Retrieve the full message history for a specific conversation.

async with GaiaClient(api_key="YOUR_API_KEY") as gaia:
    messages = await gaia.get_chat_history("abc-123")

    for msg in messages:
        role = msg.get("role", "unknown")
        text = msg.get("content", msg.get("queryString", ""))
        print(f"[{role}] {text[:120]}")

curl -s \
  -H "apiKey: $GAIA_API_KEY" \
  "https://helios.cohesity.com/v2/mcm/gaia/chat-history?conversationId=abc-123" \
  | python -m json.tool

Managing Conversations¶

Renaming a Conversation¶

curl -s -X PUT \
  -H "apiKey: $GAIA_API_KEY" \
  -H "Content-Type: application/json" \
  "https://helios.cohesity.com/v2/mcm/gaia/conversations/abc-123" \
  -d '{"conversationName": "Database Backup Procedures"}'

Pinning / Unpinning¶

Pin important conversations so they appear at the top of the list:

curl -s -X PUT \
  -H "apiKey: $GAIA_API_KEY" \
  -H "Content-Type: application/json" \
  "https://helios.cohesity.com/v2/mcm/gaia/conversations/abc-123" \
  -d '{"isPinned": true}'

Deleting a Conversation¶

async with GaiaClient(api_key="YOUR_API_KEY") as gaia:
    await gaia.delete_conversation("abc-123")
    print("Conversation deleted.")

curl -s -X DELETE \
  -H "apiKey: $GAIA_API_KEY" \
  "https://helios.cohesity.com/v2/mcm/gaia/conversations/abc-123"

Complete Example: Multi-Turn Conversation Flow¶

A realistic end-to-end example that creates a conversation, asks a series of related questions, then retrieves and displays the full history.

import asyncio
from gaia_sdk import GaiaClient

DATASETS = ["engineering-docs", "runbooks"]

async def main():
    async with GaiaClient(api_key="YOUR_API_KEY") as gaia:

        # ── Turn 1: Open question ──────────────────────────────
        print("Turn 1:")
        r1 = await gaia.ask(
            dataset_names=DATASETS,
            query="What monitoring tools do we use?",
        )
        print(f"  {r1.response_string}\n")
        conv_id = r1.conversation_id

        # ── Turn 2: Follow-up ─────────────────────────────────
        print("Turn 2:")
        r2 = await gaia.ask(
            dataset_names=DATASETS,
            query="How are alerts configured for the primary one?",
            conversation_id=conv_id,
        )
        print(f"  {r2.response_string}\n")

        # ── Turn 3: Drill deeper ──────────────────────────────
        print("Turn 3:")
        r3 = await gaia.ask(
            dataset_names=DATASETS,
            query="Show me the escalation policy for P1 alerts.",
            conversation_id=conv_id,
        )
        print(f"  {r3.response_string}\n")

        # ── Retrieve full history ─────────────────────────────
        print("=" * 60)
        print("Full conversation history:\n")
        history = await gaia.get_chat_history(conv_id)
        for i, entry in enumerate(history, 1):
            q = entry.get("queryString", entry.get("query", ""))
            a = entry.get("responseString", entry.get("response", ""))
            print(f"  [{i}] Q: {q}")
            print(f"      A: {a[:200]}…\n")

asyncio.run(main())

Best Practices¶

Conversation Retention & Privacy¶

Gaia enforces strict per-user privacy:

• Only you can view your conversations
• Other users, including administrators, cannot view, rename, or delete your conversations
• You also cannot access conversations created by other users
• Chat history is encrypted and stored (for SaaS: in Helios on AWS US servers)

Chat History Must Be Enabled¶

Chat history is a platform-level setting (not per-user). An admin must enable it in Settings > Preferences > Chat History. When disabled, conversations are not persisted.

Context Isolation¶

Gaia maintains strict context isolation across threads:

• Each conversation thread maintains independent context — one thread never influences another
• Context is retained for the last 3 questions and responses in the current session
• If you open a new tab or navigate away, Gaia starts a fresh session

To restore context after starting a new session, use the chat history API:

# Reload conversation context
history = await gaia.get_chat_history(conversation_id)

# Or use Load History in the Gaia UI

Pinning Limits¶

• You can pin up to 15 conversations (they appear at the top of the list)
• All other conversations appear in the "Recent" section
• Pinning status persists across page refreshes and sessions

# Pin via API
curl -s -X PUT \
  -H "apiKey: $GAIA_API_KEY" \
  -H "Content-Type: application/json" \
  "https://helios.cohesity.com/v2/mcm/gaia/conversations/abc-123" \
  -d '{"isPinned": true}'

What's Next¶

• Exhaustive Search — find all matching documents without LLM synthesis.
• Streaming Responses — stream answers token-by-token within a conversation.
• Session Management — manage user sessions that carry conversation state.