PPAgent 文档

Appearance

智能体 ​

智能体是PPAgent核心组件，负责连接消息源和后端模型，处理用户消息和回复，以及应用各种技能规则。智能体的主要职责是监听消息源的消息、判断是否应该响应、获取模型的响应、调用技能并将处理后的结果回传给消息源。

功能亮点 ​

  • 多实例支持：一个应用实例中可以创建多个Agent实例，彻底告别配置不够用的情况
  • 多渠道集成：一个智能体可以同时监听多个消息源
  • 丰富的消息处理能力：支持延迟发送、排队发送、消息拆分、图片提取、历史消息管理等等，为用户提供更流畅的对话体验
  • 灵活的技能系统：支持配置多个技能规则，可在消息处理前后应用不同的技能，实现复杂的消息转换和处理流程
  • 智能会话管理：支持多活跃会话管理，可根据配置自动处理多用户同时提问的情况
  • 流式响应优化：针对不同平台特性提供细粒度的消息拆分和发送控制，实现接近实时的对话体验
  • 推理过程支持：对于支持推理的模型，可展示AI的思考过程，提高交互透明度

配置详情 ​

群组响应规则配置 ​

智能体通过响应规则决定是否对某条消息进行回复。响应规则包括以下配置项：

  • instanceName: 使用的后端模型实例名称
  • respondTo: 指定触发回复的条件
    • at: 是否响应@消息
    • refered: 是否响应引用消息
    • names: 触发回复的关键名称列表

例如：

typescript
botResponseRule: {
  instanceName: "gpt-model", // 后端模型实例名称
  respondTo: {
    at: true,       // 响应@消息
    refered: true,  // 响应引用消息
    names: ["小助手", "智能体"] // 当消息包含这些名称时响应
  }
}

消息拆分配置 ​

为了提供更好的对话体验，智能体支持将长回复拆分成多条消息发送：

  • bufferWordsMinCount: 每条回复不低于多少字
  • maxSplitCount: 一次回复最多拆分成多少条
  • splitCharacters: 用于拆分句子的标记，如["。", "！", "？"]
  • maxReasoningSplitCount: 思考过程最大的拆分数量

历史消息管理 ​

智能体可以管理对话的历史消息，为模型提供上下文：

  • historyEnabled: 是否启用历史消息功能
  • historyOptions: 历史消息管理的配置项
    • expireInSeconds: 历史消息超时时间
    • maxWordsCount: 最多存储多少个字符
    • maxItemsCount: 最多存储多少条记录

发送模式配置 ​

智能体支持两种消息发送模式：

  • sendMode: 发送模式，"now"为立即发送，"queue"为排队发送
  • minSendInterval: 排队发送时的最小发送时间间隔

思考过程显示 ​

对于支持推理的模型，智能体可以显示思考过程：

  • sendReasoning: 是否显示思考过程
  • reasoningPrefix: 思考部分内容的前缀
  • contentPrefix: 回复内容的前缀

多活跃会话管理 ​

智能体支持处理多活跃会话的情况：

  • multiActiveChatInConversationMode: 多活跃会话处理模式
  • multiActiveChatInConversationTips: 多活跃会话提示信息
  • timeoutInSeconds: 会话超时时间

技能规则配置 ​

智能体可以配置多个技能规则，用于处理消息或修改回复：

  • skillRules: 技能规则列表

    • instanceName: 技能实例名称
    • skillApplyOn: 技能应用时机，"source"或"reply"，source是针对用户发送的内容应用，reply是针对大模型响应的内容应用
    • skillWhenReplyStatus: 回复时的技能应用状态，"part"或"complete"，part是流式回复时一旦有消息，就应用，complete是全部响应完成再应用

其他配置项 ​

  • splitImageFromBotText: 是否从文本消息中提取图片单独发送
  • removeImageAfterSplit: 图片拆出来后是否从原文本中移除
  • checkWavAudio: 是否检测音频为wav格式
  • fallbackAnswer: 兜底回复内容
  • sendErrorLog: 是否发送错误日志到客户端

示例配置代码 ​

以下是完整的智能体配置示例，展示了如何在代码中创建PPAgent实例并配置智能体：

typescript
const agent = new PPAgent({
    source: [
        // 消息源配置...
    ],
    bot: [
        // 后端模型配置...
    ],
    skill: [
        // 技能配置...
    ],
    agent: [
        {
            name: Agent.params.name,
            options: {
                instanceName: "default-agent", // 实例名称，必填
                sourceInstanceNames: ["source-instance"], // 监听的消息源实例名称，必填
                botResponseRule: {
                    // 响应规则，必填
                    instanceName: "bot-instance",
                    respondTo: {
                        // 或的关系
                        at: true,
                        refered: true,
                        names: ["助手"],
                    },
                },
                // 可选配置项
                splitImageFromBotText: false, // 是否从文本消息中提取图片单独发送
                removeImageAfterSplit: false, // 图片拆出来后是否从原文中移除
                bufferWordsMinCount: 70, // 每条回复不低于多少字
                maxSplitCount: 3, // 一次回复最多被拆分成多少条
                splitCharacters: ["。", "！", "？"], // 拆分句子的标记
                historyEnabled: true, // 是否启用历史消息功能
                historyOptions: {
                    expireInSeconds: 300, // 历史消息超时时间，单位秒
                    maxWordsCount: 10240, // 最多存储多少个字符
                    maxItemsCount: 30, // 最多存储多少条记录
                },
                sendMode: "queue", // 发送模式，now或queue
                minSendInterval: 1000, // 最小发送时间间隔，单位毫秒
                fallbackAnswer: "🥹，我还不支持这个消息类型呢！", // 兜底回复
                multiActiveChatInConversationMode: "pool_tips", // 多活跃会话处理模式
                multiActiveChatInConversationTips: "我当前回复完成后就会回答这个问题😀！", // 多活跃会话提示
                timeoutInSeconds: 60, // 会话超时时间，单位秒
                sendReasoning: false, // 是否显示思考过程
                reasoningPrefix: "【思考中】", // 思考部分内容的前缀
                contentPrefix: "【回复】", // 回复内容的前缀
                maxReasoningSplitCount: 3, // 思考过程最大的拆分数量
                checkWavAudio: true, // 是否检测音频为wav格式
                sendErrorLog: false, // 是否发送错误日志到客户端
                skillRules: [
                    // 技能规则列表
                    // 技能规则配置...
                ],
            },
        },
    ],
});

服务器运行请参考 install_code.md 文件。

注意事项 ​

  1. 当使用多个消息源时，需要确保每个消息源的配置都正确，特别是鉴权相关的配置。

  2. 对于不同的消息平台，建议根据平台特性调整消息拆分和发送的相关配置：

    • 对于支持流式回复的平台（如飞书），可以设置较小的bufferWordsMinCount和较大的maxSplitCount
    • 对于有消息频率限制的平台（如微信公众号），建议增加minSendInterval的值，避免触发风控

  3. 对于支持图文混排的平台（如钉钉），建议将splitImageFromBotText设置为false；而对于不支持图文混排的平台（如微信），则建议设置为true

  4. 如果后端模型已经有历史消息管理功能（如dify、coze等），则无需开启智能体的历史消息功能，避免重复管理带来的性能开销