ImpoDocs
Browse documentation

DocumentationHardware

User-created gadget agents

The proposed layer for persistent behavior built in natural language and hosted by the platform.

On this pageThe saved definitionBuild, test, keepRoute and executeShared policyDelivery stages

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. 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#

FieldPurpose
Gadget bindingsWhich owned devices the behavior may use.
Triggers and filtersDevice events, schedules or explicit invocations; webhooks are a later extension.
Allowed commands and toolsThe specific actions available to the run, subject to current grants.
Execution kindrules for fixed actions or llm for judgement.
Instructions or actionsNatural-language behavior for a bounded agent, or validated deterministic actions.
State and budgetsSmall owned state; limits on frequency, duration, tool calls and model use.
Revision and enabled stateLifecycle 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 and SDK proposal preserve the decisions and remaining contract questions.