Agent Lifecycle

new Agent(options) creates and starts the Plugin lifecycle and ActionSchedule during construction. There is no agent.start() or agent.stop(); the host calls agent.dispose() to release resources.

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 } from "@downcity/agent";
import { Workspace } from "@downcity/workspace";
import { Shell } from "@downcity/workspace";
import { MacOsSeatbeltSandbox } from "@downcity/sandbox-macos";

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

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

await agent.dispose();

Sessions wait for Agent initialization before execution. dispose() stops plugin lifecycle, ActionSchedule, and Shell resources; the containing City owns and closes its HTTP/RPC transports.

Continue with the Agent SDK docs.

Agent Lifecycle

Agent Lifecycle

Table of Contents