Agent Lifecycle

An Agent instance moves through a simple lifecycle: create, start, execute, stop.

1. Create

Instantiate the Agent with constructor options:

const agent = new Agent({
  id: "my-agent",
  model: myModel,
  tools: [myTool],
  plugins: [myPlugin],
});

At this stage, the Agent is configured but not running. No plugins are loaded, no sessions exist, and no HTTP server is listening.

2. Start

await agent.start();

During startup, the Agent will:

• validate the project directory (if path is provided)
• load PROFILE.md and SOUL.md (if found in the project directory)
• initialize all plugins (call their init hooks)
• start the HTTP server (if configured in start)

After start(), the Agent is ready to accept messages and tasks.

3. Execute

Once running, the Agent can be entered through multiple surfaces:

• HTTP requests (if the HTTP server is enabled)
• Direct SDK calls (agent.session(...))
• Plugin-driven events (chat messages, scheduled tasks)

All paths converge on the same session and executor core.

4. Stop

await agent.stop();

During shutdown, the Agent will:

• stop accepting new requests
• gracefully close all active sessions
• call destroy hooks on all plugins
• stop the HTTP server (if running)
• persist any pending state

Recovery

If the process exits unexpectedly, the next start() will:

• restore persisted sessions from .downcity/
• reinitialize plugins
• resume any scheduled tasks

Continue with:

• Agent SDK
• Agent SDK Reference