DB-GPT App API 实战指南：通过 chat_app 聊天、查询与列举智能应用

DB-GPT App API 实战指南：通过 chat_app 聊天、查询与列举智能应用

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT

本篇指南围绕 DB-GPT 提供的App API展开，讲解如何通过 HTTP 接口与官方dbgpt_clientPython 客户端，对已发布的智能应用（App）进行流式聊天调用、详情查询与列表获取。读完本文，你将掌握POST /api/v2/chat/completions（chat_mode=chat_app）的完整调用方式、GET /api/v2/serve/apps系列管理接口的用法，以及 App / AppDetail 两套数据模型中的全部字段含义，可直接用于二次开发或接入外部系统。

一、App API 概览与前置准备

在 DB-GPT 中，"App" 指用户通过可视化编排构建的智能体应用（如基于 AWEL 工作流或 Agent 组合而成的对话应用）。App API 提供了一条不依赖前端页面、纯 HTTP 的调用通道，方便把已发布的 App 集成进你自己的系统。

本指南涉及的三个核心接口如下：

在动手之前，请确认以下前提：

1. DB-GPT 服务已启动，默认监听http://localhost:5670（可修改服务配置）；
2. 已创建并发布一个 App，并拿到它的app_id（即下文的APP_ID/app_code）；
3. 准备 API Key：默认示例中使用dbgpt。从源码看，服务端通过service.config.api_keys配置白名单（支持逗号分隔多个 Key），请求时以Authorization: Bearer <key>传递，见 agent/chat/api/endpoints.py。若未配置api_keys，服务端默认放行所有请求；
4. 如需使用 Python 客户端，安装dbgpt-client包（其源码位于 packages/dbgpt-client）。

二、流式聊天调用 App：POST /api/v2/chat/completions

调用 App 与普通模型对话的关键区别在于两个请求参数：

• chat_mode: "chat_app"：指定当前对话走"应用"通道；
• chat_param: "{YOUR_APP_ID}"：指定要调用的具体 App（对应 App 的app_code）。

默认的chat_mode是chat_normal，从 dbgpt-client 的 schema.py 可以看到 DB-GPT 支持的完整模式枚举：

class ChatMode(Enum): CHAT_NORMAL = "chat_normal" CHAT_APP = "chat_app" CHAT_AWEL_FLOW = "chat_flow" # 调用 AWEL 工作流 CHAT_KNOWLEDGE = "chat_knowledge" # 知识库问答 CHAT_DATA = "chat_data" CHAT_DB_QA = "chat_with_db_qa" CHAT_DASHBOARD = "chat_dashboard"

2.1 Curl 方式调用

DBGPT_API_KEY=dbgpt APP_ID={YOUR_APP_ID} curl -X POST "http://localhost:5670/api/v2/chat/completions" \ -H "Authorization: Bearer $DBGPT_API_KEY" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d "{\"messages\":\"Hello\",\"model\":\"gpt-4o\", \"chat_mode\": \"chat_app\", \"chat_param\": \"$APP_ID\"}"

2.2 Python 客户端方式调用

from dbgpt_client import Client DBGPT_API_KEY = "dbgpt" APP_ID="{YOUR_APP_ID}" client = Client(api_key=DBGPT_API_KEY) async for data in client.chat_stream( messages="Introduce AWEL", model="gpt-4o", chat_mode="chat_app", chat_param=APP_ID ): print(data)

这里的Client是dbgpt_client的核心类，构造参数支持api_base（默认取环境变量DBGPT_API_BASE，缺省为http://localhost:5670/api/v2）、api_key（默认取环境变量DBGPT_API_KEY）和timeout（默认 120 秒），底层基于httpx.AsyncClient实现，见 client.py。chat_stream内部会将stream置为True并发起 SSE 请求，逐帧解析data:开头的增量消息（client.py）。

2.3 流式响应格式

服务端返回 OpenAI 风格的 SSE 流，每一帧是一个ChatCompletionStreamResponse对象，最后以data: [DONE]结束。示例：

data: {"id": "109bfc28-fe87-452c-8e1f-d4fe43283b7d", "created": 1710919480, "model": "gpt-4o", "choices": [{"index": 0, "delta": {"role": "assistant", "content": "```agent-plans\n[{\"name\": \"Introduce Awel\", \"num\": 2, \"status\": \"complete\", \"agent\": \"Human\", \"markdown\": \"```agent-messages\\n[{\\\"sender\\\": \\\"Summarizer\\\", \\\"receiver\\\": \\\"Human\\\", \\\"model\\\": \\\"gpt-4o\\\", \\\"markdown\\\": \\\"Agentic Workflow Expression Language (AWEL) ...\"}]\n```"}}]} data: [DONE]

值得注意，App 的智能体输出会以agent-plans/agent-messages的 Markdown 代码块形式封装在delta.content中，展示 Agent 的规划（plans）与最终消息（messages）。该响应结构的类型定义位于 packages/dbgpt-core/src/dbgpt/core/schema/api.py：

• id：流式响应 ID（默认形如chatcmpl-<uuid>）；
• created：创建时间戳；
• model：模型名；
• choices[].delta：增量内容，包含role、content，以及可选的reasoning_content（推理内容）；
• usage：Token 用量统计（prompt_tokens/total_tokens/completion_tokens）。

2.4 请求体参数详解

chat_stream与chat方法支持以下参数（定义见 schema.py 与 api.py）：

2.5 非流式调用

如果不需要逐字流式输出，可以使用client.chat()（非流式），它内部将stream置为False，直接返回完整的ChatCompletionResponse：

from dbgpt_client import Client client = Client(api_key="dbgpt") res = await client.chat( model="chatgpt_proxyllm", messages="Hello?", chat_mode="chat_app", chat_param=APP_ID, )

两种方式的完整对照示例可参考仓库中的 examples/client/client_chat_example.py，其中还展示了chat_knowledge、chat_flow等其他模式的写法。

三、查询单个 App：GET /api/v2/serve/apps/{app_id}

当需要获取某个 App 的完整信息（名称、描述、团队配置、Agent 节点详情等）时，使用该接口。路径参数说明：

Query Parameters

Response body：返回一个 App Object，结构与下文第五节一致。

3.1 Curl 方式

DBGPT_API_KEY=dbgpt APP_ID={YOUR_APP_ID} curl -X GET "http://localhost:5670/api/v2/serve/apps/$APP_ID" -H "Authorization: Bearer $DBGPT_API_KEY"

3.2 Python 客户端方式

from dbgpt_client import Client from dbgpt_client.app import get_app DBGPT_API_KEY = "dbgpt" app_id = "{your_app_id}" client = Client(api_key=DBGPT_API_KEY) res = await get_app(client=client, app_id=app_id)

get_app的实现位于 packages/dbgpt-client/src/dbgpt_client/app.py：它通过client.get("/apps/" + app_id)发起请求，内部自动拼接为{api_base}/serve/apps/{app_id}，随后校验返回体中的success标志，成功则反序列化为AppModel，失败则抛出携带err_code的ClientException。

四、列出 App：GET /api/v2/serve/apps

当需要枚举系统内可用的 App（例如做应用选择器）时，使用该接口。

Response body：返回一个 App Object 列表（AppModel数组）。

4.1 Curl 方式

DBGPT_API_KEY=dbgpt curl -X GET 'http://localhost:5670/api/v2/serve/apps' -H "Authorization: Bearer $DBGPT_API_KEY"

4.2 Python 客户端方式

from dbgpt_client import Client from dbgpt_client.app import list_app DBGPT_API_KEY = "dbgpt" client = Client(api_key=DBGPT_API_KEY) res = await list_app(client=client)

从服务端实现 agent/app/endpoints.py 可以看到，列表接口还支持以下可选查询参数：

list_app客户端方法解析返回体中的data.app_list字段并批量构造AppModel（app.py）。

五、App 数据模型（App Model）

无论查询还是列举，返回的 App 对象都遵循以下结构（字段定义见 dbgpt-client/schema.py）：

其中details描述了该 App 内部编排的每一个 Agent 节点，是理解"一个 App 由哪些智能体组成"的关键。

六、App 明细模型（App Detail Model）

details数组中每个元素是一个AppDetailModel，字段如下（见 dbgpt-client/schema.py）：

其中resources字段对应AgentResourceModel，其type枚举定义了 Agent 可挂载的资源类别：database（数据库）、knowledge（知识库）、internet（联网检索）、plugin（插件）、text_file/excel_file/image_file（文件类）、awel_flow（AWEL 工作流），并带有is_dynamic标志标识资源是预定义还是动态传入（见 schema.py）。通过这些字段，你可以反向解析出任意一个 App 的完整"智能体编排蓝图"。

七、服务端实现与完整管理能力

App 管理接口的服务端实现位于 packages/dbgpt-serve/src/dbgpt_serve/agent/app/endpoints.py，基于 FastAPI 路由，除本文重点讲解的查询与列举外，还暴露了完整的增删改接口：

数据层由GptsAppDao（查询列表/详情、增删改）与GptsAppCollectionDao（收藏关系）提供支持。如果你需要脱离dbgpt_client、直接用 REST 方式管理 App，可以对照上述接口进行调用；官方客户端封装的完整 CRUD 示例位于 examples/client/app_crud_example.py，其中展示了list_app与get_app的典型使用姿势。

八、常见问题与排查建议

• 401 认证失败：确认请求头Authorization: Bearer <key>中的 Key 与服务端api_keys配置一致；未配置api_keys时服务端会放行所有请求（endpoints.py）。
• 找不到 App：确认chat_param传的是app_code而非app_name；可用GET /api/v2/serve/apps先列举核对。
• 没有流式输出：确认请求体包含"stream": true（Python 端使用chat_stream而非chat），且按data:前缀逐行解析 SSE；客户端解析逻辑见 client.py。
• 端口不通：确认服务端监听地址为http://localhost:5670，或通过环境变量DBGPT_API_BASE指向实际地址。

综上，App API 是 DB-GPT 对外暴露的标准化应用接入通道：chat_mode=chat_app+chat_param=app_id完成对话集成，/serve/apps系列接口完成应用元数据管理，配合dbgpt_client可零成本嵌入到你的 Python 项目中。

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT