--- title: "AI Chat | DreamFactory Docs" source: "https://docs.dreamfactory.com/AI/ai-chat" canonical_url: "https://docs.dreamfactory.com/AI/ai-chat" converted_at: "2026-07-14T20:22:51.281Z" format: "markdown" converted_by: "html-to-md-ai" --- AI Chat lets users have natural-language conversations with their DreamFactory-governed data. Behind the scenes, an AI model runs an agentic tool-calling loop: it reads table schemas, queries data, calls stored procedures, and accesses MCP services, then synthesizes the results into a human-readable answer. All data access is governed by DreamFactory's standard role-based access control. Commercial FeatureAI Chat requires a DreamFactory commercial license (Gold or Platinum). ## How It Works[​](#how-it-works) 1. An admin creates an **AI Chat** service and links it to an **AI Connection** (the LLM provider) and a **DreamFactory role** (the data access scope). 2. A user creates a **chat session** via the API. 3. The user sends messages to the session. For each message, DreamFactory: - Passes the conversation history plus available tool definitions to the AI model. - If the AI wants to query data, it issues tool calls (get tables, get schema, query data, etc.). DreamFactory executes each tool call under the configured role's permissions and feeds the results back to the AI. - This loop continues until the AI produces a final text response or hits the tool-call limit. 4. The response (with token counts and tool-call metadata) is returned to the user. ### Tool Surface[​](#tool-surface) The AI Chat service automatically discovers which tools to expose based on the role's service access grants: - **Database services** (SQL, MongoDB, Snowflake, etc.): the AI gets `get_tables`, `get_table_schema`, `get_table_data`, `get_table_fields`, and `get_table_relationships` tools for each accessible database service. - **MCP services**: the AI discovers available MCP tools at runtime via JSON-RPC `tools/list` and can invoke them during the conversation. - **Excluded services**: AI Connection, AI Chat, System, User, Swagger, and API Docs services are never exposed to the AI. Tool names are prefixed with the service name so the AI can work across multiple databases in a single conversation. For example, a database service named `hr_db` produces tools like `hr_db__get_tables`, `hr_db__get_table_data`, etc. ## Creating an AI Chat Service[​](#creating-an-ai-chat-service) 1. In the DreamFactory admin panel, go to **Services > Create**. 2. Select **AI Chat** from the service type list. 3. Configure the required fields: ### Configuration Fields[​](#configuration-fields) FieldRequiredDescription**AI Connection**YesThe AI Connection service (Anthropic, OpenAI, etc.) that powers this chat. The connection's system prompt, allowed models, and rate limits all still apply.**AI Role (data access)**YesThe DreamFactory role the AI operates under for tool calls. Use a least-privilege role scoped to the data you want the AI to read. This is the only access bottleneck for tool calls.**Default data services**NoJSON array of service names the AI can access. Acts as a whitelist on top of the role's permissions (the AI sees the intersection). Leave blank to expose every service the role can access. Example: `["dellstore_db","hr_db"]`**Default system prompt**NoInstructions injected at the top of every chat session. Sets the assistant's persona, restricts topics, or describes the data it should query.**Max tool calls per turn**NoHard cap on tool calls in a single user turn before the AI must respond. Default: 25. Increase for complex multi-step workflows.**Max messages per session**NoHard cap on session length. Protects against runaway context costs. Default: 200. ### Security Model[​](#security-model) The AI role must appear in the linked AI Connection's **Allowed Roles** list. This is validated at session creation time. The actual data access enforcement happens at the wire level on every tool call: the orchestrator sends each request with the AI agent's JWT and the role-bound API key, and DreamFactory's standard RBAC pipeline gates the request server-side. This means: - Adding a database service to the role's access list makes it available to the AI. - Removing it removes it. No parallel configuration is needed. - If the role loses access between session creation and a tool call, the call returns a 403 which is surfaced to the AI as a tool error. ## API Endpoints[​](#api-endpoints) Assuming the AI Chat service is named `my_chat`: ### Create a Session[​](#create-a-session) **`POST /api/v2/{service-name}/session`** Creates a new chat session. **Request:** ``` { "data_services": ["dellstore_db", "hr_db"], "allowed_resources": { "dellstore_db": ["customers", "orders"] }, "title": "Q4 Sales Analysis", "system_prompt": "You are a data analyst. Always show your SQL reasoning."} ``` FieldRequiredDescription`data_services`NoOverride: limit the AI to these services for this session. Empty = use everything the role allows.`allowed_resources`NoOverride: per-service table restrictions.`title`NoSession title. Auto-set to the first message if omitted.`system_prompt`NoOverride the service's default system prompt for this session. **Response:** ``` { "id": 42, "service_id": 5, "user_id": 1, "data_services": ["dellstore_db", "hr_db"], "title": "Q4 Sales Analysis", "status": "active", "total_input_tokens": 0, "total_output_tokens": 0, "tool_call_count": 0, "created_at": "2026-06-01T10:00:00.000000Z", "updated_at": "2026-06-01T10:00:00.000000Z"} ``` ### Send a Message[​](#send-a-message) **`POST /api/v2/{service-name}/session/{session_id}`** Send a user message and receive the AI's response. **Request:** ``` { "message": "What are the top 10 customers by total order value?"} ``` **Response:** ``` { "content": "Here are the top 10 customers by total order value:\n\n| Customer | Total Orders |\n|...", "input_tokens": 2450, "output_tokens": 380, "tool_calls_made": 3, "finish_reason": "stop"} ``` The `tool_calls_made` field tells you how many database queries or MCP tool calls the AI executed to produce this answer. ### List Sessions[​](#list-sessions) **`GET /api/v2/{service-name}/session`** Returns all sessions for the current user. Admins see all sessions. **Query parameters:** ParameterDefaultDescription`status``active`Filter by status: `active`, `archived`, or `all`. ### Get Session Detail[​](#get-session-detail) **`GET /api/v2/{service-name}/session/{session_id}`** Returns the session with its message history. **Query parameters:** ParameterDefaultDescription`message_limit`50Max messages to return (most recent first, reversed to chronological order). Capped at 500. The response includes a `messages` array where each message has: FieldDescription`role``user`, `assistant`, `tool`, or `system``content`Message text or tool result`tool_calls`Array of tool calls (for assistant messages that triggered tools)`tool_name`Name of the tool called (for tool-result messages)`is_error`Whether this tool result was an error`input_tokens`Tokens consumed by this turn`output_tokens`Tokens generated by this turn`latency_ms`Response time for this turn ### Delete a Session[​](#delete-a-session) **`DELETE /api/v2/{service-name}/session/{session_id}`** Deletes the session and all its messages. Non-admins can only delete their own sessions. ## AI Chat vs. Data Chat[​](#ai-chat-vs-data-chat) DreamFactory provides two ways to chat with your data: FeatureAI Chat (df-ai-chat)Data Chat (df-ai, built-in)**Service type**Separate `ai_chat` serviceResource on `ai_connection` service (`/data-chat`)**Sessions**Persistent sessions with message historyStateless (caller manages conversation)**MCP tools**Yes. Discovers and invokes MCP service toolsNo**Access control**Dedicated AI role. Role-derived tool surface.App-based (Data Access API Key)**Tool-call tracking**Per-session counters (total_input_tokens, tool_call_count)Returned inline per request**Usage logging**Writes to `ai_usage_log` with `resource=chat-session`Writes to `ai_usage_log` with `resource=data-chat` Use **AI Chat** when you need persistent sessions, MCP integration, or fine-grained role-based scoping. Use **Data Chat** for quick stateless queries where the caller manages conversation state. ## Usage Logging and Audit[​](#usage-logging-and-audit) Every AI provider call from the orchestrator is logged to `ai_usage_log` with `resource=chat-session`, distinct from direct REST gateway calls (`resource=chat`). Both contribute to the same AI Connection's cost attribution and monthly budget calculations. Prompt logging and SIEM dispatch also apply to AI Chat sessions when configured on the underlying AI Connection. See [AI Gateway Analytics](/AI/ai-gateway) for details. ## Configuration Limits[​](#configuration-limits) SettingDefaultConfig KeyMax tool calls per message25`ai-chat.max_tool_calls_per_message`Max messages per session200`ai-chat.max_messages_per_session`Tool result max length50,000 chars`ai-chat.tool_result_max_length`Message limit max (API)500`ai-chat.message_limit_max` When a tool result exceeds the max length, it is truncated with a `[TRUNCATED]` marker instructing the AI to use filters or limits to narrow the query.