aicc-capsule — Reference Testbed

Reference implementation of the AICC Protocol in a 3D environment: an AI-controlled capsule in a room. This is the "hello world" of the protocol — a working end-to-end vertical that proves the spec is implementable and gives other projects a template to copy.

Goal

A 3D room with a capsule that an LLM agent controls through AICC sensor/actuator tools. The agent perceives the world via tools (vision, proprioception, hear), reasons, and acts (move, turn, look_at, interact). No pixel-clicking, no engine-specific hooks — pure protocol.

Status

Working. The testbed is built: headless 3D room with a capsule, a protocol-conformant bridge (9/9 conformance scenarios), and a demo in which an agent (LLM or scripted) navigates to the beacon and activates it. See testbed/README.md for run instructions; scripts/BUILDLOG.md for the build log.

Search challenge

The agent can also be sent on an autonomous search: an orange triangle is hidden on the back side of one of the crates, and the model must explore the room with real vision, spot it, and report it. This recording shows the run from three angles — the top-down map, the actual first-person frames the model saw, and its chat/reasoning (recorded with smooth motion, ~2 Hz):

Regenerate it with python -m testbed.record_search --provider polza --goal search --out search_mission.gif --capture-hz 2.0 --cruise 0.8 --steps 60.

Smooth & proactive movement

The same recording setup with a beacon mission and the cruise mode — the capsule glides with animated move/turn calls and keeps moving while the model thinks (--cruise). Frames are sampled at ~2.5 Hz by an observer client, so the GIF shows the actual motion, not step endpoints:

Regenerate with python -m testbed.record_search --provider polza --goal beacon --out smooth_mission.gif --capture-hz 2.5 --cruise 1.0.

Layout

aicc-capsule/
  AGENTS.md           # instructions for AI coding agents (opencode, claude, etc.)
  README.md           # this file
  docs/
    aicc-core.md      # AICC Protocol spec, v0.1 (copy from AICC-Protocol repo)
    aicc.schema.json  # JSON Schema for all AICC messages
    testbed-design.md # design notes for the testbed itself (see below)
  scripts/            # build/run/dev scripts
  testbed/            # the testbed source (empty until built)

Reading order for an agent

1. AGENTS.md — what to build, constraints, definition of done
2. docs/aicc-core.md — the protocol contract (sections 1–5 are essential)
3. docs/testbed-design.md — how the testbed maps onto the protocol
4. ~/Desktop/aicc-py — the SDK to build on (Bridge, AICCClient, transports)

Related repositories

• Spec: https://github.com/emil28092005/AICC-Protocol
• Python SDK: https://github.com/emil28092005/aicc-py (local checkout: ~/Desktop/aicc-py)