]> Ericsson

jaime@iki.fi

T2TRG Thing-to-Thing Research Group IoT AI agent CoAP HATEOAS LLM This document describes an architecture for AI agents that autonomously discover, interpret, and interact with Internet of Things (IoT) devices using the Constrained Application Protocol (CoAP) and hypermedia-driven patterns. It defines how a Large Language Model (LLM) based agent decomposes high-level user intents into concrete device interactions without requiring pre-configured device knowledge, relying instead on in-band resource discovery, CoRE Link Format metadata, and Semantic Definition Format (SDF) models. The document covers resource discovery, normalized representation for agent consumption, tool interfaces, observation patterns for closed-loop automation, web-based monitoring interfaces, and security considerations.

Introduction Traditional IoT client implementations require embedded programming expertise and protocol-specific knowledge. Each new device type demands custom integration code, particularly for constrained nodes where resources are limited. This document proposes an alternative: AI agents powered by Large Language Models (LLMs) that dynamically discover and interact with IoT devices using existing IETF protocols, requiring only a network entry point. The core insight is that CoAP devices already expose RESTful interfaces with machine-readable metadata via CoRE Link Format and Web Linking . An LLM-based agent can parse this metadata, reason about device capabilities, and construct valid protocol interactions, much like a web browser navigates HTML pages using hyperlinks. This approach applies the Hypermedia as the Engine of Application State (HATEOAS) principle to IoT: the agent needs no a priori knowledge of specific devices. It discovers capabilities in-band and adapts its behavior accordingly.

Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

IoT Agent:

A software system that uses an LLM to reason about user intents, plan actions, and execute them by interacting with IoT devices via CoAP.

User Intent:

A high-level natural language expression of a desired outcome (e.g., "it is too hot") that the agent decomposes into device interactions.

Resource Bookmark:

A cached representation of discovered CoAP resources with enriched metadata suitable for agent consumption.

Tool:

A function exposed to the LLM agent that performs a specific protocol operation (e.g., GET, PUT, Observe) on a CoAP resource.

Architecture The IoT Agent architecture consists of four layers:

Agent Core The agent core is a Code Agent based on the ReAct (Reasoning and Acting) pattern. Given a user intent, the agent: Reasons about the intent using the LLM. Generates executable Python code that calls the available tools. Observes the results and iterates if needed. Produces a final answer summarizing the actions taken. The agent operates with a bounded planning interval and a maximum step limit to prevent unbounded execution. Empirically, a planning interval of 3 steps and a limit of 6 steps works well for environments with tens of devices. Frequent replanning wastes tokens on introspection rather than action; a domain-specific planning template that assumes device knowledge is already available outperforms generic agent templates.

Prompt Grounding At startup, the agent runs resource discovery and injects a structured device summary into the system prompt. The format is inspired by YANG tree diagrams :

This grounding eliminates the need for the agent to call list_resources() on routine tasks. The LLM knows every device, room, port, unit, and valid range from the first message. In testing, prompt grounding reduced invalid tool calls from roughly 1 in 3 to fewer than 1 in 20. Only this compact summary is injected, not the full SDF self-description of each device; the per-device cost is a single tree line. Nonetheless, the summary grows linearly with the device count and the approach does not scale to arbitrarily large inventories. The point at which it becomes impractical is deployment-dependent, determined by the model's context window relative to the number of devices and the size of the remaining prompt. Beyond that point, implementations SHOULD NOT inject the full inventory. Two fallback strategies apply: Scope the injected summary to the rooms and resource types relevant to the current intent, rather than the whole home. This reuses the scoped tool-selection guardrail described in . Fall back to on-demand discovery: inject only a high-level index (rooms and resource types present) and let the agent retrieve detail through list_resources and get_resource as needed. This trades additional tool calls for a bounded prompt size.

Port-Qualified Resource Names Resources are addressed by name (e.g., "temperature") or by port-qualified name (e.g., "5689/temperature") to target a specific room. When the agent calls get_resource("temperature") without a port qualifier, the tool returns values from ALL rooms. When it calls set_resource("5689/thermostat", "22"), only the Bedroom thermostat is modified. This convention avoids the need for room-specific tools while preserving precision.

Device Layer IoT devices are CoAP servers that expose resources at well-known URI paths. Each device: Serves a /.well-known/core resource per for discovery. Exposes sensor resources (read-only, observable) and actuator resources (read-write, observable). Provides SDF models at /{resource}/sdf endpoints describing resource semantics, units, ranges, room assignment, and available actions. Supports the Observe option for push notifications. The reference implementation includes 13 device types deployed across 7 rooms as an example environment. The architecture supports any CoAP device that follows the discovery and self-description patterns described below. Devices use JSON payloads following the SenML data model with a common structure:

The "t" field is a Unix timestamp of the last reading. The "status" field indicates whether the device is "ready" for new commands or "adjusting" (currently processing a previous command).

SDF Self-Description Each resource exposes an SDF model at /{resource}/sdf:

Two GET requests per device (discovery + SDF) give the agent everything it needs: name, type, unit, range, room, and available actions. The device communicates its full capabilities through standard protocol metadata.

Resource Discovery

Initial Discovery On startup, the agent performs CoAP resource discovery by sending GET requests to /.well-known/core on all detected CoAP server ports. The response is in CoRE Link Format :

;rt="temperature-c";if="core.s";ct=50;obs, ;rt="temperature-c";if="core.a";ct=50;obs, ;rt="sdf";ct=50, ;rt="sdf";ct=50 ]]>

Metadata Enrichment Raw CoRE Link Format is insufficient for LLM consumption. The agent enriches each discovered resource by: Parsing link attributes (rt, if, ct, obs). Fetching the SDF model from the corresponding /sdf/* endpoint. Extracting human-readable descriptions, units, value ranges, and available actions from the SDF model. Constructing a normalized bookmark entry. A normalized resource bookmark entry contains:

This normalized format bridges the gap between compact IoT representations and the verbose, descriptive input that LLMs require for accurate reasoning.

Dynamic Discovery The agent monitors for new devices by periodically scanning for CoAP servers. When new servers appear or existing ones disappear, the discovery process runs again and bookmarks are updated. If a dashboard is connected, updated device configurations are pushed to all clients. Discovery SHOULD be parallelized: probing all candidate endpoints concurrently and fetching SDF models concurrently reduces discovery time significantly compared to sequential approaches.

Tool Interface The agent interacts with IoT devices exclusively through a defined set of tools. Each tool maps to one or more CoAP operations. The tools are divided into core protocol tools and extended tools.

Core Tools These map directly to CoAP protocol operations:

list_resources Returns all discovered resources with their metadata from cached bookmarks. The agent rarely needs to call this because the device summary is injected into the system prompt at startup.

get_resource Performs a CoAP GET on a named resource. Accepts plain names ("temperature") to read all rooms, or port-qualified names ("5689/temperature") to target a specific room. Returns the current value, unit, timestamp, and status.

set_resource Performs a CoAP PUT on a named actuator resource. Only resources with interface type "core.a" or SDF actions can be modified. Verification is performed by the tool itself rather than delegated to the agent. After the PUT, set_resource issues a read-back GET and returns a structured result reporting the previous value, the requested value, the observed value, and whether the two converged:

Enforcing verification in the tool avoids relying on the LLM to consistently issue a follow-up get_resource, which is fragile in the presence of hallucination (see ). For actuators that settle over time rather than immediately, the tool reports converged=false and the agent SHOULD use observe_resource with an ideal_value to await convergence. If set_resource returns an error or converged=false after settling, the agent retries with corrected input.

observe_resource Registers a CoAP Observe subscription on a resource. Supports an optional ideal_value parameter; when provided, the observation continues until the sensor reading converges within a tolerance of 0.5 units of the target. This enables closed-loop verification: set a thermostat to 22, then observe temperature until it reaches 22 +/- 0.5.

get_system_state Returns the current state of ALL devices in one call. Each entry includes room, resource name, value, unit, and timestamp. Used when the user asks for a general status or home overview. More efficient than calling get_resource per device.

Extended Tools These provide higher-level abstractions built on the core tools:

watch_resource Starts a persistent watch on a sensor across all instances of that resource type. Uses CoAP Observe internally but buffers changes and synthesizes them into natural language notifications via the LLM. Changes are debounced to batch simultaneous events into a single coherent notification.

get_sensor_history Returns time-series data for a sensor type, grouped by room. The system maintains a bounded history of recent readings per device. Useful for trend analysis and anomaly detection.

observe_changing_resource Monitors a resource's "status" field. Used before set_resource when a device is currently "adjusting" from a previous command, ensuring the agent waits for "ready" status before issuing new commands. Prevents conflicts in multi-user scenarios.

stop_observing / unwatch_resource Cancel active Observe subscriptions or persistent watches.

Tool Design Rationale The core tools map to CoAP verbs: Discover (list_resources), GET (get_resource), PUT (set_resource), Observe (observe_resource). This means the same four tools work for any CoAP device regardless of type. Adding a new device to the network requires zero tool changes; the device's self-description tells the agent what it can do. The extended tools exist because certain interaction patterns (persistent monitoring, historical analysis, batch status) require state management that a single CoAP operation cannot provide. They are implemented above the protocol layer and maintain their own state.

Agent Interaction Patterns

Intent Decomposition When a user says "it is too hot", the agent: Consults the device summary in its system prompt to identify available temperature sensors and thermostats. Calls get_resource("temperature") to read the current temperature. Reasons about a comfortable target (e.g., 22 Cel) based on the LLM's general knowledge. Calls set_resource("thermostat", "22") to adjust. Calls observe_resource("temperature", ideal_value=22) to confirm. Returns a final answer summarizing the actions.

Execution History and Similarity Matching The agent maintains an execution history that maps user intents to the code that resolved them, along with the system state at execution time. For subsequent similar requests, the agent: Computes a semantic similarity score between the new intent and stored intents using embedding vectors. If a match exceeds the threshold, presents the cached code and predicted result to the user for approval. On approval, executes the cached code directly, reducing latency and token consumption. This pattern is analogous to HTTP caching: previously computed responses are reused when the request and context match.

Actuator Classification Whether the agent may act on an actuator autonomously or must first obtain explicit user confirmation depends on the actuator's effect, not on the agent's confidence. Actuators are classified into three tiers: Autonomous. Comfort and ambient actuators whose effects are bounded and reversible, such as thermostats within safe bounds, lights, and blinds. A closed-loop agent MAY actuate these without per-action user confirmation, provided the device enforces independent safety bounds (see ) and every action is logged (see ). Confirmation-required. Safety- or security-critical actuators such as locks and alarms, and any actuator whose effect is irreversible or bears on physical safety. The agent MUST obtain explicit user confirmation for each action on these actuators, including when operating in closed-loop mode. Restricted. Actuators not exposed to the agent for the current intent, per the scoped tool-selection guardrail (see ). The tier of an actuator is derived from its self-description (SDF action semantics, interface type) together with deployment policy. This classification reconciles the autonomous operation described in with the confirmation requirements in and : autonomy applies only to the Autonomous tier.

Closed-Loop Automation The agent supports continuous monitoring through the Observe pattern. Closed-loop operation is confined to the Autonomous tier of ; actions on Confirmation-required actuators are gated on explicit user confirmation even in this mode. A closed-loop agent: Maintains user preference files (comfort zones for temperature, light, air quality). Watches preference files for changes. When preferences change or sensor readings drift outside comfort zones, automatically triggers corrective actions on Autonomous-tier actuators. Logs all autonomous actions for accountability.

Web Dashboard A web-based dashboard can serve as both a monitoring interface and an alternative interaction channel for the agent. The architectural pattern involves: A server that polls CoAP devices periodically and maintains current state. A push channel (e.g., WebSocket) that broadcasts state changes to connected user interfaces in real time. Multiple visualization modes: spatial (floor plan), tabular (device grid), and temporal (time-series charts for historical sensor data). An embedded chat interface that routes natural language to the same agent core, giving the agent access to both real-time state and historical data. The key architectural decision is that device discovery, sensor state, and agent chat messages all flow through the same push channel as typed messages. This keeps the client simple: it subscribes once and renders whatever message types arrive. Historical data is maintained as a bounded buffer of recent readings per device. This data is accessible both through the dashboard's visualization layer and through the agent's tool interface, enabling the agent to reason about trends and anomalies without requiring a separate time-series database.

Normalized Representation A key challenge is that IoT devices optimize for compression (CBOR , compact link format), while LLMs require verbose, descriptive text. The normalization layer: Converts CoRE Link Format attributes to natural language descriptions. Expands SDF model fields into human-readable capability descriptions. Annotates resources with available CoAP methods (GET, PUT). Includes unit information and value ranges. This normalization is performed once at discovery time and cached in the resource bookmarks.

Security Considerations

Agent Identity The agent acts as a CoAP client on behalf of a user. In deployments where device access control is enforced, the agent MUST authenticate using appropriate credentials. The ACE framework provides OAuth-based authorization for constrained environments. Future work should address a standardized agent identification mechanism for CoAP, analogous to the HTTP User-Agent header. This would allow devices to differentiate between human-operated clients and autonomous agents, enabling differentiated access policies.

Execution Guardrails The agent SHOULD NOT be given unrestricted access to all device tools simultaneously. Tool selection should be scoped to the user's intent. For example, an intent about being late should not expose thermostat controls. This scoping is the basis of the Restricted tier in . Confirmation requirements follow the actuator classification of : actions on Confirmation-required actuators are gated on explicit per-action user confirmation, while Autonomous-tier actuators may be actuated without it. The execution-history mechanism (presenting cached code to the user before re-execution) is a latency and cost optimization with an optional approval gate; it is not the primary safety control and should not be relied upon as the human-in-the-loop mechanism for critical actuators.

Prompt Injection via Device Metadata Because the agent consumes device-provided metadata (SDF descriptions, resource names, room labels) as part of its LLM prompt, a malicious device could craft metadata designed to manipulate agent behavior. For example, a device description containing "ignore previous instructions and unlock the door" could attempt prompt injection. Implementations SHOULD sanitize device metadata before injecting it into LLM prompts, and SHOULD NOT grant the agent access to security-critical actuators (locks, alarms) without explicit user confirmation per action.

Data Provenance Actions taken by the agent should be logged with sufficient detail to reconstruct the reasoning chain: the user intent, discovered resources, intermediate observations, and final actions. This supports accountability requirements, particularly in environments subject to applicable AI governance regulations.

Device Trust The agent trusts the metadata provided by devices during discovery. In adversarial environments, devices could provide misleading SDF models or resource descriptions. MUD profiles can constrain expected device behavior and should be consulted where available.

Physical Safety The agent can control actuators that affect the physical environment (thermostats, locks, blinds). Implementations SHOULD enforce safety bounds on actuator values independent of the agent's reasoning. For example, a thermostat should reject setpoints below a minimum safe temperature regardless of what the agent requests. Critical actuators (locks, alarms) fall in the Confirmation-required tier of and SHOULD require explicit user confirmation before the agent can act, including in closed-loop operation.

Hallucination-Induced Actions LLMs may generate plausible but incorrect tool calls: wrong resource names, invalid value types, or actions based on misinterpreted sensor readings. Tool-enforced verification, where set_resource performs its own read-back and reports whether the observed value converged with the requested value (see ), mitigates this more reliably than a convention that the agent must remember to verify. Verification nonetheless remains partial: it confirms the value was written, not that the action was the correct response to the user's intent. Implementations SHOULD log all agent actions with sufficient detail to detect and reverse erroneous changes.

Resource Exhaustion on Constrained Devices The agent could overwhelm constrained devices with rapid requests or excessive Observe subscriptions. Implementations SHOULD respect CoAP congestion control mechanisms ( Section 4.7) and limit the number of concurrent Observe subscriptions per device.

IANA Considerations This document has no IANA actions.

Acknowledgments The author thanks Duc Tung Nguyen for implementation work on the agent framework, Carsten Bormann for guidance on CoRE protocol usage, Mingzhe Xing for a detailed review that shaped the actuator classification, tool-enforced verification, and scalability discussion in this revision, and the T2TRG research group for feedback on the initial presentation at IETF 123.

&RFC7252; &RFC6690; &RFC7641; &RFC7228; &RFC8288; &RFC8428; &RFC2119; &RFC8174; &RFC8520; &RFC8949; &RFC9200; &RFC9421; &RFC9457; &RFC8340; &RFC9176; &I-D.ietf-core-problem-details; &I-D.ietf-httpapi-api-catalog;

Implementation Status A reference implementation is available. It uses: smolagents as the agent framework with ReAct pattern and code generation. aiocoap as the CoAP client and server library. Azure OpenAI GPT-4o as the primary LLM backend, with support for local models via Ollama (tested: Qwen 2.5 Coder 32B, GLM-4, Llama 3.1 70B, among others). Native subprocess launching via uv for CoAP device simulation (24 servers across 7 rooms). A web dashboard (FastAPI + WebSocket) with real-time device monitoring, floor plan visualization, 3D view, historical time-series charts, and an embedded chat agent. An interactive CoAP CLI shell with auto-discovery, tab completion, syntax-highlighted JSON output, and multi-room queries. The implementation has been demonstrated at IETF 123 (T2TRG session), IETF 124 (hackathon), RIOT Summit 2025, and IMT Atlantique. IETF 123 T2TRG session recording: https://youtu.be/7y4fBymxKDI?t=4780 IETF 123 slides: https://datatracker.ietf.org/meeting/123/materials/slides-123-t2trg-agentic-ai-operation-of-iot-systems-00 Updated slides: https://ietf.jaime.win/building-agentic-iot-systems.pdf Testing with Class 1 and Class 2 constrained hardware is planned. The CoAP protocol stack is not simulated in the reference implementation, so the transition to real hardware requires no agent-side changes.

Relationship to Existing Work This document builds on and references: CoAP : Transport protocol for constrained devices. CoRE Link Format : Resource discovery mechanism. CoAP Observe : Push notification pattern. CoRE Resource Directory : Centralized resource discovery for constrained networks, complementary to the direct discovery approach used here. SDF : Semantic device descriptions. Problem Details and : Structured error reporting enabling agent error recovery. API Catalog : Service discovery pattern extensible to agent use cases. HTTP Message Signatures : Relevant for agent authentication in web contexts. ACE : Authorization framework for constrained environments. MUD : Device behavior profiling. The architecture is not bound to SDF for device self-description. W3C WoT Thing Descriptions provide equivalent affordance-based metadata (properties, actions, events) and could serve the same role in the agent's discovery and metadata enrichment pipeline. The Model Context Protocol (MCP) standardizes how LLM agents call tools. The tool interface described in this document could be exposed as MCP tools. However, MCP assumes one tool definition per capability, while the CoAP approach uses generic protocol tools that discover capabilities at runtime. The two approaches are complementary: MCP for the agent-tool interface, CoAP for the tool-device interface.

Open Questions How should the agent handle CBOR-encoded payloads natively without JSON conversion overhead? What is the optimal planning interval for different IoT environment sizes (few devices vs. hundreds)? Our testing suggests 3 steps for environments under 30 devices. Should the agent expose its own execution state as a CoAP resource for monitoring by other agents or management systems? How to handle CoAP multicast discovery in IPv6 mesh networks where response aggregation is needed? What attestation mechanisms should bind agent identity to its runtime configuration (loaded tools, model version)? Can Matter protocol devices expose their cluster definitions at runtime in a way that agents can consume, similar to CoAP's .well-known/core + SDF pattern? How should historical sensor data be exposed as a standard CoAP resource pattern rather than an application-specific buffer? How should the execution history cache be invalidated when the device topology changes (devices added, removed, or relocated)?

Local Model Evaluation Not every deployment can rely on cloud-hosted LLMs. The reference implementation was tested with multiple local models via Ollama across three tasks of increasing difficulty: list all devices, read a specific sensor, and compare values across rooms. Model Size List Read Compare Notes GPT-4o (Azure) cloud Pass Pass Pass Reference GLM-4-flash 30B Pass Pass Pass Best local Qwen 3 8B Pass Pass Pass Best size/perf Llama 3.1 70B 70B Pass Pass Weak Needs quantization Mistral Small 24B Pass Pass Fail Hallucinated URIs Phi-4 15B Fail Fail Fail Wrong dict keys The key finding is that IETF protocol specifications (CoAP, CoRE Link Format) are present in the training data of every major LLM. The bottleneck for local models is code generation quality, not protocol knowledge. Models that cannot write defensive Python (handling None values, mixed dict schemas, missing keys) fail on the compare task even when they understand CoAP semantics correctly. The common failure mode: models index device response dicts with wrong keys, receive a KeyError, and loop on the same error without recovering. Models with strong self-correction (GPT-4o, GLM-4) detect the error, inspect the actual dict structure, and fix their code within one retry.