Agent SDK

@downcity/agent currently exposes two main SDK entry points:

• Agent: a local embeddable agent runtime
• RemoteAgent: a remote agent client

The core of this SDK is the session. Whether you work locally or remotely, the real execution object is the session, not the Agent itself.

Two common usage paths

1. Pure SDK embedding

In this mode, the host owns the model instance directly:

• new Agent({ model })
• or await session.set({ model })

Good fit for:

• embedding directly inside a Node service
• local scripts or internal tools
• apps that already manage model instances themselves

2. Downcity / Downcity / City integration

In this mode, the Agent project does not directly own provider config, API keys, or model instances.

The model catalog and provider details live in City AIService, and the Agent project only binds:

{
  "execution": {
    "type": "api",
    "modelId": "quality"
  }
}

Good fit for:

• normal Downcity Agent projects
• multiple Agents sharing one model pool
• setups where provider keys, routing, and catalogs should stay centralized in City

When to use Agent

When your app and the agent run in the same process, or at least in the same local runtime environment, use:

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

You can explicitly pass:

• id
• path
• tools
• instruction
• model
• plugins

It behaves like a local embedded execution shell.

When to use RemoteAgent

When another process has already exposed an agent, use:

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

Then connect it through:

new RemoteAgent({ url: "http://127.0.0.1:15314" })

RemoteAgent currently supports:

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

It behaves like the paired remote client, not the model host.

Shared core object: Session

Whether you work locally or remotely, the SDK is really centered around sessions:

• create_session()
• getSession()
• list_sessions()
• getInfo()
• prompt()
• subscribe()
• history()
• system()
• fork()

The shared interactive model is:

• const turn = await session.prompt(...)
• session.subscribe(...)
• await turn.finished

Most SDK questions eventually become "how should I create, configure, and consume the session?"

One critical difference

Pure local SDK sessions

The local SDK session model can come from:

new Agent({ model })

or:

await session.set({ model })

Downcity Agent projects

The project runtime model comes from:

• downcity.json.execution.modelId
• the connected City AIService catalog

So in Downcity integration mode:

• the Agent project stores only the modelId
• Downcity resolves that modelId through City AIService
• provider config, API keys, and base URLs do not belong in the Agent project

Remote SDK sessions

Remote sessions do not currently support passing a local model instance from the client.

That is because the model instance should stay on the server side, not travel over the wire from the client.

Recommended reading order

1. Local Agent
2. Agent and City AIService
3. Sessions
4. Plugin Concepts
5. Remote Agent
6. SDK Surface
7. API reference

Related docs

• City AIService
• Add model
• Model config (City + Agent)