Build an AI Embodiment Kit with CircuitPython Agents

Imagine walking into your home office and your AI assistant already knows it's too warm, notices the humidity is climbing, and gently pulses a vibration motor on your desk to get your attention before asking — via a tiny display with cheerful pixel faces — whether you'd like it to nudge the thermostat. That's not science fiction. That's the embodiment kit, and I've spent the last few weeks wiring one together, writing the agent skill files, and learning more than I expected about what it really means to give an LLM a body.

The embodiment kit concept is deceptively simple: a microcontroller loaded with CircuitPython, a handful of sensors, a few output devices, and a communication bridge that lets a large language model send commands and receive real-world data. But the deeper I've gone into building the agent skill and the accompanying guide, the more I've realised this project sits at a genuinely fascinating intersection of embedded hardware, open-source Python, and the rapidly evolving world of AI agents. Let me walk you through what I've built, why it matters, and how you can replicate or extend it yourself.

What Is the CircuitPython Embodiment Kit and Why Does It Matter?

At its core, the embodiment kit is a small device — think the size of a paperback book — that lives in your room and acts as the physical senses and voice of your LLM agent. The microcontroller running CircuitPython sits at the heart of it, connected to a temperature, humidity, and pressure sensor, a lux sensor for ambient light, a PDM microphone, a piezo buzzer, an accelerometer, a haptic vibration motor, a strip of NeoPixel LEDs, and a small display capable of showing text, prompts, and hand-crafted pixel faces.

What makes this genuinely powerful is the communication layer. The device listens on Adafruit IO, a cloud-based MQTT feed service. A companion Python script — the embodiment CLI — runs on whatever machine your LLM agent lives on. When the agent wants to do something, it constructs a JSON command object and publishes it to the Adafruit IO feed. The microcontroller picks that up, executes the command, and sends sensor readings or button press responses back through the same channel. The result is a feedback loop between the digital intelligence of your AI model and the physical reality of your room.

This matters because most AI agents today are entirely disembodied. They live in a chat window, a terminal, or a voice speaker. They have no idea if your room is stifling hot, whether the ambient noise just spiked, or whether you've been sitting completely still for three hours. The embodiment kit gives your agent genuine situational awareness — and that changes the kinds of tasks it can meaningfully help with.

Understanding the Agent Skill File: The Bridge Between AI and Hardware

One of the most interesting pieces of this project is the skill.md file — a markdown document that tells the LLM model exactly how to interact with the embodiment kit. If you've worked with tool-calling or function-calling in modern AI frameworks, think of the skill file as a richer, more narrative version of that. It explains the available commands, their parameters, expected responses, and even offers guidance on when and how to use each capability tastefully.

Writing a good skill file is genuinely harder than it sounds. The first draft I generated with Claude Opus after a full day of manually testing every capability came out impressively thoughtful — it even included notes reminding the model not to be annoying with the haptic buzzer. But it was also deeply hardcoded to my specific environment: absolute paths, references to my Claude installation directory, transport assumptions baked into the text.

The lesson here is that skill files need to be environment-agnostic. Instead of hardcoding a path like /home/tim/.claude/skills/embodiment_kit/scripts/embodiment_cli.py, the better approach is to reference a conceptual placeholder like <skills_directory>/embodiment_kit/scripts/embodiment_cli.py and let the agent resolve the actual path at runtime. Similarly, the transport mechanism — whether you're using Adafruit IO over MQTT or a local HTTP server — should be abstracted away so the skill doesn't break when you switch between them.

The other major refinement worth making is around Python dependencies. Rather than listing raw package names casually in the skill, you should include a proper requirements.txt approach, noting which packages need CircuitPython-specific variants (the adafruit-io, paho-mqtt, and connection_manager libraries all have specific install names that differ slightly from what you might expect, including some with dashes and some without).

Sensors, Outputs, and the Full Capability Map

Let me get specific about what this kit can actually do, because the range is broader than most people expect when they first hear "microcontroller project."

On the sensing side, you have:

• Temperature, humidity, and pressure — real-time environmental data, useful for everything from comfort monitoring to anomaly detection
• Lux (ambient light) — the agent can tell the difference between daytime, golden hour, and lights-off working conditions
• Sound level via PDM microphone — not speech recognition, but volume and noise presence, which is surprisingly informative
• Accelerometer (LIS3DH) — motion, tilt, tap detection; useful for detecting if the device has been moved or if the desk environment has changed

On the output side, you have:

• NeoPixel LED strip — full RGB colour control, perfect for ambient status indicators or attention signals
• Piezo buzzer — simple tones and alert sounds without needing a speaker driver
• Haptic vibration motor (DRV driver) — subtle physical nudges that don't require the user to be looking at a screen
• Display with pixel faces — the agent can show happy, sad, angry, confused, or sleepy expressions, as well as custom text messages and yes/no prompt dialogs
• Physical buttons — the user can respond to agent prompts directly on the device, with responses fed back to the LLM

That last point about buttons deserves emphasis. The display-plus-buttons combination means your agent can surface a decision to you — "Do you want to commit this code?" — and you can answer it without ever touching your keyboard or switching windows. For developers buried in deep work, that's a genuinely useful interaction model.

Parsing JSON Responses: JQ Versus Python One-Liners

When the embodiment CLI script runs and gets a response from the microcontroller, it returns a JSON object. Your agent needs to make sense of that. There are two solid approaches here, and the skill file should document both.

The first is JQ, a lightweight command-line JSON processor installable via apt. JQ lets you pipe the output of the CLI script directly into a query like .state.sensors.temperature and get a clean scalar value out. It's elegant and fast, but it's an extra dependency.

The second is a Python one-liner using json.loads from the standard library. Since the embodiment CLI is already a Python script, Python is guaranteed to be present on the host machine. A simple inline command can parse the JSON and extract any nested key using dot notation. This is more portable and requires nothing extra to install.

For robustness, the skill file should present both options. Different deployment environments will favour different approaches, and giving the agent both paths means it can fall back gracefully.

Extending the Kit: Smart Home Integration and Beyond

The embodiment kit as described is already genuinely useful, but the architecture is designed to scale. Because the agent can read real-world sensor data and the communication layer is abstracted, it's straightforward to extend it in several directions.

The most obvious extension is smart home integration. If your HVAC, lighting, or appliances are connected to a platform like Home Assistant, you can wire your LLM agent into that ecosystem. The agent could monitor the room temperature via the embodiment kit, compare it against your preferred comfort range, and issue commands to the smart home platform to adjust accordingly — all without you lifting a finger.

Another compelling direction is presence and context awareness. The combination of lux, sound, and accelerometer data gives the agent enough signal to make reasonable inferences about what's happening in the room. Is it dark and quiet? Maybe you're sleeping and shouldn't be interrupted. Is there a sudden spike in ambient sound? Perhaps now isn't the time for a haptic notification.

Finally, for those who want to keep everything fully local and off the network, there's a path using USB serial communication rather than cloud MQTT. The microcontroller would still run CircuitPython, but the communication channel would be a direct USB serial link to the host machine. Cloud-based LLMs obviously still need internet access on the host side, but the sensor and output communication stays entirely local — which matters for privacy-conscious setups.

Getting Started: What You Actually Need

If this project has sparked something in you — and I genuinely hope it has — here's the practical starting point.

First, pick a microcontroller. Adafruit makes excellent options, and the CircuitPython.org website lists over 650 supported devices. For a project like this with multiple sensors and outputs, you'll want something with generous IO pins — the Raspberry Pi Pico is a solid general-purpose starting point, though Adafruit's own Feather or Metro lines offer nice integration with their breakout boards.

Second, set up CircuitPython. Plug in your board, drop the CircuitPython UF2 firmware onto it, and you'll see it appear as a USB drive with a code.py file. Edit that file, save it, and your code runs immediately — no compile step, no flashing ritual, just Python.

Third, grab the sensors and output components. Adafruit sells all of these as breakout boards with excellent documentation: the BME280 for temperature/humidity/pressure, the VEML7700 for lux, a PDM microphone breakout, the LIS3DH accelerometer, the DRV2605 haptic motor driver, NeoPixel strips, and a small OLED or TFT display.

Fourth, set up an Adafruit IO account (free tier is sufficient to start), install the embodiment CLI script on your host machine, configure your LLM agent with the skill file, and start testing capabilities one at a time.

The journey from "blinking an LED" to "my AI agent just told me the room is too humid and suggested I open a window" is shorter than you'd think — and every step along the way teaches you something genuinely useful about both embedded systems and AI agent design.

Frequently Asked Questions

Do I need to know Python to build the embodiment kit?

A basic familiarity with Python helps enormously, but CircuitPython is specifically designed to be beginner-accessible. The syntax is standard Python, the documentation is excellent, and when you plug in your board and edit code.py, you get immediate feedback. If you can write a simple Python script, you can build this project. The agent skill file is markdown, not code, so that part requires no programming at all.

Can the embodiment kit work without an internet connection?

Partially. The current primary transport uses Adafruit IO, which requires internet connectivity on both the microcontroller and the host machine running your LLM. However, an HTTP server implementation is also possible, allowing local network communication. For a fully offline setup, USB serial communication between the host and the microcontroller is theoretically viable — though if you're using a cloud-based LLM, the host machine itself still needs internet access for that part of the system.

Which LLM models work best with the agent skill system?

The skill file approach is model-agnostic by design, but more capable models handle it better. Testing with a mid-tier model (like Claude Sonnet) is useful to verify that the skill is clear enough for a capable-but-not-top-tier model to execute correctly. Having Opus or a similarly advanced model write the initial skill draft after watching you work through all the capabilities is a clever bootstrapping technique — the model benefits from seeing the full interaction history.

How do I handle the Python library dependencies for the CLI script?

You'll want a Python virtual environment on your host machine with the following libraries installed: adafruit-io, requests, paho-mqtt, and adafruit-connection-manager. Note that some package names use dashes and some use underscores — check the exact names on PyPI or the Adafruit documentation before installing. The microcontroller side uses CircuitPython-specific library bundles, which you install by copying .mpy files onto the device's lib folder rather than using pip.

Can I add my own sensors or outputs to the kit?

Absolutely — and that's one of the most exciting aspects of the project. Because the skill file documents the command interface rather than hardcoding the hardware, you can extend the kit with additional sensors or outputs and then update the skill to expose those new capabilities to the agent. As long as your CircuitPython code on the microcontroller handles the new hardware and responds correctly to JSON commands, the agent side picks it up naturally through the updated skill documentation.