Agent Manager

[中文]

• Component registry: espressif/brookesia_agent_manager

• Helper header: #include "brookesia/agent_helper/manager.hpp"

• Helper class: esp_brookesia::agent::helper::Manager

Overview

brookesia_agent_manager is the core agent framework:

• Lifecycle: Plugin-based init, activate, start, stop, sleep, wake, and dynamic switching.

• State machine: Correct, consistent transitions.

• Control: Pause/resume, interrupt, status queries.

• Dialog modes: RealTime and Manual (manual listen start/stop).

• Events: Operations, state, speech/listen, text, emotes—decoupled from apps.

• Extensions: Function calling, text, interrupt, emotes via agent properties.

• AFE (optional): Wake begin/end handling.

• Services: Audio and SNTP integration.

• Persistence: Optional brookesia_service_nvs for active agent and mode.

State Machine Architecture

The manager uses a state machine for agent lifecycle.

State Diagram

        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
    

State Descriptions

State	Type	Description
TimeSyncing	Transient	Waiting for time sync.
Ready	Stable	Time OK (or skipped); waiting for activate.
Activating	Transient	Activating agent.
Activated	Stable	Activated; waiting for start.
Starting	Transient	Starting agent.
Started	Stable	Running; audio in/out enabled.
Sleeping	Transient	Entering sleep.
Slept	Stable	Asleep; can wake or stop.
WakingUp	Transient	Waking from sleep.
Stopping	Transient	Stopping agent.

Standard Include / Helper Class

• Standard include: #include \"brookesia/agent_helper/manager.hpp\"

• Helper class: esp_brookesia::agent::helper::Manager

Service Interfaces

Functions

SetAgentInfo

Description

Set agent info.

Execution

• Requires scheduler: Not required

Parameters

• Name

  • Type: String

  • Required: required

  • Description: Agent name.

• Info

  • Type: Object

  • Required: required

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

Schema JSON

Show raw 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 Command

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

SetChatMode

Description

Set chat mode.

Execution

• Requires scheduler: Required

Parameters

• Mode

  • Type: String

  • Required: required

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

Schema JSON

Show raw 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 Command

svc_call AgentManager SetChatMode {"Mode":null}

SetTargetAgent

Description

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

Execution

• Requires scheduler: Required

Parameters

• Name

  • Type: String

  • Required: required

  • Description: Agent name to set as target.

Schema JSON

Show raw 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 Command

svc_call AgentManager SetTargetAgent {"Name":null}

GetTargetAgent

Description

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

Execution

• Requires scheduler: Required

Parameters

• No parameters.

Schema JSON

Show raw JSON

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

CLI Command

svc_call AgentManager GetTargetAgent

GetAgentNames

Description

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

Execution

• Requires scheduler: Required

Parameters

• No parameters.

Schema JSON

Show raw JSON

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

CLI Command

svc_call AgentManager GetAgentNames

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}]

Execution

• Requires scheduler: Not required

Parameters

• Name

  • Type: String

  • Required: optional

  • Default: ""

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

Schema JSON

Show raw 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 Command

svc_call AgentManager GetAgentAttributes {"Name":null}

GetChatMode

Description

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

Execution

• Requires scheduler: Required

Parameters

• No parameters.

Schema JSON

Show raw JSON

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

CLI Command

svc_call AgentManager GetChatMode

GetActiveAgent

Description

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

Execution

• Requires scheduler: Required

Parameters

• No parameters.

Schema JSON

Show raw JSON

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

CLI Command

svc_call AgentManager GetActiveAgent

TriggerGeneralAction

Description

Trigger a general action.

Execution

• Requires scheduler: Required

Parameters

• Action

  • Type: String

  • Required: required

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

Schema JSON

Show raw 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 Command

svc_call AgentManager TriggerGeneralAction {"Action":null}

Suspend

Description

Suspend the agent.

Execution

• Requires scheduler: Required

Parameters

• No parameters.

Schema JSON

Show raw JSON

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

CLI Command

svc_call AgentManager Suspend

Resume

Description

Resume the agent.

Execution

• Requires scheduler: Required

Parameters

• No parameters.

Schema JSON

Show raw JSON

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

CLI Command

svc_call AgentManager Resume

InterruptSpeaking

Description

Interrupt speaking; the agent stops and keeps listening.

Execution

• Requires scheduler: Required

Parameters

• No parameters.

Schema JSON

Show raw JSON

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

CLI Command

svc_call AgentManager InterruptSpeaking

ManualStartListening

Description

Manually start listening. Only in Manual mode.

Execution

• Requires scheduler: Required

Parameters

• No parameters.

Schema JSON

Show raw JSON

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

CLI Command

svc_call AgentManager ManualStartListening

ManualStopListening

Description

Manually stop listening. Only in Manual mode.

Execution

• Requires scheduler: Required

Parameters

• No parameters.

Schema JSON

Show raw JSON

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

CLI Command

svc_call AgentManager ManualStopListening

GetGeneralState

Description

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

Execution

• Requires scheduler: Required

Parameters

• No parameters.

Schema JSON

Show raw 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 Command

svc_call AgentManager GetGeneralState

GetSuspendStatus

Description

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

Execution

• Requires scheduler: Required

Parameters

• No parameters.

Schema JSON

Show raw JSON

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

CLI Command

svc_call AgentManager GetSuspendStatus

GetSpeakingStatus

Description

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

Execution

• Requires scheduler: Required

Parameters

• No parameters.

Schema JSON

Show raw JSON

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

CLI Command

svc_call AgentManager GetSpeakingStatus

GetListeningStatus

Description

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

Execution

• Requires scheduler: Required

Parameters

• No parameters.

Schema JSON

Show raw JSON

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

CLI Command

svc_call AgentManager GetListeningStatus

ResetData

Description

Reset manager and agent data.

Execution

• Requires scheduler: Required

Parameters

• No parameters.

Schema JSON

Show raw JSON

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

CLI Command

svc_call AgentManager ResetData

Events

GeneralActionTriggered

Description

Emitted when a general action is triggered.

Execution

• Requires scheduler: Required

Items

• Action

  • Type: String

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

Schema JSON

Show raw 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 Command

svc_subscribe AgentManager GeneralActionTriggered

GeneralEventHappened

Description

Emitted when a general event occurs.

Execution

• Requires scheduler: Required

Items

• Event

  • Type: String

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

• IsUnexpected

  • Type: Boolean

  • Description: Whether the event was unexpected.

Schema JSON

Show raw 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 Command

svc_subscribe AgentManager GeneralEventHappened

SuspendStatusChanged

Description

Emitted when suspend status changes.

Execution

• Requires scheduler: Required

Items

• IsSuspended

  • Type: Boolean

  • Description: Whether the agent is suspended.

Schema JSON

Show raw JSON

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

CLI Command

svc_subscribe AgentManager SuspendStatusChanged

SpeakingStatusChanged

Description

Emitted when speaking status changes.

Execution

• Requires scheduler: Required

Items

• IsSpeaking

  • Type: Boolean

  • Description: Whether the agent is speaking.

Schema JSON

Show raw JSON

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

CLI Command

svc_subscribe AgentManager SpeakingStatusChanged

ListeningStatusChanged

Description

Emitted when listening status changes.

Execution

• Requires scheduler: Required

Items

• IsListening

  • Type: Boolean

  • Description: Whether the agent is listening.

Schema JSON

Show raw JSON

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

CLI Command

svc_subscribe AgentManager ListeningStatusChanged

AgentSpeakingTextGot

Description

Emitted when the agent speaks text.

Execution

• Requires scheduler: Required

Items

• Text

  • Type: String

  • Description: Spoken text.

Schema JSON

Show raw JSON

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

CLI Command

svc_subscribe AgentManager AgentSpeakingTextGot

UserSpeakingTextGot

Description

Emitted when the user speaks text.

Execution

• Requires scheduler: Required

Items

• Text

  • Type: String

  • Description: User text.

Schema JSON

Show raw JSON

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

CLI Command

svc_subscribe AgentManager UserSpeakingTextGot

EmoteGot

Description

Emitted when the agent shows an emote.

Execution

• Requires scheduler: Required

Items

• Emote

  • Type: String

  • Description: Emote name.

Schema JSON

Show raw JSON

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

CLI Command

svc_subscribe AgentManager EmoteGot

Related Types and Configs

For structs, enums, helper methods, and the full Doxygen-rendered API surface, see Raw helper API reference.

API Reference

Agent Base Class

Public header: #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.

Returns

const AgentAttributes& Agent attributes passed at construction time.

inline const AudioConfig &get_audio_config() const

Get the audio configuration used by the agent.

Returns

const AudioConfig& Current encoder and decoder configuration.

Agent Manager

Public header: #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.

Returns

Manager& Singleton instance.