Agent SDK
Understand the local Agent, remote Agent, and Session usage model exposed by @downcity/agent
Agent SDK
@downcity/agent exposes two main SDK entry points:
Agent: a local embeddable agent runtimeRemoteAgent: a remote HTTP client
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:
idpathtoolsservicesplugins
It behaves like a local embedded execution shell.
When to use RemoteAgent
When another process has already exposed an agent over HTTP, use:
import { RemoteAgent } from "@downcity/agent";Then call it through baseUrl.
It behaves like the paired remote client.
Shared core object: Session
Whether you work locally or remotely, the SDK is really centered around sessions:
session()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
Project runtime
The project runtime model comes from:
downcity.json.execution.modelId
Local SDK session
The local SDK session model comes from:
await session.set({ model });Remote SDK session
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.