XiaoZhi

[中文]

  • Component registry: espressif/brookesia_agent_xiaozhi

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

  • Helper class: esp_brookesia::agent::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/agent_helper/xiaozhi.hpp\"

  • Helper class: esp_brookesia::agent::helper::XiaoZhi

Service Interfaces

Functions

AddMCP_ToolsWithServiceFunction

Description

Add MCP tools from service functions. Return type: JSON array<string> of added tool names. Example: [“Service.Audio.SetVolume”,”Service.Audio.GetVolume”]

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: [“SetVolume”,”GetVolume”]

Schema JSON
Show raw JSON 

{
  "name": "AddMCP_ToolsWithServiceFunction",
  "description": "Add MCP tools from service functions. Return type: JSON array<string> of added tool names. Example: [\"Service.Audio.SetVolume\",\"Service.Audio.GetVolume\"]",
  "require_scheduler": false,
  "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: [\"SetVolume\",\"GetVolume\"]",
      "type": "Array",
      "required": false,
      "default_value": []
    }
  ]
}
CLI Command
svc_call AgentXiaoZhi AddMCP_ToolsWithServiceFunction {"ServiceName":null,"FunctionNames":null}

AddMCP_ToolsWithCustomFunction

Description

Add custom MCP tools. Return type: JSON array<string> of added tool names. Example: [“Custom.Display.GetBrightness”,”Custom.Display.SetBrightness”]

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

Schema JSON
Show raw JSON 

{
  "name": "AddMCP_ToolsWithCustomFunction",
  "description": "Add custom MCP tools. Return type: JSON array<string> of added tool names. Example: [\"Custom.Display.GetBrightness\",\"Custom.Display.SetBrightness\"]",
  "require_scheduler": false,
  "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
    }
  ]
}
CLI Command
svc_call AgentXiaoZhi 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.Audio.SetVolume”,”Custom.Display.GetBrightness”]

Schema JSON
Show raw JSON 

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

ExplainImage

Description

Explain an image. Return type: string. Example: “This image contains a cup on a desk.”

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.

Schema JSON
Show raw JSON 

{
  "name": "ExplainImage",
  "description": "Explain an image. Return type: string. Example: \"This image contains a cup on a desk.\"",
  "require_scheduler": true,
  "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?"
    }
  ]
}
CLI Command
svc_call AgentXiaoZhi 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 AgentXiaoZhi ActivationCodeReceived