Learning objective
Explore how an LLM can serve as the decision-making program in a software agent: it receives a percept, selects an action from a defined action set, and interacts with an environment through the agent's actuators.
Model: SmolLM2-360M-Instruct (ONNX) · Transformers.js 3.8.1 · preferred execution: WebGPU with 4-bit weights, with a single-threaded WASM fallback. Model files are downloaded from the official Hugging Face model repository on first use and cached by the browser. Inference runs on the device; no API key or inference server is used.
How this relates to the Russell & Norvig software-agent architecture
Conceptual mapping to the standard agent–environment interaction loop in Artificial Intelligence: A Modern Approach (AIMA). The LLM is used as the agent program's action-selection mechanism; the surrounding JavaScript provides the architecture and interface to the environment.
Vacuum-cleaner room
Sensor function
Actuator function
Important distinction: AIMA describes an agent as an entity that perceives its environment through sensors and acts upon it through actuators. Here, the model does not directly manipulate the room. The JavaScript agent program converts the percept into a prompt, obtains the LLM's proposed action, checks it against the action set and environment constraints, and only then passes it to the actuator function. The environment produces the next percept, closing the loop.
What is inside the agent program in this implementation?
- Percept builder: extracts the robot's current position, whether its current cell is dirty, and the four adjacent cells.
- Prompt builder: expresses the percept and the permitted action vocabulary in natural language.
- LLM decision function: runs SmolLM locally and generates a short response.
- Action parser: extracts one permitted action: UP, DOWN, LEFT, RIGHT, SUCK, or STOP.
- Actuator / action executor: rejects invalid moves and executes valid actions in the simulator.
This is a deliberately minimal, single-percept decision-maker. It does not maintain an explicit internal world model, persistent memory, a learned Q-table, or a separate utility function. The room itself retains its state; the model is only given the current local percept on each decision.
Vacuum-cleaner environment
6 × 4 grid · walls block movement · dirt is removed with SUCK. The robot receives a local percept of its current cell and its four neighbouring cells.
Current percept supplied to the LLM
Load the model and request a percept to see the sensor output.
Agent console
The agent receives a percept and proposes one action. You can inspect the generated response before the simulator executes it.
Decision trace
A proposed action is not executed automatically. This separation makes the decision and actuation stages visible and lets students inspect an invalid or unexpected model response.
Agent configuration
Lower values generally make generation more deterministic. The model can still produce invalid or unsuitable actions.
The task requires only a short action label. A small generation limit reduces unnecessary output.
Inspect the decision prompt
The prompt will appear here after requesting a decision.
What should students investigate?
- Does the LLM consistently choose SUCK when the current cell is dirty?
- Does it avoid moving into a wall?
- Does it use the local percept effectively, or does it make decisions that appear to require information it was not given?
- How does changing temperature affect action consistency?
- Compare the LLM's behaviour with the explicit BFS goal-based agent and the Q-learning agent from the earlier laboratories.
Suggested measurements: task completion, number of actions, invalid-action rate, model inference latency, and number of decisions required.
Technical notes and limitations
- Serve this page over HTTPS or from localhost. ES modules and WebGPU generally do not work reliably from a
file://URL. - Use a recent Chrome or Edge version with WebGPU enabled. If WebGPU initialisation fails, the page attempts a WASM/CPU fallback.
- The first model load downloads model weights (the q4f16 WebGPU ONNX file is approximately 272 MB; the WASM q4 variant is also quantized). Subsequent visits may use the browser cache.
- Model execution is local after download. The page does not send the room state or prompts to an inference API. \n
- A Transformers.js warning that response content-length cannot be determined is usually a download-progress warning, not by itself a model-loading failure. Before loading ONNX Runtime, this version checks that the model configuration and selected ONNX file are reachable.
- Small language models are not guaranteed to follow the action format. Invalid responses are displayed and are not executed.
- The action executor is deterministic JavaScript. It checks boundaries and walls independently of the LLM.
Implementation reference: Transformers.js WebGPU guide · Hugging Face SmolLM2-360M-Instruct model (ONNX files).