智能体管理器

[English]

• 组件注册表： espressif/brookesia_agent_manager

• 辅助头文件： #include "brookesia/service_helper/agent/manager.hpp"

• 辅助类： esp_brookesia::service::helper::Manager

概述

brookesia_agent_manager 是 ESP-Brookesia 智能体管理框架核心组件，提供：

• 统一的智能体生命周期管理：通过插件机制，集中式管理智能体的初始化、激活、启动、停止、休眠和唤醒，支持智能体之间的动态切换。

• 状态机管理：基于状态机自动管理智能体的状态转换，确保状态转换的正确性和一致性。

• 智能体操作控制：支持智能体的暂停/恢复、中断说话、状态查询等操作，提供完整的智能体控制能力。

• 对话模式支持：支持实时对话（RealTime）和手动对话（Manual）两种模式，手动模式下支持手动开始/停止监听。

• 事件驱动架构：支持通用操作事件、状态变化事件、说话/监听状态事件、文本交互事件和表情事件，实现智能体与应用之间的解耦通信。

• 功能扩展支持：支持函数调用、文本处理、中断说话、表情等扩展功能，通过智能体属性配置灵活启用。

• AFE 事件处理：可选启用 AFE（音频前端）事件处理，自动响应唤醒开始/结束事件。

• 服务集成：基于服务框架，提供统一的服务接口，集成音频服务和 Device 时间同步能力。

• 持久化存储：可选搭配 brookesia_service_storage 服务持久化保存智能体激活状态和对话模式等信息。

状态机架构

brookesia_agent_manager 使用状态机管理智能体的生命周期，确保状态转换的正确性和一致性。

状态机图

flowchart TD
    A["**TimeSyncing**<br/>· 等待时间同步<br/>· 可按配置跳过"]
    B["**Ready**<br/>· 基础环境就绪<br/>· 等待激活"]
    C["**Activating**<br/>· 初始化插件资源<br/>· 准备智能体上下文"]
    D["**Activated**<br/>· 插件已激活<br/>· 可启动会话"]
    E["**Starting**<br/>· 启动会话流程<br/>· 打开所需服务"]
    F["**Started**<br/>· 智能体运行中<br/>· 可处理交互"]
    G["**Sleeping**<br/>· 进入休眠流程<br/>· 暂停活跃交互"]
    H["**Slept**<br/>· 已休眠<br/>· 等待唤醒或停止"]
    I["**WakingUp**<br/>· 恢复会话资源<br/>· 回到运行态"]
    J["**Stopping**<br/>· 停止会话<br/>· 释放运行资源"]

    A -->|"时间已同步 / 跳过"| B
    B -->|"Activate"| C
    C -->|"激活完成"| D
    D -->|"Start"| E
    E -->|"启动完成"| F
    F -->|"Sleep"| G
    G -->|"休眠完成"| H
    H -->|"Wake"| I
    I -->|"唤醒完成"| F
    F -->|"Stop"| J
    H -->|"Stop"| J
    J -->|"停止完成"| D

状态说明

状态	类型	说明
TimeSyncing	瞬态	正在同步时间，等待时间同步完成事件
Ready	稳定	就绪状态，时间已同步（或跳过），等待激活命令
Activating	瞬态	正在激活智能体，等待激活完成事件
Activated	稳定	智能体已激活，等待启动命令
Starting	瞬态	正在启动智能体，等待启动完成事件
Started	稳定	智能体已启动，可以接收音频输入和输出
Sleeping	瞬态	正在休眠智能体，等待休眠完成事件
Slept	稳定	智能体已休眠，可以唤醒或停止
WakingUp	瞬态	正在唤醒智能体，等待唤醒完成事件
Stopping	瞬态	正在停止智能体，等待停止完成事件

服务接口

函数

SetAgentInfo

描述

Set agent info.

执行要求

• 是否需要调度器: 不需要

参数

• Name

  • 类型: String

  • 是否必填: 必填

  • 描述: Agent name.

• Info

  • 类型: Object

  • 是否必填: 必填

  • 描述: Agent info as a JSON object. Example: {"api_key":"api_key_value","model":"model_name"}

Schema JSON

展开查看 JSON

{
  "name": "SetAgentInfo",
  "description": "Set agent info.",
  "require_scheduler": false,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Name",
      "description": "Agent name.",
      "type": "String",
      "required": true,
      "default_value": null
    },
    {
      "name": "Info",
      "description": "Agent info as a JSON object. Example: {\"api_key\":\"api_key_value\",\"model\":\"model_name\"}",
      "type": "Object",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI 命令

svc_call AgentManager SetAgentInfo {"Name":null,"Info":null}

SetChatMode

描述

Set chat mode.

执行要求

• 是否需要调度器: 需要

参数

• Mode

  • 类型: String

  • 是否必填: 必填

  • 描述: Chat mode. Allowed values: [Manual, RealTime]

Schema JSON

展开查看 JSON

{
  "name": "SetChatMode",
  "description": "Set chat mode.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Mode",
      "description": "Chat mode. Allowed values: [Manual, RealTime]",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI 命令

svc_call AgentManager SetChatMode {"Mode":null}

SetTargetAgent

描述

Set target agent. The agent will be activated by triggering Activate action.

执行要求

• 是否需要调度器: 需要

参数

• Name

  • 类型: String

  • 是否必填: 必填

  • 描述: Agent name to set as target.

Schema JSON

展开查看 JSON

{
  "name": "SetTargetAgent",
  "description": "Set target agent. The agent will be activated by triggering `Activate` action.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Name",
      "description": "Agent name to set as target.",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI 命令

svc_call AgentManager SetTargetAgent {"Name":null}

GetTargetAgent

描述

Get target agent name.

执行要求

• 是否需要调度器: 需要

参数

• 无。

返回值

• 类型: String

• 描述: Example: "Coze"

Schema JSON

展开查看 JSON

{
  "name": "GetTargetAgent",
  "description": "Get target agent name.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "String",
    "description": "Example: \"Coze\""
  }
}

CLI 命令

svc_call AgentManager GetTargetAgent

GetAgentNames

描述

Get agent names.

执行要求

• 是否需要调度器: 需要

参数

• 无。

返回值

• 类型: Array

• 描述: Example: ["Agent1", "Agent2"]

Schema JSON

展开查看 JSON

{
  "name": "GetAgentNames",
  "description": "Get agent names.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "Array",
    "description": "Example: [\"Agent1\", \"Agent2\"]"
  }
}

CLI 命令

svc_call AgentManager GetAgentNames

GetAgentAttributes

描述

Get agent attributes.

执行要求

• 是否需要调度器: 不需要

参数

• Name

  • 类型: String

  • 是否必填: 可选

  • 默认值: ""

  • 描述: Agent name (optional). Returns all agents when omitted.

返回值

• 类型: Array

• 描述: Example: [{"name":"Agent","operation_timeout":{"activate":1000,"start":1000,"sleep":1000,"wake_up":1000,"stop":1000},"support_general_functions":[],"support_general_events":[],"require_time_sync":false}]

Schema JSON

展开查看 JSON

{
  "name": "GetAgentAttributes",
  "description": "Get agent attributes.",
  "require_scheduler": false,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Name",
      "description": "Agent name (optional). Returns all agents when omitted.",
      "type": "String",
      "required": false,
      "default_value": ""
    }
  ],
  "return_value": {
    "type": "Array",
    "description": "Example: [{\"name\":\"Agent\",\"operation_timeout\":{\"activate\":1000,\"start\":1000,\"sleep\":1000,\"wake_up\":1000,\"stop\":1000},\"support_general_functions\":[],\"support_general_events\":[],\"require_time_sync\":false}]"
  }
}

CLI 命令

svc_call AgentManager GetAgentAttributes {"Name":null}

GetChatMode

描述

Get chat mode.

执行要求

• 是否需要调度器: 需要

参数

• 无。

返回值

• 类型: String

• 描述: Allowed values: [Manual, RealTime]. Example: "Manual"

Schema JSON

展开查看 JSON

{
  "name": "GetChatMode",
  "description": "Get chat mode.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "String",
    "description": "Allowed values: [Manual, RealTime]. Example: \"Manual\""
  }
}

CLI 命令

svc_call AgentManager GetChatMode

GetActiveAgent

描述

Get active agent name.

执行要求

• 是否需要调度器: 需要

参数

• 无。

返回值

• 类型: String

• 描述: Example: "Coze"

Schema JSON

展开查看 JSON

{
  "name": "GetActiveAgent",
  "description": "Get active agent name.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "String",
    "description": "Example: \"Coze\""
  }
}

CLI 命令

svc_call AgentManager GetActiveAgent

TriggerGeneralAction

描述

Trigger a general action.

执行要求

• 是否需要调度器: 需要

参数

• Action

  • 类型: String

  • 是否必填: 必填

  • 描述: General action. Allowed values: [TimeSync, Activate, Start, Stop, Sleep, WakeUp]

Schema JSON

展开查看 JSON

{
  "name": "TriggerGeneralAction",
  "description": "Trigger a general action.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Action",
      "description": "General action. Allowed values: [TimeSync, Activate, Start, Stop, Sleep, WakeUp]",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI 命令

svc_call AgentManager TriggerGeneralAction {"Action":null}

Suspend

描述

Suspend the agent.

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

{
  "name": "Suspend",
  "description": "Suspend the agent.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": null
}

CLI 命令

svc_call AgentManager Suspend

Resume

描述

Resume the agent.

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

{
  "name": "Resume",
  "description": "Resume the agent.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": null
}

CLI 命令

svc_call AgentManager Resume

InterruptSpeaking

描述

Interrupt speaking; the agent stops and keeps listening.

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

{
  "name": "InterruptSpeaking",
  "description": "Interrupt speaking; the agent stops and keeps listening.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": null
}

CLI 命令

svc_call AgentManager InterruptSpeaking

ManualStartListening

描述

Manually start listening. Only in Manual mode.

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

{
  "name": "ManualStartListening",
  "description": "Manually start listening. Only in `Manual` mode.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": null
}

CLI 命令

svc_call AgentManager ManualStartListening

ManualStopListening

描述

Manually stop listening. Only in Manual mode.

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

{
  "name": "ManualStopListening",
  "description": "Manually stop listening. Only in `Manual` mode.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": null
}

CLI 命令

svc_call AgentManager ManualStopListening

GetGeneralState

描述

Get general state.

执行要求

• 是否需要调度器: 需要

参数

• 无。

返回值

• 类型: String

• 描述: Allowed values: [TimeSyncing, Ready, Activating, Activated, Starting, Stopping, Started, Sleeping, WakingUp, Slept]. Example: "Started"

Schema JSON

展开查看 JSON

{
  "name": "GetGeneralState",
  "description": "Get general state.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "String",
    "description": "Allowed values: [TimeSyncing, Ready, Activating, Activated, Starting, Stopping, Started, Sleeping, WakingUp, Slept]. Example: \"Started\""
  }
}

CLI 命令

svc_call AgentManager GetGeneralState

GetSuspendStatus

描述

Get suspend status.

执行要求

• 是否需要调度器: 需要

参数

• 无。

返回值

• 类型: Boolean

• 描述: Example: false

Schema JSON

展开查看 JSON

{
  "name": "GetSuspendStatus",
  "description": "Get suspend status.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "Boolean",
    "description": "Example: false"
  }
}

CLI 命令

svc_call AgentManager GetSuspendStatus

GetSpeakingStatus

描述

Get speaking status.

执行要求

• 是否需要调度器: 需要

参数

• 无。

返回值

• 类型: Boolean

• 描述: Example: true

Schema JSON

展开查看 JSON

{
  "name": "GetSpeakingStatus",
  "description": "Get speaking status.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "Boolean",
    "description": "Example: true"
  }
}

CLI 命令

svc_call AgentManager GetSpeakingStatus

GetListeningStatus

描述

Get listening status.

执行要求

• 是否需要调度器: 需要

参数

• 无。

返回值

• 类型: Boolean

• 描述: Example: true

Schema JSON

展开查看 JSON

{
  "name": "GetListeningStatus",
  "description": "Get listening status.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "Boolean",
    "description": "Example: true"
  }
}

CLI 命令

svc_call AgentManager GetListeningStatus

LoadData

描述

Load persisted manager data.

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

{
  "name": "LoadData",
  "description": "Load persisted manager data.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": null
}

CLI 命令

svc_call AgentManager LoadData

ResetData

描述

Reset manager and agent data.

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

{
  "name": "ResetData",
  "description": "Reset manager and agent data.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": null
}

CLI 命令

svc_call AgentManager ResetData

事件

GeneralActionTriggered

描述

Emitted when a general action is triggered.

执行要求

• 是否需要调度器: 需要

参数

• Action

  • 类型: String

  • 描述: General action. Allowed values: [TimeSync, Activate, Start, Stop, Sleep, WakeUp]

Schema JSON

展开查看 JSON

{
  "name": "GeneralActionTriggered",
  "description": "Emitted when a general action is triggered.",
  "require_scheduler": true,
  "items": [
    {
      "name": "Action",
      "description": "General action. Allowed values: [TimeSync, Activate, Start, Stop, Sleep, WakeUp]",
      "type": "String"
    }
  ]
}

CLI 命令

svc_subscribe AgentManager GeneralActionTriggered

GeneralEventHappened

描述

Emitted when a general event occurs.

执行要求

• 是否需要调度器: 需要

参数

• Event

  • 类型: String

  • 描述: General event. Allowed values: [TimeSynced, Activated, Started, Stopped, Slept, Awake]

• IsUnexpected

  • 类型: Boolean

  • 描述: Whether the event was unexpected.

Schema JSON

展开查看 JSON

{
  "name": "GeneralEventHappened",
  "description": "Emitted when a general event occurs.",
  "require_scheduler": true,
  "items": [
    {
      "name": "Event",
      "description": "General event. Allowed values: [TimeSynced, Activated, Started, Stopped, Slept, Awake]",
      "type": "String"
    },
    {
      "name": "IsUnexpected",
      "description": "Whether the event was unexpected.",
      "type": "Boolean"
    }
  ]
}

CLI 命令

svc_subscribe AgentManager GeneralEventHappened

SuspendStatusChanged

描述

Emitted when suspend status changes.

执行要求

• 是否需要调度器: 需要

参数

• IsSuspended

  • 类型: Boolean

  • 描述: Whether the agent is suspended.

Schema JSON

展开查看 JSON

{
  "name": "SuspendStatusChanged",
  "description": "Emitted when suspend status changes.",
  "require_scheduler": true,
  "items": [
    {
      "name": "IsSuspended",
      "description": "Whether the agent is suspended.",
      "type": "Boolean"
    }
  ]
}

CLI 命令

svc_subscribe AgentManager SuspendStatusChanged

SpeakingStatusChanged

描述

Emitted when speaking status changes.

执行要求

• 是否需要调度器: 需要

参数

• IsSpeaking

  • 类型: Boolean

  • 描述: Whether the agent is speaking.

Schema JSON

展开查看 JSON

{
  "name": "SpeakingStatusChanged",
  "description": "Emitted when speaking status changes.",
  "require_scheduler": true,
  "items": [
    {
      "name": "IsSpeaking",
      "description": "Whether the agent is speaking.",
      "type": "Boolean"
    }
  ]
}

CLI 命令

svc_subscribe AgentManager SpeakingStatusChanged

ListeningStatusChanged

描述

Emitted when listening status changes.

执行要求

• 是否需要调度器: 需要

参数

• IsListening

  • 类型: Boolean

  • 描述: Whether the agent is listening.

Schema JSON

展开查看 JSON

{
  "name": "ListeningStatusChanged",
  "description": "Emitted when listening status changes.",
  "require_scheduler": true,
  "items": [
    {
      "name": "IsListening",
      "description": "Whether the agent is listening.",
      "type": "Boolean"
    }
  ]
}

CLI 命令

svc_subscribe AgentManager ListeningStatusChanged

AgentSpeakingTextGot

描述

Emitted when the agent speaks text.

执行要求

• 是否需要调度器: 需要

参数

• Text

  • 类型: String

  • 描述: Spoken text.

Schema JSON

展开查看 JSON

{
  "name": "AgentSpeakingTextGot",
  "description": "Emitted when the agent speaks text.",
  "require_scheduler": true,
  "items": [
    {
      "name": "Text",
      "description": "Spoken text.",
      "type": "String"
    }
  ]
}

CLI 命令

svc_subscribe AgentManager AgentSpeakingTextGot

UserSpeakingTextGot

描述

Emitted when the user speaks text.

执行要求

• 是否需要调度器: 需要

参数

• Text

  • 类型: String

  • 描述: User text.

Schema JSON

展开查看 JSON

{
  "name": "UserSpeakingTextGot",
  "description": "Emitted when the user speaks text.",
  "require_scheduler": true,
  "items": [
    {
      "name": "Text",
      "description": "User text.",
      "type": "String"
    }
  ]
}

CLI 命令

svc_subscribe AgentManager UserSpeakingTextGot

EmoteGot

描述

Emitted when the agent shows an emote.

执行要求

• 是否需要调度器: 需要

参数

• Emote

  • 类型: String

  • 描述: Emote name.

Schema JSON

展开查看 JSON

{
  "name": "EmoteGot",
  "description": "Emitted when the agent shows an emote.",
  "require_scheduler": true,
  "items": [
    {
      "name": "Emote",
      "description": "Emote name.",
      "type": "String"
    }
  ]
}

CLI 命令

svc_subscribe AgentManager EmoteGot

相关类型与配置

结构体、枚举、helper 方法以及完整 Doxygen API 请参考 helper 原始 API 参考。

API 参考

智能体基类

公共头文件： #include "brookesia/agent_manager/base.hpp"

Header File

• service/agent/brookesia_agent_manager/include/brookesia/agent_manager/base.hpp

Classes

class Base : public esp_brookesia::service::ServiceBase

Common base class for all agent implementations.

The class extends service::ServiceBase with agent lifecycle hooks, audio pipeline coordination, and shared state tracked by Manager and StateMachine.

Subclassed by esp_brookesia::agent::Coze, esp_brookesia::agent::Openai, esp_brookesia::agent::XiaoZhi

Public Functions

inline const AgentAttributes &get_attributes() const

Get immutable metadata describing the agent.

返回

const AgentAttributes& Agent attributes passed at construction time.

inline const AudioConfig &get_audio_config() const

Get the audio configuration used by the agent.

返回

const AudioConfig& Current encoder and decoder configuration.

智能体管理器

公共头文件： #include "brookesia/agent_manager/manager.hpp"

Header File

• service/agent/brookesia_agent_manager/include/brookesia/agent_manager/manager.hpp

Classes

class Manager : public esp_brookesia::service::ServiceBase

Service responsible for managing agent selection and shared agent state.

Public Types

enum class DataType

Persistent keys managed by the agent manager.

Values:

enumerator TargetAgent

enumerator ChatMode

enumerator Max

Public Static Functions

static inline Manager &get_instance()

Get the global agent-manager singleton.

返回

Manager& Singleton instance.