Agent Lifecycle

new Agent(options) starts plugin lifecycle and ActionSchedule during construction. There is no agent.start() or agent.stop().

Run only one active runtime for the same Agent ID in the same physical Workspace. ActionSchedule is a local scheduler and does not coordinate duplicate Agent processes.

import { Agent, Workspace } from "@downcity/agent";
import { Shell } from "@downcity/shell";
import { MacOsSeatbeltSandbox } from "@downcity/sandbox-macos";

const shell = new Shell({ sandbox: new MacOsSeatbeltSandbox() });
const agent = new Agent({
  id: "my-agent",
  workspace: new Workspace({ path: process.cwd(), shell }),
  model,
});

await agent.ready();

const session = await agent.sessions.create();
const turn = await session.prompt({ query: "Start" });
await turn.finished;

await agent.dispose();

Sessions wait for Agent readiness before their first execution, so ready() is an optional explicit barrier. It is useful before reading plugin state or exposing a transport. dispose() stops plugin lifecycle, ActionSchedule, and Shell resources; callers must separately close transports created by AgentHTTP or AgentRPC.

Continue with the Agent SDK docs.