Skip to main content

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

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:
1

User submits a question

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.
2

Insights Agent reasons about the question

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
3

Text2SQL Agent generates and validates SQL

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.
4

Results are streamed back

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:
ServicePortRole
Talk2Data Service8080FastAPI REST + SSE gateway. Manages sessions, chat history, and artifact storage
Insights Agent8002Main agentic loop. Reasoning engine that orchestrates tool calls and agent delegation
Text2SQL Agent8001Specialized agent for NL-to-SQL generation, validation, and execution

​
Communication Flow

​
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:
ConceptUsage
Agent CardsEach agent exposes /.well-known/agent-card.json describing capabilities and skills
Message PartsTextPart for questions/answers, DataPart for datasource metadata, FilePart for artifacts
EventsTaskStatusUpdateEvent for progress, TaskArtifactUpdateEvent for results
StreamingServer-Sent Events (SSE) for real-time updates to the frontend

​
LLM Integration

The Data Insights agents use LiteLLM for provider-agnostic LLM access: 
from commons.llm import LLMClient

client = LLMClient()
# Model format: "provider/model"
response = await client.complete(
    model="gemini/gemini-2.0-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 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)
  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

Text-to-SQL

Deep dive into the NL-to-SQL generation pipeline.

Analysis Agent

Learn about the Insights Agent’s reasoning and analysis capabilities.

Visualizations

Understand how charts and visualizations are generated.

Data Source Setup

Connect a database to start chatting with your data.