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

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 (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 (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 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 and pass it to Service.create():

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 exposes the POST /add endpoint (lines 92-99) that routes to Service.create. Send a JSON payload matching the ServeRequest schema:

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:

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

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.
• The PromptTemplateAdapter converts between database entities and runtime StoragePromptTemplate objects.
• The Service class in 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.
• 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}