Build a device application

@agentium/edge connects core Agents to device tools and provides resource monitoring, device presets, Ollama helpers, and a cloud-sync client. Start with a measured system reading, then add only the hardware and model capabilities your device needs. Your application owns the work loop and its response to unhealthy resources. The edge runtime reports degradation and watchdog timeouts; it does not automatically throttle, restart an Agent, or remove tools.

Why edge?

Local inference: use Ollama when requests and model processing should stay on the device.
Device tools: read system information or connect GPIO, I2C, cameras, BLE, and servos.
Observable operation: report resource usage and host-controlled health decisions.
Optional synchronization: queue bounded event batches and fetch configuration from your own cloud endpoints.

Quick start

This first program reads system resources and prints the available system-tool names. It does not call a model or write to hardware. Linux-specific readings may be unavailable on other platforms.

mkdir agentium-device
cd agentium-device
npm init -y
npm pkg set type=module
npm install @agentium/core@4.0.0 @agentium/edge@4.0.0
npm install --save-dev typescript tsx @types/node

Save as inspect.ts:

import { ResourceMonitor, SystemToolkit } from "@agentium/edge";

const snapshot = new ResourceMonitor().snapshot();
console.log("Memory usage (%):", snapshot.memory.usage_percent);
console.log("CPU temperature (C):", snapshot.cpu.temperature_c);
console.log("Available tools:", new SystemToolkit().getTools().map((tool) => tool.name));

npx tsx inspect.ts

Expect a measured memory percentage, a temperature or null, and system_info, system_process_list, and system_network_info. No monitoring timer is started. The monitor uses OS readings and probes nvidia-smi when available; a missing GPU does not prevent system inspection.

Choose a toolkit

Task	Guide	Additional runtime requirement
Read system, process, and network information	SystemToolkit	Node/OS APIs; some readings are Linux-only
Read or write digital pins	GpioToolkit	`node-libgpiod`, GPIO device permissions
Read I2C sensors	SensorToolkit	`i2c-bus`, enabled I2C bus and supported sensor
Capture images or video	CameraToolkit	Camera hardware and supported `libcamera` commands
Discover/connect to Bluetooth devices	BleToolkit	`@stoprocent/noble`, BLE adapter permissions
Set or sweep hobby servo angles	ServoToolkit	`node-libgpiod`, GPIO and correctly configured actuator

Read-only system inspection is a useful first step before connecting actuators. Choose allowed pins, device access, tool approvals, and application limits for the specific hardware operation.

Connect a local model

Install and start Ollama separately, then download the model you intend to use. The package’s Ollama helpers can check availability or request a model download; they do not bundle Ollama or model weights. Preset recommendations are starting points, so measure latency and memory on your target workload. Install the core adapter’s optional dependency:

npm install ollama@0.6

With Ollama already serving a downloaded model, save this as assistant.ts:

import { Agent, ollama } from "@agentium/core";
import { checkOllama, edgePreset, SystemToolkit } from "@agentium/edge";

const preset = edgePreset("pi5-8gb");
const model = process.env.OLLAMA_MODEL ?? preset.recommendedModel;
const status = await checkOllama();
if (!status.running) throw new Error("Start Ollama before running the assistant");
if (!status.models?.includes(model)) throw new Error(`Download ${model} with Ollama first`);

const agent = new Agent({
  name: "device-assistant",
  model: ollama(model),
  maxTokens: preset.maxTokens,
  instructions: "Use measured system information. Say when a reading is unavailable.",
  tools: new SystemToolkit().getTools(),
});
try {
  const result = await agent.run("Report memory usage and CPU temperature from system_info.");
  if (result.status !== "completed") throw new Error(`Run ended with ${result.status}`);
  console.log(result.text);
} finally {
  await agent.close();
}

npx tsx assistant.ts

The answer should reflect the tool’s measurements; exact wording depends on the model. Use a model with tool-call support and inspect run events if it answers without measuring. This calls the local Ollama service. It does not install, start, or stop that service.

Supported devices

These are the built-in preset recommendations, not validated capacity guarantees:

Device	RAM	Preset model	Preset ID
Pi 4	2 GB	`tinyllama:1.1b`	`pi4-2gb`
Pi 4	4 GB	`tinyllama:1.1b`	`pi4-4gb`
Pi 4	8 GB	`llama3.2:1b`	`pi4-8gb`
Pi 5	4 GB	`llama3.2:1b`	`pi5-4gb`
Pi 5	8 GB	`phi3:mini`	`pi5-8gb`

A preset does not configure every Agent or enforce process limits by itself. The example explicitly applies maxTokens; implement other limits in the host and model configuration where supported.

Package structure

Component	Role	Next task
Six toolkits	Expose selected OS and hardware operations as tools	Connect one device and verify a reading/action
`EdgeRuntime`	Resource monitoring, health endpoint, watchdog/degradation signals	Define host responses
Presets and Ollama helpers	Starting configuration and local model checks	Choose local inference
`EdgeCloudSync`	Fetch blueprints, heartbeat, queue event batches	Implement the host protocol
`registerEdgeToolkits()`	Add edge toolkit types to the core toolkit catalog	Discover configuration fields in your operator API

Hardware dependencies

Install native npm dependencies only for the selected toolkit:

npm install node-libgpiod
npm install i2c-bus
npm install @stoprocent/noble

These are alternatives for GPIO/servo, I2C, and BLE respectively; the first system-inspection example needs none of them. CameraToolkit has no native npm dependency but still requires the external camera commands and working hardware. Review each toolkit’s OS requirements before deployment.

Extend the application

After one measured task works, add the runtime and demonstrate how your host stops admitting work or asks its process supervisor to restart. Add cloud sync only when the receiving endpoints and configuration-application policy exist. Use evaluation for representative answers and Ship for process supervision, ownership, and release checks.

Find an integration

Voice and call adapters

Sandbox and telemetry

Providers and services

Protocols and devices

Build a device application

Why edge?

Quick start

Choose a toolkit

Connect a local model

Supported devices

Package structure

Hardware dependencies

Extend the application

​Why edge?

​Quick start

​Choose a toolkit

​Connect a local model

​Supported devices

​Package structure

​Hardware dependencies

​Extend the application

Why edge?

Quick start

Choose a toolkit

Connect a local model

Supported devices

Package structure

Hardware dependencies

Extend the application