---
title: User-created gadget agents
description: The proposed layer for persistent behavior built in natural language and hosted by the platform.
status: proposal
---

A gadget agent is a saved behavior bound to a person's gadgets. “When it gets shaken, play this sound” should become a trigger and a fixed action. “When I pick it up in the morning, read my first meeting” needs a bounded run with calendar access and speech.

This is Ring 1 in the [four-ring architecture](/docs/gadgets/overview/). The creation tools, saved definitions, event router and automation controls described here are **not implemented**. Ordinary Tasks and scheduled Tasks exist, but are not this feature.

Today, maker instructions can already ask the gadget's Conversation to look up a meeting and respond. This proposal adds a user-owned definition with explicit triggers, allowed tools, budgets and lifecycle controls. Those controls do not follow automatically from a maker's prompt.

## The saved definition

| Field | Purpose |
| --- | --- |
| Gadget bindings | Which owned devices the behavior may use. |
| Triggers and filters | Device events, schedules or explicit invocations; webhooks are a later extension. |
| Allowed commands and tools | The specific actions available to the run, subject to current grants. |
| Execution kind | `rules` for fixed actions or `llm` for judgement. |
| Instructions or actions | Natural-language behavior for a bounded agent, or validated deterministic actions. |
| State and budgets | Small owned state; limits on frequency, duration, tool calls and model use. |
| Revision and enabled state | Lifecycle controls that can fence already queued work. |

The SDK proposal starts with bounded JSON state and separate run records. A dedicated per-agent database is a later option. The JSON in the design record is illustrative; it is not a supported API payload.

## Build, test, keep

The agent discovers real gadget and platform capabilities, explains a plan and submits a definition through a proposed creation tool. The server validates ownership, command availability, arguments, permissions and budgets.

A dry run checks and describes actions without sending them to hardware. A requested live trial uses the same policy path. The user can then enable, disable or edit the behavior and inspect its runs from the gadget's automations view.

Once enabled, the saved trigger starts the work. The user does not need to keep the app open or repeat the instruction on every event.

## Route and execute

The proposed `POST /api/v1/gadgets/events` admits a structured, owned event. A router would match enabled definitions and queue runs. Today, events go to the originating gadget's continuing Conversation. Any future fallback to that path must preserve the matched run's limits; a failed or over-budget automation must not obtain a second unrestricted run.

Rules would run fixed actions through the shared dispatcher with no model call. LLM runs would use a bounded Agent API session on the worker with an explicit tool allowlist. Both would request device actions through Ring 0.

## Shared policy

The proposed platform must enforce grants at execution, deduplicate triggers, fence disabled or revised definitions and preserve state under overlapping runs. Automated movement requires the person's explicit grant and bounded execution. That per-agent grant is not implemented by today's gadget command tool.

The design does not add a shared-device arbitration service. The SDK's settled behavior is that a new sound replaces the current sound, the display keeps the latest write, and a second drive request fails while the base is busy. Firmware owns these outcomes and local stop behavior; each board must implement its advertised contract.

An offline device would fail the action and record the result. An uncertain side effect would not be replayed automatically. Proposed run logs must distinguish accepted commands, completed actions, skipped work and failures.

## Delivery stages

1. **Rules:** versioned contracts, owned storage, event admission, trigger matching, fixed actions, dry runs and user controls.
2. **LLM agents:** bounded worker sessions, granted tools and run inspection.
3. **Observation:** consent, retention and limits for camera streams, plus a worker that produces semantic events.
4. **Sharing:** reusable definitions with fresh per-user grants and no copied credentials or state.

The [complete design](/docs/source/gadgets-design.md) and [SDK proposal](https://github.com/impoai/impo-gadget-sdk/blob/main/docs/GADGET-AGENTS.md) preserve the decisions and remaining contract questions.
