> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Chat With Data
> How the CRAFT conversational data analytics pipeline works, from natural-language questions to SQL-generated answers with multi-turn context.
# Chat With Data
CRAFT's Data Insights solution enables users to ask natural-language questions against their databases and receive instant answers, visualizations, and analytical insights. The system uses a multi-agent architecture built on Google's A2A protocol to orchestrate the full pipeline from question to answer.
## How It Works
When a user asks a question, the platform orchestrates a pipeline across three agents:
The user types a natural-language question in the chat interface (e.g., "What were the top 10 products by revenue last quarter?"). The Talk2Data Service receives the request and creates a session context.
The Insights Agent receives the question and determines the best approach. It may:
* Route directly to the Text2SQL Agent for database queries
* Execute a multi-step analysis plan for complex questions
* Generate Python code for statistical analysis
* Produce visualizations for data-oriented answers
The Text2SQL Agent converts the natural-language question into SQL using schema-aware generation. It validates the SQL with `sqlglot`, executes it against the connected database, and returns the results.
Results flow back through the agent chain via A2A events. The user sees real-time progress messages ("Analyzing schema...", "Generating SQL...", "Executing query...") followed by the final answer with data tables and optional visualizations.
## Architecture
The Data Insights system consists of three services communicating via the A2A protocol:
| Service | Port | Role |
| --------------------- | ---- | ------------------------------------------------------------------------------------- |
| **Talk2Data Service** | 8080 | FastAPI REST + SSE gateway. Manages sessions, chat history, and artifact storage |
| **Insights Agent** | 8002 | Main agentic loop. Reasoning engine that orchestrates tool calls and agent delegation |
| **Text2SQL Agent** | 8001 | Specialized agent for NL-to-SQL generation, validation, and execution |
### Communication Flow
```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#555555', 'fontFamily': 'sans-serif', 'edgeLabelBackground': '#ffffff'}}}%%
flowchart TD
Client["Browser / API Client"]
T2D["Talk2Data Service (8080)"]
IA["Insights Agent (8002)"]
SQL["Text2SQL Agent (8001)"]
DB[("Customer Database")]
Client -->|"REST + SSE"| T2D
T2D -->|"A2A (JSON-RPC 2.0 / SSE)"| IA
IA -->|"A2A (JSON-RPC 2.0 / SSE)"| SQL
SQL -->|"SQL via data connection"| DB
classDef client fill:#56B4E9,stroke:#555555,color:#000
classDef svc fill:#E69F00,stroke:#555555,color:#000
classDef data fill:#009E73,stroke:#555555,color:#000
class Client client
class T2D,IA,SQL svc
class DB data
```
## Multi-Turn Conversations
The system maintains conversation context across multiple turns using the A2A **Context ID** (mapped to the session ID):
* Each session has a conversation history stored in PostgreSQL
* Previous questions and answers are included in the LLM context window
* The Insights Agent can reference earlier results ("Now show me the same data as a pie chart")
* Session artifacts (query results, visualizations) persist for the duration of the session
* **Session context items** (`/sessions/{id}/context`) allow storing key-value metadata per session (e.g., selected data connection, user preferences)
Multi-turn context allows follow-up questions like "What about last year?" or "Break that down by region" without repeating the full original question.
## A2A Protocol Integration
All inter-agent communication uses Google's A2A protocol:
| Concept | Usage |
| ----------------- | ---------------------------------------------------------------------------------------------- |
| **Agent Cards** | Each agent exposes `/.well-known/agent-card.json` describing capabilities and skills |
| **Message Parts** | `TextPart` for questions/answers, `DataPart` for datasource metadata, `FilePart` for artifacts |
| **Events** | `TaskStatusUpdateEvent` for progress, `TaskArtifactUpdateEvent` for results |
| **Streaming** | Server-Sent Events (SSE) for real-time updates to the frontend |
## LLM Integration
The Data Insights agents use **LiteLLM** for provider-agnostic LLM access:
```python theme={null}
from commons.llm import LLMClient
client = LLMClient()
# Model format: "provider/model"
response = await client.complete(
model="vertex_ai/gemini-3.5-flash",
messages=[{"role": "user", "content": question}]
)
```
Supported providers include Gemini, GPT, Claude, and any LiteLLM-compatible model. LLM observability is provided by **Langfuse** when `LANGFUSE_HOST` is configured, traces every LLM call with token counts, cost, and latency. See [Langfuse Setup](/guides/langfuse-setup) for observability configuration.
## Data Connection Requirements
Chat with Data requires a registered data connection in the platform:
1. Register a PostgreSQL database via the Assets API (see [Data Source Setup](/guides/data-source-setup))
2. Create a session linked to the data connection ID
3. The Text2SQL Agent fetches the database schema and uses it for context-aware SQL generation
## Next Steps
Deep dive into the NL-to-SQL generation pipeline.
Learn about the Insights Agent's reasoning and analysis capabilities.
Understand how charts and visualizations are generated.
Connect a database to start chatting with your data.