Quick Start

快速接入

1. 配置模型

AgentKit 示例程序支持从本地配置读取模型信息。可以在运行目录或 UIGearsAgentKit 目录放置 agentkit.local.json。

OpenAI-compatible 配置示例：

{
  "provider": "openai",
  "baseUrl": "https://api.example.com/v1",
  "apiKey": "your-api-key",
  "model": "your-model",
  "maxTokens": 1024,
  "timeoutMs": 60000,
  "stream": true
}

DeepSeek 配置示例：

{
  "provider": "deepseek",
  "baseUrl": "https://api.deepseek.com",
  "apiKey": "your-deepseek-api-key",
  "model": "deepseek-v4-flash",
  "maxTokens": 1024,
  "timeoutMs": 60000,
  "stream": true
}

也可以通过环境变量配置真实模型。OpenAI-compatible provider 使用 OPENAI_API_KEY、OPENAI_BASE_URL、OPENAI_MODEL；DeepSeek provider 使用 DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL、DEEPSEEK_MODEL。

没有配置时，示例程序会自动使用 Mock 模型离线运行。

2. 创建聊天请求

using namespace UIGQtLib::QtAgent;

ChatRequest request;
request.addSystemMessage("你是 Qt 应用中的智能助手。");
request.addUserMessage("分析当前设备状态。");

ChatReply* reply = model->chat(request, {}, parent);

3. 注册工具

ToolRegistry registry;
registry.registerTool(new FunctionTool(
    "query_device_status",
    "查询设备状态。",
    schema,
    ToolPermission::ReadOnly,
    [](const QJsonObject& args) {
        return ToolResult{true, {}, "设备状态正常。"};
    }
));

4. 运行示例程序

打开 AgentKit 示例程序后，可通过左侧能力树分别查看基础对话、模型能力、流程能力和设备监控分析示例。

Usage Guide

使用指南

模型接入

AgentKit 使用 ChatModel 抽象模型接口。首版内置：

• MockChatModel：本地离线模型，用于演示和测试。
• OpenAICompatibleModel：兼容 OpenAI Chat Completions 协议的 HTTP 客户端。
• DeepSeekModel：DeepSeek 模型客户端，默认使用 OpenAI-compatible 接口 https://api.deepseek.com 和 deepseek-v4-flash。

示例程序支持三种 provider：mock、openai、deepseek。配置文件 agentkit.local.json 中把 provider 设置为 deepseek 后，只需要填写 DeepSeek API Key 即可使用真实模型；也可以通过 DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL、DEEPSEEK_MODEL 环境变量配置。

工具调用

业务功能通过 AgentTool 或 FunctionTool 注册到 ToolRegistry。工具包含名称、说明、JSON Schema、权限和执行函数。

工具权限包括：

• ReadOnly
• Write
• Destructive
• ExternalNetwork
• FileSystem
• SystemCommand

涉及写入、文件系统或更高风险操作时，应通过审批弹窗确认。

Trace 追踪

每次工具调用会生成 ToolCallTrace，用于展示工具名称、状态、权限、输入、输出、错误和耗时。ToolCallTraceView 可直接用于产品调试界面。

工作流编排

StateGraph 使用 QJsonObject 作为状态对象。节点读取状态并返回局部更新，边和条件边决定下一步执行位置。

适合实现：

• 多步骤任务。
• 条件路由。
• 循环直到完成。
• 人工审核。
• 工具节点和模型节点组合。

Capabilities Overview

AgentKit 能力模块

Qt-UI AgentKit 的接口位于命名空间 UIGQtLib::QtAgent。建议业务代码统一引入聚合头文件：

#include "QtAgentKit.h"

本章按 AgentKit 的能力模块说明 SDK 的核心类、接口方法、参数、返回值和常见调用示例。

类关系概览

ChatModel
  ├─ MockChatModel
  ├─ OpenAICompatibleModel
  └─ DeepSeekModel

AgentTool
  └─ FunctionTool

ToolRegistry
AgentExecutor

PromptTemplate
ChatPromptTemplate
RunnableChain
RunnableParallel

StringOutputParser
JsonOutputParser
StructuredOutputParser

ChatMemory
InMemoryRetriever
SimpleRagChain

StateGraph
MemoryCheckpointer

AgentChatPanel
ModelConfigWidget
ToolCallTraceView
ApprovalDialog

选型建议

Model Chat

模型对话

模型对话模块负责统一不同模型 Provider 的调用方式。开发阶段可使用 MockChatModel 离线验证，也可以使用 OpenAICompatibleModel 接入兼容 OpenAI Chat Completions 协议的服务；对于 DeepSeek，AgentKit 提供了独立的 DeepSeekModel 入口，内部复用 OpenAI-compatible 请求格式。

核心类

支持的 Provider

ChatRequest 常用方法

ChatModel 常用方法

ChatReply 信号和方法

示例

#include "QtAgentKit.h"

using namespace UIGQtLib::QtAgent;

auto* model = new OpenAICompatibleModel(this);

ModelConfig config;
config.provider = "openai";
config.baseUrl = "https://api.example.com/v1";
config.apiKey = qgetenv("OPENAI_API_KEY");
config.model = "gpt-5.4-mini";
config.stream = true;
model->setConfig(config);

ChatRequest request;
request.addSystemMessage("你是一个 Qt 桌面应用助手。");
request.addUserMessage("说明如何在 Qt 中接入 AgentKit。");

ChatReply* reply = model->chat(request, {}, this);
connect(reply, &ChatReply::deltaReceived, this, [](const QString& delta) {
    qDebug() << delta;
});
connect(reply, &ChatReply::finished, this, [](const QString& text) {
    qDebug() << "finished:" << text;
});
connect(reply, &ChatReply::failed, this, [](const QString& error) {
    qWarning() << error;
});

示例：接入 DeepSeek

#include "QtAgentKit.h"

using namespace UIGQtLib::QtAgent;

auto* model = new DeepSeekModel(this);

ModelConfig config;
config.provider = "deepseek";
config.baseUrl = "https://api.deepseek.com";
config.apiKey = qgetenv("DEEPSEEK_API_KEY");
config.model = "deepseek-v4-flash";
config.stream = true;
model->setConfig(config);

ChatRequest request;
request.addSystemMessage("你是一个 Qt 桌面应用助手。");
request.addUserMessage("用三句话说明 AgentKit 的作用。");

ChatReply* reply = model->chat(request, {}, this);
connect(reply, &ChatReply::deltaReceived, this, [](const QString& delta) {
    qDebug() << delta;
});
connect(reply, &ChatReply::failed, this, [](const QString& error) {
    qWarning() << error;
});

Prompt and Chain

Documentation is not configured yet.

Output Parser

Documentation is not configured yet.

Memory and RAG

Documentation is not configured yet.

Tool Calling and Approval

Documentation is not configured yet.

State Workflow

Documentation is not configured yet.

UI Widgets

UI 控件

AgentKit 提供 Qt Widgets 控件，便于把 Agent 能力嵌入桌面应用。

核心控件

AgentChatPanel 方法和信号

ModelConfigWidget 方法

ToolCallTraceView 方法

ApprovalDialog 方法

示例：嵌入聊天面板和 Trace 表格

auto* chat = new AgentChatPanel(this);
auto* traceView = new ToolCallTraceView(this);
auto* executor = new AgentExecutor(this);

executor->setModel(model);
executor->setToolRegistry(registry);

connect(chat, &AgentChatPanel::sendRequested, this, [chat, executor](const QString& text) {
    chat->appendUserMessage(text);
    chat->beginAssistantMessage();
    chat->setRunning(true);
    executor->run(text);
});

connect(chat, &AgentChatPanel::stopRequested, executor, &AgentExecutor::cancel);

connect(executor, &AgentExecutor::assistantDelta, chat, &AgentChatPanel::appendDelta);
connect(executor, &AgentExecutor::assistantFinished, this, [chat](const QString&) {
    chat->finishAssistantMessage();
    chat->setRunning(false);
});
connect(executor, &AgentExecutor::traceAdded, traceView, &ToolCallTraceView::addTrace);

License

授权说明

Qt-UI AgentKit 提供试用版、基础版和完整版。

试用版

用于评估、学习和原型验证，不提供源码，不支持商用。下载内容后续补充，当前页面会保留试用入口。

基础版

包含 AgentKit 单产品完整源码，支持单项目商用，包含 1 年版本免费升级权益，提供邮件 + 工单支持。

完整版

统一价格为 ￥12,800，包含 StyleKit、WidgetKit、ChartKit、AgentKit 全系列 4 款产品完整源码，不限商用项目数量，包含 1 年版本免费升级权益，提供邮件 + 工单 + 优先支持。

下载说明

商业源码包下载内容后续补充。购买记录、下载入口和更新权益将在会员中心与订单查询页面中展示。