XiaoZhi

[中文]

  • Component registry: espressif/brookesia_agent_xiaozhi

  • Helper header: #include "brookesia/service_helper/agent/xiaozhi.hpp"

  • Helper class: esp_brookesia::service::helper::XiaoZhi

Overview

brookesia_agent_xiaozhi integrates the XiaoZhi AI platform for ESP-Brookesia.

Features

  • Platform: Built on esp_xiaozhi SDK.

  • Voice: OPUS at 16 kHz, 24 kbps.

  • Events: Speaking/listening, agent/user text, emotes, etc.

  • Manual listen: Start/stop listening for Manual mode.

  • Barge-in: Interrupt agent speech.

  • Lifecycle: Unified management via brookesia_agent_manager.

Standard Include / Helper Class

  • Standard include: #include \"brookesia/service_helper/agent/xiaozhi.hpp\"

  • Helper class: esp_brookesia::service::helper::XiaoZhi

Service Interfaces

Functions

AddMCP_ToolsWithServiceFunction

Description

Add MCP tools from service functions.

Execution

  • Requires scheduler: Not required

Parameters

  • ServiceName

    • Type: String

    • Required: required

    • Description: Service name.

  • FunctionNames

    • Type: Array

    • Required: optional

    • Default: []

    • Description: Function names as JSON array<string>. Empty means all functions in the service. Example: ["SetAudioPlayerVolume","GetAudioPlayerVolume"]

Return Value

  • Type: Array

  • Description: Added tool names. Example: ["Service.Device.SetAudioPlayerVolume","Service.Device.GetAudioPlayerVolume"]

Schema JSON
Show raw JSON 

{
  "name": "AddMCP_ToolsWithServiceFunction",
  "description": "Add MCP tools from service functions.",
  "require_scheduler": false,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "ServiceName",
      "description": "Service name.",
      "type": "String",
      "required": true,
      "default_value": null
    },
    {
      "name": "FunctionNames",
      "description": "Function names as JSON array<string>. Empty means all functions in the service. Example: [\"SetAudioPlayerVolume\",\"GetAudioPlayerVolume\"]",
      "type": "Array",
      "required": false,
      "default_value": []
    }
  ],
  "return_value": {
    "type": "Array",
    "description": "Added tool names. Example: [\"Service.Device.SetAudioPlayerVolume\",\"Service.Device.GetAudioPlayerVolume\"]"
  }
}
CLI Command
svc_call XiaoZhi AddMCP_ToolsWithServiceFunction {"ServiceName":null,"FunctionNames":null}

AddMCP_ToolsWithCustomFunction

Description

Add custom MCP tools.

Execution

  • Requires scheduler: Not required

Parameters

  • Tools

    • Type: Array

    • Required: required

    • Description: Tools to add as JSON array<object>. Example: [{"description":"custom tool description 1","name":"Display.GetBrightness"},{"description":"custom tool description 2","name":"Display.SetBrightness"}]

Return Value

  • Type: Array

  • Description: Added tool names. Example: ["Custom.Display.GetBrightness","Custom.Display.SetBrightness"]

Schema JSON
Show raw JSON 

{
  "name": "AddMCP_ToolsWithCustomFunction",
  "description": "Add custom MCP tools.",
  "require_scheduler": false,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Tools",
      "description": "Tools to add as JSON array<object>. Example: [{\"description\":\"custom tool description 1\",\"name\":\"Display.GetBrightness\"},{\"description\":\"custom tool description 2\",\"name\":\"Display.SetBrightness\"}]",
      "type": "Array",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": {
    "type": "Array",
    "description": "Added tool names. Example: [\"Custom.Display.GetBrightness\",\"Custom.Display.SetBrightness\"]"
  }
}
CLI Command
svc_call XiaoZhi AddMCP_ToolsWithCustomFunction {"Tools":null}

RemoveMCP_Tools

Description

Remove MCP tools.

Execution

  • Requires scheduler: Not required

Parameters

  • Tools

    • Type: Array

    • Required: required

    • Description: Tool names to remove. Example: ["Service.Device.SetAudioPlayerVolume","Custom.Display.GetBrightness"]

Schema JSON
Show raw JSON 

{
  "name": "RemoveMCP_Tools",
  "description": "Remove MCP tools.",
  "require_scheduler": false,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Tools",
      "description": "Tool names to remove. Example: [\"Service.Device.SetAudioPlayerVolume\",\"Custom.Display.GetBrightness\"]",
      "type": "Array",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}
CLI Command
svc_call XiaoZhi RemoveMCP_Tools {"Tools":null}

ExplainImage

Description

Explain an image.

Execution

  • Requires scheduler: Required

Parameters

  • Image

    • Type: RawBuffer

    • Required: required

    • Description: Image data.

  • Question

    • Type: String

    • Required: optional

    • Default: "What is in the image?"

    • Description: Question text.

Return Value

  • Type: String

  • Description: Example: "This image contains a cup on a desk."

Schema JSON
Show raw JSON 

{
  "name": "ExplainImage",
  "description": "Explain an image.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Image",
      "description": "Image data.",
      "type": "RawBuffer",
      "required": true,
      "default_value": null
    },
    {
      "name": "Question",
      "description": "Question text.",
      "type": "String",
      "required": false,
      "default_value": "What is in the image?"
    }
  ],
  "return_value": {
    "type": "String",
    "description": "Example: \"This image contains a cup on a desk.\""
  }
}
CLI Command
svc_call XiaoZhi ExplainImage {"Image":null,"Question":null}

Events

ActivationCodeReceived

Description

Emitted when an activation code is received.

Execution

  • Requires scheduler: Required

Items

  • Code

    • Type: String

    • Description: Activation code.

Schema JSON
Show raw JSON 

{
  "name": "ActivationCodeReceived",
  "description": "Emitted when an activation code is received.",
  "require_scheduler": true,
  "items": [
    {
      "name": "Code",
      "description": "Activation code.",
      "type": "String"
    }
  ]
}
CLI Command
svc_subscribe XiaoZhi ActivationCodeReceived