智能体管理器

[English]

• 组件注册表： espressif/brookesia_agent_manager

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

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

概述

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

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

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

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

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

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

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

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

• 服务集成：基于服务框架，提供统一的服务接口，集成音频服务和 SNTP 服务。

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

状态机架构

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

状态机图

        stateDiagram-v2
  direction TB

  %% State Styles
  classDef Stable fill:#DEFFF8,stroke:#46EDC8,color:#378E7A,font-weight:bold;
  classDef Transient fill:#FFEFDB,stroke:#FBB35A,color:#8F632D,font-weight:bold;

  %% Initial State
  [*] --> TimeSyncing
  [*] --> Ready: Bypass

  %% =====================
  %% TimeSyncing (Optional)
  %% =====================
  state TimeSyncing {
    do_time_sync() --> poll_until_time_synced()
  }

  TimeSyncing --> Ready: Success

  %% =====================
  %% Ready
  %% =====================
  Ready --> Activating: Activate

  %% =====================
  %% Activating
  %% =====================
  state Activating {
    do_activate() --> poll_until_activated()
  }

  Activating --> Activated: Success
  Activating --> Stopping: Stop
  Activating --> Ready: Failure / Timeout

  %% =====================
  %% Activated
  %% =====================
  Activated --> Starting: Start
  Activated --> Stopping: Stop

  %% =====================
  %% Starting
  %% =====================
  state Starting {
    do_start() --> poll_until_started()
  }

  Starting --> Started: Success
  Starting --> Stopping: Stop
  Starting --> Ready: Failure / Timeout

  %% =====================
  %% Started
  %% =====================
  Started --> Sleeping: Sleep
  Started --> Stopping: Stop

  %% =====================
  %% Sleeping
  %% =====================
  state Sleeping {
    do_Sleep() --> poll_until_Slept()
  }

  Sleeping --> Slept: Success
  Sleeping --> Stopping: Stop
  Sleeping --> Ready: Failure / Timeout

  %% =====================
  %% Slept
  %% =====================
  Slept --> WakingUp: WakeUp
  Slept --> Stopping: Stop

  %% =====================
  %% WakingUp
  %% =====================
  state WakingUp {
    do_wakeup() --> poll_until_awake()
  }

  WakingUp --> Started: Success
  WakingUp --> Stopping: Stop
  WakingUp --> Ready: Failure / Timeout

  %% =====================
  %% Stopping
  %% =====================
  state Stopping {
    do_stop() --> poll_until_stopped()
  }

  Stopping --> Ready: Success / Failure / Timeout

  class Ready Stable
  class Activated Stable
  class Started Stable
  class Slept Stable
  class TimeSyncing Transient
  class Starting Transient
  class Activating Transient
  class Sleeping Transient
  class WakingUp Transient
  class Stopping Transient
    

状态说明

状态	类型	说明
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,
  "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
    }
  ]
}

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,
  "parameters": [
    {
      "name": "Mode",
      "description": "Chat mode. Allowed values: [Manual, RealTime]",
      "type": "String",
      "required": true,
      "default_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,
  "parameters": [
    {
      "name": "Name",
      "description": "Agent name to set as target.",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call AgentManager SetTargetAgent {"Name":null}

GetTargetAgent

描述

Get target agent name. Return type: string. Example: "AgentCoze"

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

{
  "name": "GetTargetAgent",
  "description": "Get target agent name. Return type: string. Example: \"AgentCoze\"",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call AgentManager GetTargetAgent

GetAgentNames

描述

Get agent names. Return type: JSON array<string>. Example: ["Agent1", "Agent2"]

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

{
  "name": "GetAgentNames",
  "description": "Get agent names. Return type: JSON array<string>. Example: [\"Agent1\", \"Agent2\"]",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call AgentManager GetAgentNames

GetAgentAttributes

描述

Get agent attributes. Return type: JSON array<object>. 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}]

执行要求

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

参数

• Name

  • 类型: String

  • 是否必填: 可选

  • 默认值: ""

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

Schema JSON

展开查看 JSON

{
  "name": "GetAgentAttributes",
  "description": "Get agent attributes. Return type: JSON array<object>. 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}]",
  "require_scheduler": false,
  "parameters": [
    {
      "name": "Name",
      "description": "Agent name (optional). Returns all agents when omitted.",
      "type": "String",
      "required": false,
      "default_value": ""
    }
  ]
}

CLI 命令

svc_call AgentManager GetAgentAttributes {"Name":null}

GetChatMode

描述

Get chat mode. Return type: string. Allowed values: [Manual, RealTime]. Example: "Manual"

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

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

CLI 命令

svc_call AgentManager GetChatMode

GetActiveAgent

描述

Get active agent name. Return type: string. Example: "AgentCoze"

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

{
  "name": "GetActiveAgent",
  "description": "Get active agent name. Return type: string. Example: \"AgentCoze\"",
  "require_scheduler": true,
  "parameters": []
}

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,
  "parameters": [
    {
      "name": "Action",
      "description": "General action. Allowed values: [TimeSync, Activate, Start, Stop, Sleep, WakeUp]",
      "type": "String",
      "required": true,
      "default_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,
  "parameters": []
}

CLI 命令

svc_call AgentManager Suspend

Resume

描述

Resume the agent.

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

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

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,
  "parameters": []
}

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,
  "parameters": []
}

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,
  "parameters": []
}

CLI 命令

svc_call AgentManager ManualStopListening

GetGeneralState

描述

Get general state. Return type: string. Allowed values: [TimeSyncing, Ready, Activating, Activated, Starting, Stopping, Started, Sleeping, WakingUp, Slept]. Example: "Started"

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

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

CLI 命令

svc_call AgentManager GetGeneralState

GetSuspendStatus

描述

Get suspend status. Return type: boolean. Example: false

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

{
  "name": "GetSuspendStatus",
  "description": "Get suspend status. Return type: boolean. Example: false",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call AgentManager GetSuspendStatus

GetSpeakingStatus

描述

Get speaking status. Return type: boolean. Example: true

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

{
  "name": "GetSpeakingStatus",
  "description": "Get speaking status. Return type: boolean. Example: true",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call AgentManager GetSpeakingStatus

GetListeningStatus

描述

Get listening status. Return type: boolean. Example: true

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

{
  "name": "GetListeningStatus",
  "description": "Get listening status. Return type: boolean. Example: true",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call AgentManager GetListeningStatus

ResetData

描述

Reset manager and agent data.

执行要求

• 是否需要调度器: 需要

参数

• 无。

Schema JSON

展开查看 JSON

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

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

• 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

• 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.