DOCSEARCHbyAlgolia
Submit Docs

MushroomAgent Documentation

website·Indexed 30 days ago

https://docs.kiwilightyear.com/

Documentation for MushroomAgent, a distributed embodied agent designed to perceive, think, and act in the real world. It features a cognitive pipeline, support for multiple LLM providers like OpenAI and DeepSeek, and integration with communication channels such as Discord, Feishu, and HTTP. The platform allows developers to extend capabilities via tools and Skills, manage agent behavior through templates (IDENTITY, SOUL, HEARTBEAT), and configure the runtime via a CLI and config.yaml.

Tokens
21.3K
Snippets
115
Records
178
Agent score
49%

What's inside MushroomAgent

  1. Overview of MushroomAgent architecture

    MushroomAgent is a distributed agent runtime designed for developers building cross-platform systems like voice assistants, IoT controllers, and hardware-accelerated agents. It uses a distributed architecture to separate intelligence from physical sensing and action through two primary roles:

    • Agent: The decision-making core. It processes context (text, voice, video, device events), interacts with the LLM, decides the next action, and dispatches commands.
    • Node: The device I/O layer. Nodes collect local data (microphone audio, camera video, text) and forward it to the agent, then execute the resulting actions (voice output, UI manipulation, robot movement).

  2. Overview of MushroomAgent Discord channel capabilities

    The discord channel integrates with the Discord Gateway via WebSocket to receive messages and uses the REST API to send replies. It supports both server (guild) channels and direct messages (DMs). Key supported features include receiving messages, sending text replies, and handling slash commands.

  3. MushroomAgent Architecture Overview

    MushroomAgent is a distributed embodied agent designed to perceive, think, and act in the real world. Its architecture is built around four primary design goals: a unified subject, a unified world model, a unified action plane, and unified evolution as nodes grow.

  4. Understand the MushroomAgent system prompt assembly order

    Every LLM call in MushroomAgent uses a system prompt assembled by assemble_system_prompt_messages() in a fixed sequence. Earlier layers appear first in the context window. The prompt consists of 5 layers:

    1. Fixed Skeleton: Core structure and conditional sections (User, Persona, Skills, Knowledge, Summary, Response Format).
    2. Runtime Facts: Live turn data (IDs, timestamps, channel info, workspace path).
    3. Workspace Context: Contents of specific markdown files from the workspace root.
    4. Heartbeat Context: Protocol guidance for proactive engagement (heartbeat-triggered turns only).
    5. Ephemeral System Prompt: Per-turn instructions or sub-agent task scopes.

  5. Understand how the agent uses Skills to operate tools

    Skills provide the agent with operational procedures and guidance for specific domains, teaching it when and how to use tools. The agent follows a three-step process:

    1. Discover: The runtime recursively scans for SKILL.md files starting from configured skill roots (default is workspace.path/skills/, which resolves to ~/.mushroom_agent/skills/ in the local starter).
    2. Select: The agent enables a skill if the user request clearly matches the skill's purpose.
    3. Read: The agent uses the read tool to ingest the content of the matched SKILL.md file.

  6. Understand the mushroom_agent runtime architecture

    The mushroom_agent is the device-side runtime module. Its architecture is organized into four primary functional areas:

    • protocol: Manages environment events and action instruction models.
    • hardware: Provides hardware abstractions and adapters.
    • transport: Handles communication via LocalTransport and RemoteTransport.
    • runtime: Manages session organization, input forwarding, and the execution of actions.

  7. Use the Eval Panel for interactive agent verification

    The Eval Panel allows developers to run live evaluation cases against a locally running agent. It exercises the real LLM, tools, and prompt assembly. It is ideal for interactive verification after modifying system prompts or tools, or for verifying if a model still follows specific instructions.

    Note: Live runs consume real tokens from your configured LLM provider.

  8. Understand the Mushroom Agent workspace directory layout

    The agent workspace is the central location for configuration, context files, skills, logs, and memory. By default, the local workspace is located at ~/.mushroom_agent/. The workspace.path configuration setting serves as the anchor for this layout, from which the runtime derives the paths for skills/, memory/, and tool working directories.
    ~/.mushroom_agent/
├── config.yaml          # Main configuration file
├── prompts/             # Prompt files generated by init
│   ├── AGENTS.md        # Rules and constraints
│   ├── SOUL.md          # Persona and tone
│   ├── IDENTITY.md      # Self-identity
│   └── APPROACH_GREETING.md # Camera-approach greeting style
├── HEARTBEAT.md         # Workspace context: heartbeat checklist
├── skills/              # Local skills directory
├── memory/              # Agent memory storage
└── logs/                # Runtime logs

  9. Choose between WebSocket text chat and realtime voice endpoints

    Use WebSockets when your application requires a persistent bidirectional connection, low-latency text interaction, or realtime voice input and output. The available endpoints are:

    • Text chat: /ws/v1/chat
    • Realtime voice: /ws/v1/realtime

  10. Choose between Communication Transports and Platform Channels

    MushroomAgent provides two integration layers depending on how the agent is accessed:

    1. Communication Transports: Runtime entrypoints used when your own service, script, or browser UI calls MushroomAgent directly.
    2. Platform Channels: Adapters that integrate MushroomAgent into existing external chat or media platforms (e.g., Discord, Feishu), routing platform messages through the communication layer.

  11. Choose between local and remote agent deployment modes

    Depending on the desired architecture, use the following CLI patterns:

    • Single Process Local: Use start to run the agent, configured device runtime, and local UI together in one process.
    • API Service: Use serve --ui to start the service/API path and mount the web interface.
    • Distributed/Remote: Use serve on a host machine, then use node attach on one or more separate devices to connect them to that host.

  12. Manage schedules using the manage_schedule tool

    manage_schedule is a tool exposed via @function_tool used to handle reminders, recurring tasks, and timed background turns. It supports both text and voice interaction scenarios. The tool provides the following actions: create, list, get, status, update, run, runs, and remove.