SDK Surface

If you only want the practical developer-facing API shape, remember this:

• Agent is the local runtime entry
• RemoteAgent is the remote session client
• AgentSession is the local working object
• RemoteAgentSession is the remote working object

Recommended mental model

The SDK is session-first.

In most apps, the real object you work with is not Agent itself, but the session returned by:

• agent.session_collection().create_session()
• agent.session_collection().get_session(sessionId)
• remoteAgent.session_collection().create_session()
• remoteAgent.session_collection().get_session(sessionId)

Typical local flow

import { Agent } from "@downcity/agent";

const agent = new Agent({
  id: "demo",
  path: process.cwd(),
});

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

const turn = await session.prompt({
  query: "Summarize this repository",
});

await turn.finished;

You can also provide a default model directly in new Agent({ model }).

Typical remote flow

import { RemoteAgent } from "@downcity/agent";

const agent = new RemoteAgent({
  url: "http://127.0.0.1:5314/agents/repo-helper",
});

const session = await agent.session_collection().get_session("repo-analysis");
const turn = await session.prompt({
  query: "Continue",
});

await turn.finished;

Agent

Use Agent when the agent runtime lives in the same local process or host environment.

Core methods:

• new Agent(options)
• agent.ready()
• agent.dispose()
• agent.session_collection()
• agent.runPluginAction(input)
• agent.setInstruction(input)
• agent.getConfig()
• agent.getLogger()
• agent.plugins

Typical responsibilities:

• create and resume local sessions
• automatically start plugin lifecycles and ActionSchedule on construction; explicit ready() / dispose() only when needed
• expose plugin integration
• provide narrow advanced helpers for config and logging

If you need RPC or HTTP, use the AgentRPC / AgentHTTP classes from @downcity/server.

RemoteAgent

Use RemoteAgent when another process has already exposed an agent.

Core methods:

• new RemoteAgent({ url })
• agent.session_collection()

It currently supports:

• http://...
• https://...
• rpc://...

Typical responsibilities:

• connect to an existing remote Agent runtime
• switch to a known remote session
• browse available remote sessions
• respond to runtime plugin actions, such as shell approval requests

AgentSession

AgentSession is the main local execution object.

Core methods:

• session.id
• session.agentId
• session.config
• session.set(input)
• session.getInfo()
• session.prompt(input)
• session.subscribe(subscriber)
• session.history(input?)
• session.system()
• session.fork(input?)

Typical usage order:

1. await agent.session_collection().create_session()
2. await session.set({ model }) or provide a default model on Agent
3. const turn = await session.prompt({ query })
4. await turn.finished
5. optional: session.history() / session.getInfo() / session.fork()

RemoteAgentSession

RemoteAgentSession keeps nearly the same interaction shape as local sessions, but without local model injection.

Core methods:

• session.id
• session.getInfo()
• session.prompt(input)
• session.subscribe(subscriber)
• session.history(input?)
• session.system()
• session.fork(input?)

Important difference:

• local AgentSession supports set({ model })
• remote RemoteAgentSession does not accept a local model instance from the client

Agent projects and Federation AIService

If you are using this SDK inside a normal Downcity Agent project, there is one more distinction:

• pure SDK embedding: pass a local model
• Downcity project: bind through execution.modelId to Federation AIService

So session.set({ model }) is not the default path for every scenario.