Chat Agent

Overview

The Praxiom AI chat agent is a conversational interface to the entire product loop. Instead of navigating menus and clicking through multi-step workflows, you can simply ask the agent to synthesize research, generate recommendations, draft documents, search insights, generate execution tickets, or answer questions about your product space — all within a conversation.

How It Works

Conversations

Every chat interaction happens within a conversation, scoped to a workspace and user.

{
  "workspace_id": "your-workspace-uuid",
  "title": "Q2 Onboarding Analysis"
}

Conversation Management

What the Agent Can Do

The chat agent has access to the full tool set that powers the structured UI workflows:

• Synthesize research — "Analyze my latest 5 interview uploads"
• Search insights — "What are the top pain points around checkout?"
• Generate recommendations — "Generate recommendations from the high-severity insights"
• Draft documents — "Write a PRD for the search improvement recommendation"
• Generate tickets — "Create execution tickets from my onboarding PRD"
• Search the web — "What are best practices for onboarding flows in SaaS?"
• Google Drive — "Find the competitive analysis doc in our Drive"
• Answer questions — "How many users mentioned mobile issues in our research?"
• Workspace context — The agent automatically loads your product context, existing insights, and recommendation history to give grounded answers

Slash Commands

Quick shortcuts for common workflows:

Deep Research

The /research command opens a Deep Research confirmation dialog before executing. This lets you choose a research depth and see the estimated cost upfront.

Depth options:

The dialog shows:

• Estimated credits for the selected depth
• Estimated duration in minutes
• Your remaining credits with a warning if the run would consume a large portion
• A blocked state if you lack sufficient credits (with a link to upgrade)

The cost estimate is fetched from GET /api/workspaces/{id}/research-jobs/estimate?depth={depth}.

File Attachments

The chat input includes a categorised attach menu for uploading files directly into the conversation. Click the paperclip icon to see file type categories.

Supported file types:

• Documents — PDF, DOCX, TXT, Markdown
• Spreadsheets — CSV, XLSX
• Images — PNG, JPG, GIF, WebP
• Audio — MP3, WAV, M4A
• Video — MP4, MOV

Each attachment shows as a pill below the input with:

• File type icon and truncated filename
• Processing status: pending → processing → completed or failed
• Image preview thumbnail for image and PDF attachments (via previewUrl)

You can attach up to 10 files per message. Pass attachment_ids in the streaming request body.

Vision (Image Understanding)

When you attach images or documents containing images (PDF, PPTX, DOCX), Praxiom automatically extracts visual content and sends it to Claude as vision content blocks. This means the agent can:

• Read and interpret charts, diagrams, and screenshots
• Extract text from images (OCR)
• Analyse UI mockups and wireframes
• Understand visual data in research documents

Image extraction runs through the processing pipeline — PDFs are converted to page images via PyMuPDF, PPTX/DOCX images are extracted from embedded media. The vision model used is Claude Haiku for cost efficiency.

Conversation Intelligence

Praxiom tracks rich metadata about each conversation to provide better context and enable multi-session workflows.

Purpose & Working State

The agent infers the conversation's purpose and tracks working state automatically:

Continuity Chains

Conversations can be resumed from a previous session using the resumed_from field. When you resume a conversation, the agent receives a briefing with:

• Delta — New sources, insights, and documents added since the last message
• Active — Total workspace state (source count, insight count, etc.)
• Memory — Key events and decisions recalled from prior interactions

This means the agent picks up where you left off with full awareness of what changed while you were away.

Persona System

The agent adapts its personality and expertise based on the inferred task:

The persona is selected automatically based on intent classification and can shift mid-conversation as the task evolves.

Models & Effort Levels

Choose the right model and effort level for your task:

Effort levels control how deeply the agent reasons:

Total credit cost = model weight × effort weight. For example, Opus + deep = 2 × 3 = 6 credits per operation.

Set these via the model and reasoning_mode parameters in the streaming request, or use the UI toggle.

Rich Output

The agent produces structured output blocks when appropriate:

These are rendered as rich UI components in the frontend, not just plain Markdown.

Verification & Trust

After the agent responds, you can verify the quality of its output:

• Citation coverage — Are claims backed by research sources?
• Cross-source validation — Do multiple sources confirm the same finding?
• Severity analysis — Are severity ratings justified by the evidence?
• Density scoring — How evidence-dense is the response?

Verification results appear as a trust badge on each message, with expandable details showing per-check results and citation similarity scores.

Skill Activation

When the agent detects that an installed skill is relevant to your query, it activates the skill automatically. You'll see a skill_activated event in the stream. If a relevant skill is not installed, the agent suggests it via a skill_suggestion banner.

Context-Aware Intro

When you open a new conversation, the agent provides a workspace-aware introduction via GET /api/workspaces/{workspace_id}/agent-intro. The intro adapts to your workspace state:

• Empty workspace — Guides you to upload your first research source
• Has sources, no insights — Offers to analyse your sources
• Has insights, no recommendations — Offers to generate recommendations
• Rich workspace — Open-ended, ready to help with any task

Key Concepts

Conversation Ownership

Conversations are private to the user who created them. Other workspace members cannot view your conversations. The API enforces ownership checks on all message and conversation endpoints.

Streaming

The agent streams responses in real time. The frontend connects to the SSE stream endpoint to display the agent's thinking process, tool calls, and final response as they happen. This provides immediate feedback even when the agent takes 30-60 seconds for complex operations.

Message Types

Each message has a role:

• user — Your input
• assistant — The agent's response
• tool_result — Output from a tool call (e.g., insight IDs saved, document content generated)

Messages also carry additional metadata:

• inferred_intent — The classified intent of the message
• thinking_blocks — Agent reasoning chains (when extended thinking is enabled)
• decision_context — Configuration snapshot for replay and auditing
• execution_metadata — Tool step details with timing

Multi-Agent Missions

For complex queries that require multiple distinct steps, the agent automatically classifies the query and proposes a Mission — a coordinated multi-agent execution plan.

Complexity Classification

Every query is classified before execution:

Classification uses a fast Haiku call running in parallel with intent inference — zero perceived latency.

Mission Proposal

When a complex query is detected, a Mission Proposal card appears in the conversation before any agent executes. You can:

• Launch the multi-agent mission
• Run as single agent to skip decomposition
• Edit the proposal

Real-Time Controls During Execution

While a mission runs, you can:

• Redirect a running agent with new instructions (prompt update takes effect at the next checkpoint)
• Stop an individual agent
• Spawn additional agents mid-mission

See the Missions guide and Command Center for full details.

Workspace Health Banner

When Praxiom detects data quality issues in your workspace (via entropy scanning), a dismissible Entropy Banner appears at the top of the chat panel. The banner reads:

"X high-priority issue(s) detected in your workspace data — may affect research quality"

• Amber background when high-severity issues are present
• Muted background for lower-severity issues only
• Links to the Dashboard Quality Overview for details
• Dismiss with the X button (stays dismissed for the session)

This helps you stay aware of data quality problems that could degrade synthesis and recommendation accuracy.

Context Management

For long conversations, the agent automatically compacts older messages to prevent context degradation. Compaction is lazy — it only triggers when the conversation exceeds the workflow's token threshold:

When compaction triggers, older messages are summarised using a workflow-specific prompt that preserves artifact IDs, decisions, and open questions. The most recent 15 messages are always kept verbatim.

What's Next

• Missions & Command Center — multi-agent parallel execution
• Dashboard Quality — understand your workspace health metrics
• Overnight Research Cycles — autonomous nightly experiments
• Knowledge Graph — how Praxiom builds a semantic graph from your research
• Streaming SSE — all stream event types including mission events