Custom Apps: architecture and lifecycle

Custom Apps give you full control over your application's code, dependencies, and infrastructure. This page explains how Custom Apps work, what contract they must follow, and how they fit into the DIAL platform.

What Custom Apps are

A Custom App is a containerized service that you build, deploy, and manage yourself. It is not tied to any application type schema — its logic lives in your code and container, not in DIAL Core configuration. You register the app in DIAL Core by providing an endpoint URL, and DIAL Core routes requests to it.

Custom Apps are the right choice when you need:

• Full network access to external services and APIs.
• Custom dependencies, libraries, or runtimes.
• Your own infrastructure for state management (databases, caches, file systems).
• Complete control over deployment, scaling, and operations.

How requests flow

When a user or another app calls a Custom App through the Unified API, the request follows this path:

Client → DIAL Core → Your Custom App → DIAL Core → Client

1. A client sends a chat completion request to DIAL Core, targeting your app's deployment name.
2. DIAL Core authenticates the request, applies rate limits, and runs any configured interceptors.
3. DIAL Core forwards the request to your app's registered endpoint.
4. Your app processes the request and returns a response in the Unified API format.
5. DIAL Core forwards the response back to the client.

Because the request passes through DIAL Core, your app automatically benefits from platform governance — authentication, rate limiting, logging, and observability — without extra integration work.

The Unified API contract

Your Custom App must implement a single required endpoint:

POST /openai/deployments/<DEPLOYMENT_NAME>/chat/completions

The request and response format follows the OpenAI chat completions API. DIAL extends this format with optional fields for attachments, custom content, and stages.

Two additional endpoints are optional:

• Rate endpoint — reports token usage and cost information.
• Configuration endpoint — returns the app's configurable properties.

Building with DIAL SDK

The DIAL SDK (aidial-sdk) is a Python framework that handles protocol compliance so you can focus on business logic. It provides:

• ChatCompletion — an abstract base class. Implement the chat_completion method to define your app's behavior.
• DIALApp — a FastAPI-based wrapper that routes requests to your implementation and handles the Unified API protocol.
• Request and response helpers for streaming, attachments, tool calls, and multi-turn conversations.

A minimal Custom App using the SDK looks like this:

from aidial_sdk import DIALApp
from aidial_sdk.chat_completion import ChatCompletion, Request, Response

class MyApp(ChatCompletion):
    async def chat_completion(
        self, request: Request, response: Response
    ) -> None:
        last_message = request.messages[-1]
        with response.create_single_choice() as choice:
            choice.append_content(last_message.content or "")

app = DIALApp()
app.add_chat_completion("my-app", MyApp())

You are not required to use the SDK. Any service that implements the Unified API contract works as a Custom App — you can use any language or framework.

Registration

Custom Apps are registered in DIAL Core's config.json under applications.<app_name>. The minimum required attribute is endpoint:

{
  "applications": {
    "my-app": {
      "endpoint": "http://my-app:5000/openai/deployments/my-app/chat/completions",
      "displayName": "My Application",
      "description": "A brief description of what the app does"
    }
  }
}

Optional attributes include inputAttachmentTypes, features, interceptors, userRoles, forwardAuthToken, and defaults. See the applications configuration reference for the full list.

To make the app available to users, assign it to a role in the roles section of config.json.

Deployment

Custom Apps run as containers alongside DIAL Core. The app must be network-reachable from Core at the configured endpoint URL.

• Local development — add the app as a service in your Docker Compose file. The echo app in dial-docker-compose/application/ is a working reference.
• Production — deploy via Helm chart in Kubernetes. The app container runs in the same cluster as DIAL Core.

Lifecycle

1. Develop — write application code using the DIAL SDK or any framework that implements the Unified API.
2. Containerize — package the app in a Docker image.
3. Deploy — run the container and ensure it is reachable from DIAL Core.
4. Register — add the app to config.json with its endpoint and metadata.
5. Test — call the app through the Unified API or use it in DIAL Chat.
6. Share or publish — share with specific users or publish to the Catalog for broader access.

When Custom Apps are the right choice

Use Custom Apps when your application needs capabilities that platform-managed app types cannot provide:

• Calling external APIs and services directly.
• Using arbitrary Python packages, system libraries, or non-Python runtimes.
• Managing persistent state in your own databases.
• Running on infrastructure you control (specific hardware, GPU, region requirements).
• Implementing complex multi-step logic that benefits from a full development environment.

For simpler use cases, consider Quick Apps (no-code orchestration) or Code Apps (browser-based Python with platform hosting).