DIAL Deep Research configuration

Deep Research 0.4.0 separates backend deployment settings from each application's properties in DIAL Core. This reference is for platform engineers familiar with the service dependencies and Core configuration. The DIAL Admin guide covers the UI for application types.

Configuration sources

Source	Scope	Reference
Process environment	Core URL, server binding, logging, model deployment mappings, and optional channels	Environment variables
Core `applicationTypeSchemas`	Shared completion and property-schema endpoints	Register the application type
Core `applications`	Each instance's sources, prompts, research limits, and report settings	Application properties

The entry point loads .env from the working directory before constructing settings. Existing process variables take precedence over values loaded by dotenv.load_dotenv. Missing or invalid required deployment settings fail startup. Application properties are fetched and validated on each request. Sources: entry point, settings construction, and property loading.

Backend deployment

This Compose service fragment assumes an existing Core service named core on the same network. Model deployments and a supported MCP retrieval application must already be configured in Core.

services:
  deep-research:
    image: epam/ai-dial-deep-research-backend:0.4.0
    environment:
      DIAL_URL: http://core:8080
      APP_HOST: 0.0.0.0
      APP_PORT: "5000"
      OPIK_TRACING_ENABLED: "false"
    restart: unless-stopped

Core reaches the backend at http://deep-research:5000. The upstream container overlay uses these service names and environment overrides, but builds a local image. The fragment above selects the released image instead.

The backend's default model deployment is gpt-5.6-terra-2026-07-09. When Core uses another deployment ID, LLM_MODELS_GPT_5_6_TERRA maps this model to that ID. This changes routing, not model capabilities; see Model deployment mappings.

Register the application type

The following Core configuration fragment uses the backend's property-schema endpoint. The $id is the type identifier; application instances must reference the same value.

{
  "applicationTypeSchemas": [
    {
      "$id": "https://mydial.epam.com/custom_application_schemas/deep-research",
      "$schema": "https://dial.epam.com/application_type_schemas/schema#",
      "dial:applicationTypeDisplayName": "Deep Research",
      "dial:applicationTypeCompletionEndpoint": "http://deep-research:5000/openai/deployments/deep-research/chat/completions",
      "dial:applicationTypeSchemaEndpoint": "http://deep-research:5000/v1/configuration-support/application-schema",
      "dial:appendApplicationPropertiesHeader": false
    }
  ]
}

This follows the released type template, replacing its host-development address with the container address. The schema handler returns the property schema without type-identity root keywords. Core supplies those from the registration.

dial:appendApplicationPropertiesHeader is false in the template. The backend asks the DIAL SDK for the request's application properties; the SDK can fetch them from Core using the application ID. See Application type schemas for the registration contract.

With ENABLE_PLAYGROUND_CHANNEL=true, the playground needs a second application type. Its $id ends in deep-research-playground, and its completion endpoint uses the deep-research-playground deployment; the schema endpoint is the same. See the released playground type.

Configure an application instance

This fragment creates one application over an existing Generic RAG MCP deployment named generic-rag-mcp. Its metadata keys must match that application's documents.

{
  "applications": {
    "research-example": {
      "displayName": "Example Deep Research",
      "applicationTypeSchemaId": "https://mydial.epam.com/custom_application_schemas/deep-research",
      "applicationProperties": {
        "mcp_servers": [
          {
            "server_name": "publications",
            "server_type": "generic_rag",
            "deployment_id": "generic-rag-mcp",
            "description": "Quarterly financial reports and company newsletters.",
            "file_sharing_tool": "get_citation_url",
            "document_metadata_resource": "documents://metadata/{document_ids}",
            "document_title_key": "publication_title",
            "references_table": {
              "title": "Documents",
              "columns": [
                {"heading": "Publication", "key": "publication_title"},
                {"heading": "Published", "key": "publication_date"}
              ]
            }
          }
        ],
        "prompts": {
          "client_name": "Example organization",
          "agent_name": "Example Deep Research"
        }
      }
    }
  },
  "roles": {
    "default": {
      "limits": {
        "research-example": {}
      }
    }
  }
}

The shape follows the released instance template and its role grants. The roles fragment grants the example application to the default role; merge it with existing role settings. Access to underlying model and retrieval deployments must also be available to the caller.

deployment_id identifies the retrieval application in Core. It differs from the public research application ID, research-example, and the backend's fixed completion deployment, deep-research.

Authentication and source access

The backend enables propagate_auth_headers=True in its DIAL SDK application. Calls under DIAL_URL use the request's forwarded API key; no static backend DIAL key is configured.

Deployment-mode MCP calls go through Core and forward the request's bearer token when present. Direct-mode MCP calls use the URL and static key bundled in an environment variable. Sources: MCP client construction and connection validation.

For retrieval services that require the user's bearer token, Core's application setting forwardAuthToken controls forwarding to the research application. See Application fields and the retrieval service's own access settings.

Troubleshooting

Symptom	Configuration to check
Startup reports missing `DIAL_URL`	Supply the Core URL in the backend's process environment. There is no built-in URL default.
Startup fails after enabling Opik	The standard image omits the optional tracing extra. Leave Opik disabled or use an image containing that extra.
Application is reported as not configured	Validate `applicationProperties`: required prompts, MCP type-specific fields, connection mode, and reference tables.
A direct MCP connection fails validation	`connection` must be a bare `$env:{VAR}` reference to a JSON URL/key bundle. Inline credentials and default-placeholder forms are rejected.
Model deployment is not found	Map `LLM_MODELS_GPT_5_6_TERRA` to an available Core model deployment and check caller access.
Retrieval receives no bearer token	Check `forwardAuthToken` on the research application and deployment-mode source configuration.
Research fails at its step budget	`max_research_graph_steps` is a failure limit, distinct from `max_research_iterations`. See Research and report settings.
Another research request is rejected in the same conversation	Once research has started, subsequent turns return a conflict. A new research requires a new conversation.

See API errors for protocol behavior and log correlation.

Configuration sources​

Backend deployment​

Register the application type​

Configure an application instance​

Authentication and source access​

Troubleshooting​