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

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.