Local Agent Quickstart

Install

pnpm add @downcity/agent

Minimal example

import { Agent } from "@downcity/agent";
import { createOpenAI } from "@ai-sdk/openai";

const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
});

const agent = new Agent({
  id: "repo-helper",
  path: "/path/to/project",
  tools: {},
  model: openai.responses("gpt-5"),
});

const session = await agent.session();
const turn = await session.prompt({
  query: "Summarize the current repository structure",
});

const result = await turn.finished;
console.log(result.text);

The three most important steps

1. new Agent(...)
2. await agent.session()
3. make sure the session has a model

Step 3 is the easiest one to forget, and it is also the most common local SDK mistake.

You can satisfy step 3 in either way:

• pass model to new Agent({ model }) as the default for this agent
• or call await session.set({ model }) for one specific session

If you skip step 3 entirely, the local session has no model and cannot execute.

When you are using the SDK for the first time, avoid stacking complex tools, services, plugins, or HTTP exposure immediately. Get the shortest execution path working first.

When you need agent.start()

new Agent(...) only creates a local agent instance inside the current process.

If you only want to run sessions directly from host code:

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

you usually do not need agent.start().

Call agent.start(...) only when you need long-lived runtime capabilities:

• start an HTTP endpoint so another process can call the agent through RemoteAgent
• start a local RPC endpoint so the host or another local process can call it
• start service lifecycles so chat, schedule, or other background loops actually run

A simple mental model is:

• no start: use the Agent as a local library
• start: turn the Agent into a long-lived runtime that exposes endpoints and runs background capabilities

Continue reading

• Constructor options
• Local Agent HTTP and RPC
• Session set / prompt / subscribe