Deploy Resident Agents

Most agent deployments are visitors: a task arrives, an agent is created, it does the task, it is destroyed. The systems an enterprise actually depends on are not tasks. A payments service, a nightly batch, a data warehouse, an integration nobody wants to touch: each of them runs for years, drifts, fails at 03:00, and is understood by whoever happened to be on call the last time. What those systems need is not a visitor. It is a resident.

A resident agent in Lightspeed is a session that lives beside one system for as long as the system does: it watches the logs and metrics, runs the health checks and routine maintenance on the host, keeps the runbook and the architecture notes current as the system drifts, and escalates to a human with a written summary when something looks wrong. It runs for months, and while it waits it costs nothing.

Why residents were impossible

Under one-OS-per-agent a resident is a machine that is switched on all year to be useful for a few minutes a day. Ten residents are affordable; a thousand, one per service, are a data centre of idle VMs. That is the arithmetic that kept agents as visitors. In Lightspeed an idle agent is a suspended workflow: a row in an event store and a few kilobytes of history. A thousand residents waiting cost a database. The machine is borrowed only when a check actually runs.

Living beside the system

The resident’s environment is the host the system runs on, attached as an existing machine, or a dedicated machine provisioned once from a profile and kept. From there the agent has the file and process tools of an operator: it reads the deployed configuration, tails the log, inspects the process table, runs the maintenance script. Metrics and dashboards arrive over hosted MCP servers configured once for the universe, with the identity configured there and never carried by the session. Credentials for the host are injected into the environment; the model uses them and never sees them. Between checks the machine is paused or stopped by idle policy and wakes transparently on the next one.

Woken by events, not polling loops

A resident does not spin. It is woken by triggers: a schedule reconciled to the workflow engine’s own scheduler, a webhook from the monitoring system, a poller the resident wrote itself for a source with no API and runs as a job in its own environment with read-only credentials, a minimum interval and a circuit breaker. Every trigger is deduplicated and every resident carries a daily run budget. The activity feed records every wake and what came of it.

What it keeps

The resident’s memory is a virtual file system with no operating system attached: the runbook, the architecture notes, the list of things that were tried in March. It stays available whether or not a machine is currently borrowed, and the skills the resident accumulates about its system are cataloged from it automatically. A resident that has watched a system for a year knows the system better than the wiki does, and its notes are files a human can read and correct.

Escalation with a summary

When something looks wrong the resident does not page a human with a graph. It posts to the team’s channel with what it saw, what it checked, what it ruled out and what it proposes, and hands back. If the proposal needs approval, the approval has a deadline; if nobody answers, the run is cancelled cleanly and the resident goes back to watching. Channels are outside the agent loop, so a resident can gain an incident channel or lose a chat integration without the harness changing.

Owned by your process

A resident is a managed session: a workflow you already run declares its tools, its deadline and its budget at creation, and the agent cannot re-bind its own tools. The resident for the payments service belongs to the payments team’s workflow, escalates into their channel, and is bounded by their limits. Two hundred residents are two hundred managed sessions, each owned, each bounded, each visible in a list grouped by what owns it.

The first month

Deploy a resident beside one batch chain. Week one it reads: the scheduler, the scripts, the logs of the last ninety runs, and writes a runbook that did not exist. Week two it watches and reports what normal looks like. Week three the chain fails at 02:40; the resident has the log, the diff of the configuration against last week, and a proposal in the channel by 02:44. Week four the team adds the next chain.

Rests on: long-running sessions, dedicated environments, environment file and process tools, hosted MCP, virtual file system, channels, managed sessions, workflow-backed tools, idle power policy.