# How DB-GPT Handles Prompt Templates: A Complete Guide to Creating Custom Prompts

> Learn how DB-GPT handles prompt templates, storing them as database objects and offering SDK/API access to create and manage custom prompts.

- Repository: [eosphoros/DB-GPT](https://github.com/eosphoros-ai/db-gpt)
- Tags: how-to-guide
- Published: 2026-02-23

---

**DB-GPT stores prompt templates as first-class database objects in the `prompt_manage` table and exposes them through a Service layer that supports both Python SDK and REST API access for creating, loading, and debugging custom prompts at runtime.**

DB-GPT is an open-source AI database management framework that treats prompt templates as persistent, queryable resources rather than static configuration files. Understanding how DB-GPT manages prompt templates enables you to create, version, and reuse custom prompts across different chat scenes and agent workflows. This guide walks through the internal architecture—from the SQLAlchemy data model to the REST API endpoints—and demonstrates how to create your own custom prompts using both the Python SDK and HTTP interfaces.

## The Prompt Template Architecture

DB-GPT implements a layered architecture that separates data persistence from runtime execution. This design allows templates to be stored, versioned, and served dynamically across different agents and chat scenes.

### Data Model and Persistence

At the foundation, prompt templates are persisted in the `prompt_manage` table via the `ServeEntity` model defined in [`packages/dbgpt-serve/src/dbgpt_serve/prompt/models/models.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/prompt/models/models.py) (lines 17-41). This SQLAlchemy entity extends the base `Model` class and stores critical fields including `chat_scene`, `prompt_type`, `prompt_name`, `content`, and `input_variables`. The DAO layer (`ServeDao`) provides the database abstraction that the service layer consumes.

### The Adapter Layer

The `PromptTemplateAdapter` class in [`packages/dbgpt-serve/src/dbgpt_serve/prompt/models/prompt_template_adapter.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/prompt/models/prompt_template_adapter.py) (lines 11-40) translates between the database representation (`ServeEntity`) and the in-memory `StoragePromptTemplate` object that the LLM client consumes. This adapter ensures that stored templates are correctly formatted with their input variables before execution.

### Service Layer Operations

The `Service` class in [`packages/dbgpt-serve/src/dbgpt_serve/prompt/service/service.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/prompt/service/service.py) implements the core business logic and CRUD operations. Key methods include:

- **`create()`** – Persists new templates via the DAO using `ServeRequest` objects
- **`load_template(prompt_type, target, language)`** – Loads a concrete `PromptTemplate` for LLM consumption (lines 14-31)
- **`get_prompt_template(prompt_type, target)`** – Returns stored templates for a specific scene (lines 54-60)
- **`debug_prompt()`** – Streams live template testing against models (lines 74-84)

## Creating Custom DB-GPT Prompts

You can create custom prompts through two primary interfaces: the Python SDK for programmatic access or the REST API for external integrations.

### Method 1: Python SDK

To create a custom prompt programmatically, instantiate a `ServeRequest` from [`packages/dbgpt-serve/src/dbgpt_serve/prompt/api/schemas.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/prompt/api/schemas.py) and pass it to `Service.create()`:

```python
from dbgpt_serve.prompt.models.models import ServeRequest
from dbgpt_serve.prompt.service.service import Service
from dbgpt.component import SystemApp
from dbgpt_serve.config import ServeConfig

# Initialise system app & service (normally done by the framework)

system_app = SystemApp()
config = ServeConfig()                     # reads default config files

service = Service(system_app, config)      # Service instance

service.init_app(system_app)               # registers DAO

# Build a prompt request

my_prompt = ServeRequest(
    chat_scene="custom_chat",
    prompt_type="custom",
    prompt_name="my_greeting_prompt",
    content="Hello {user_name}, welcome to DB‑GPT!",
    input_variables="user_name",
    model="gpt-4o",
    prompt_language="en",
)

# Persist it

response = service.create(my_prompt)
print("Created prompt ID:", response.id)

```

### Method 2: REST API

The HTTP API in [`packages/dbgpt-serve/src/dbgpt_serve/prompt/api/endpoints.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/prompt/api/endpoints.py) exposes the `POST /add` endpoint (lines 92-99) that routes to `Service.create`. Send a JSON payload matching the `ServeRequest` schema:

```bash
curl -X POST http://localhost:8000/api/v1/add \
     -H "Content-Type: application/json" \
     -d '{
           "chat_scene":"custom_chat",
           "prompt_type":"custom",
           "prompt_name":"my_greeting_prompt",
           "content":"Hello {user_name}, welcome to DB‑GPT!",
           "input_variables":"user_name",
           "model":"gpt-4o",
           "prompt_language":"en"
         }'

```

Additional endpoints include `POST /update`, `POST /delete`, `POST /list`, and `POST /query_page` for full CRUD operations.

## Loading and Executing Custom Prompts

Once stored, templates can be retrieved for runtime execution or debugging.

### Retrieving Templates with load_template

The `Service.load_template` method resolves the appropriate template for a given scene. For custom types not built into the framework, it delegates to `Service.get_prompt_template` to fetch from the database:

```python

# Retrieve the ready‑to‑use PromptTemplate object

template = service.load_template(prompt_type="custom", target="custom_chat")
print(template.template)      # -> "Hello {user_name}, welcome to DB‑GPT!"

print(template.input_variables)  # -> ["user_name"]

```

### Debugging Templates in Real-Time

The `Service.debug_prompt` method enables streaming testing of templates against live models without deploying them to production agents:

```python
from dbgpt_serve.prompt.models.models import PromptDebugInput

debug_input = PromptDebugInput(
    prompt_type="custom",
    content="Hello {user_name}, how can I help you?",
    input_values={"user_name": "Alice"},
    user_input="What is the weather today?",
    debug_model="gpt-4o",
)

# The method yields Server‑Sent Events; here we simply print each chunk

async for chunk in service.debug_prompt(debug_input):
    print(chunk)   # e.g. "data: >Hello Alice, how can I help you?\n..."

```

## Summary

- **DB-GPT prompt templates** are first-class database objects stored in the `prompt_manage` table via the `ServeEntity` model in [`packages/dbgpt-serve/src/dbgpt_serve/prompt/models/models.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/prompt/models/models.py).
- The `PromptTemplateAdapter` converts between database entities and runtime `StoragePromptTemplate` objects.
- The `Service` class in [`packages/dbgpt-serve/src/dbgpt_serve/prompt/service/service.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/prompt/service/service.py) provides `create()`, `load_template()`, and `debug_prompt()` for full lifecycle management.
- Create custom prompts via the **Python SDK** using `ServeRequest` and `Service.create()`, or via the **REST API** through `POST /add` as defined in [`packages/dbgpt-serve/src/dbgpt_serve/prompt/api/endpoints.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/prompt/api/endpoints.py).
- Templates support variable interpolation through the `input_variables` field and can be tested in real-time using the streaming debug functionality.

## Frequently Asked Questions

### How does DB-GPT store custom prompt templates?

DB-GPT persists templates in a SQLAlchemy table named `prompt_manage` using the `ServeEntity` model. This model captures the template content, input variables, target scene, language, and model compatibility. The DAO layer (`ServeDao`) abstracts database operations, allowing the service layer to perform CRUD operations without raw SQL.

### Can I modify an existing prompt template without restarting DB-GPT?

Yes. Because templates are database-backed rather than file-backed, you can update them via the `POST /update` endpoint or the `Service.update()` method at runtime. The `load_template` method always fetches the latest version from the database when resolving custom prompt types, ensuring your changes take effect immediately without service restarts.

### What is the difference between `load_template` and `get_prompt_template`?

`get_prompt_template` (lines 54-60 in the service file) returns all stored templates matching a specific `prompt_type` and `target` scene from the database. In contrast, `load_template` (lines 14-31) is the higher-level resolver that returns a concrete `PromptTemplate` object ready for LLM consumption. For built-in types, `load_template` may generate templates dynamically; for custom types, it delegates to `get_prompt_template` to retrieve your stored definitions.

### How do I test a custom prompt before deploying it to an agent?

Use the `debug_prompt` method available in the `Service` class. This method accepts a `PromptDebugInput` object containing your template content, input values, and target model, then streams the rendered output via Server-Sent Events. This allows you to verify variable substitution and model responses through the API or Python SDK without affecting production chat scenes.