Session Overview

In the SDK, the thing that actually executes work is the session.

Preferred local interactive pattern

Local Agent

const session = await agent.session_collection().create_session();
await session.set({ model });

const turn = await session.prompt({ query: "Continue" });

const unsubscribe = session.subscribe((event) => {
  console.log(event);
});

await turn.finished;

If you already provided a default model through new Agent({ model }), you do not need a separate session.set({ model }).

RemoteAgent

const session = await remoteAgent.session_collection().create_session();
const turn = await session.prompt({ query: "Continue" });
await turn.finished;

Methods you will use most often

• set
• getInfo
• prompt
• stop
• subscribe
• history
• system
• fork

If you remember only one thing, remember this: the real working object in the SDK is not Agent itself, but the session.

session.stop() stops the current turn and cancels queued prompts that have not been merged into that turn yet.

One important difference

• local sessions must have a model available
• remote sessions cannot currently receive a model instance from the client

So the biggest difference between local and remote usage is not the interaction shape. It is where the model is held and configured.

One more boundary

If you are working inside a normal Downcity Agent project, the model usually comes from:

• downcity.json.execution.modelId
• the connected Federation AIService

In that case, session.set({ model }) should not be treated as the default path.