Two API Paths: Lightweight Agents and the Runtime
AgentOS exposes two ways to run a model, and they do not share a runtime. The lightweight path is a set of functions over a provider call; the runtime path is a server-shaped process that owns a Generalized Mind Instance (GMI) per session. Between them, agent({ runtime: 'gmi' }) keeps the lightweight agent() surface and serves each session with a GMI built in process. Options are named the same on all of them, and the capability contract says what each of its four surfaces (agent, generation for generateText() and streamText(), runtime, and gmi for agent({ runtime: 'gmi' }) and gmi()) does with each one.
The lightweight path
generateText()andstreamText()resolve a provider from the model string and the environment keys (resolveProvider,createProviderManager), run the tool loop up tomaxSteps(one by default), and walk a policy-aware fallback chain when a provider fails (buildPolicyAwareFallbackChain).agent()adds a system prompt assembled from instructions, an optional soul file and the personality description, named sessions with their own history, tools, hooks and usage ledgers. Memory enters as hooks (memoryProvider.getContextbefore the call,observeafter it). Withoutruntime: 'gmi', no GMI is created on this path.agency()coordinates a roster of agents with one of seven strategies (see Agencies and orchestration strategies). Withruntime: 'gmi'its config seats are served by GMIs, andsessionSeat()seats a persistentgmi()agent as itself (Seats served by GMIs).
GMIs from agent()
agent({ runtime: 'gmi' }) returns gmi(opts), also exported as gmi() and createGmi(). It keeps the agent() options and the Agent surface, and serves each session with a GMI built in process from them, with no AgentOS runtime: a persona from the system prompt agent() sends and the personality traits, the agent's tools, a completion gateway built from its provider and fallback options, and, as its cognition profile sets them, cognitive memory, sentiment tracking and metaprompts. The session store holds the history; generate() and stream() run one turn on a GMI built for that call. rag, discovery, guardrails, security, permissions, hitl, emergent, output and provenance are accepted with a warning and not applied, and voice, avatar and channels throw at construction when set (a config that sets only enabled: false is not). With agencies.launch, a turn can launch a temporary team with the launch_agency tool (Teams a GMI launches), and on fires only for those teams: the agent's own turns fire none of its callbacks. GMIs from agent() describes the path. With learning on, the operator's learning calls are on agent.learning on this path and on AgentOS.getLearningLayer() on the runtime path, and the learning module is also on its own subpath, @framers/agentos/cognition/learning (Learning).
The runtime path
AgentOS.create() builds the runtime and processRequest() serves each session with a GMI: a persona, a mood, a reasoning trace, sentiment-triggered metaprompts, a memory bridge when cognitive memory is attached, and the runtime's guardrails, capability discovery, retrieval, emergent tools, tool permission checks, human-in-the-loop and channels. The runtime's GMIs call the provider of the turn's model directly, with no fallback chain; a host that builds a GMI itself can give it a completion gateway, which routes each model step and falls back across providers (Model calls through a completion gateway). Generalized Mind Instances describes the GMI; The turn lifecycle describes what a request goes through. Both GMI paths take a learning option, off by default: with it on, every GMI sends its persona's personality section as a system prompt of its own on every turn and binds each session to a learner (Learning). The full runtime adds no prompt profile or date tool unless the host names one. AgentOS.create preserves the environment's persistence setting when the host leaves that field out (ENABLE_PERSISTENCE unset, empty or exactly true is on; any other value is off); direct initialize defaults it to true. See What the full runtime adds to a request.
The capability contract
capabilityContract.ts records, per option, what each surface does with it:
| Option | agent | generation | runtime | gmi |
|---|---|---|---|---|
tools | enforced | enforced | enforced | enforced |
memory | partially enforced | runtime only | enforced | enforced |
rag | accepted but deferred | runtime only | enforced | accepted but deferred |
discovery | accepted but deferred | runtime only | enforced | accepted but deferred |
guardrails | accepted but deferred | partially enforced | enforced | accepted but deferred |
security | accepted but deferred | accepted but deferred | accepted but deferred | accepted but deferred |
permissions | accepted but deferred | accepted but deferred | accepted but deferred | accepted but deferred |
hitl | accepted but deferred | runtime only | enforced | accepted but deferred |
emergent | accepted but deferred | runtime only | enforced | accepted but deferred |
voice | partially enforced | runtime only | accepted but deferred | runtime only |
channels | accepted but deferred | runtime only | enforced | runtime only |
output | accepted but deferred | runtime only | enforced | accepted but deferred |
provenance | accepted but deferred | runtime only | enforced | accepted but deferred |
observability | partially enforced | partially enforced | enforced | partially enforced |
controls | partially enforced | runtime only | enforced | partially enforced |
agencies | accepted but deferred | runtime only | enforced | enforced |
No surface acts on security or permissions: AgentOS ties no policy to a security tier and applies none of the permission fields (types.ts, SecurityTier and PermissionsConfig), so the contract marks both deferred on every surface. agent(), gmi() and agency() accept them; the options of generateText() and streamText() and the runtime's AgentOSConfig do not declare them. To gate tools, use hitl.approvals.beforeTool on agency() or an onBeforeToolExecution hook; the full runtime's tool permission checks are set through its own toolPermissionManagerConfig.
agent() and gmi() each log one warning naming the options set that their surface accepts but defers, and gmi() throws at construction for voice and channels (and for avatar, which the contract does not list), unless the config sets only enabled: false. agent() without runtime: 'gmi' throws at construction when agencies.launch is set, since only a GMI runs launch_agency; when another agencies field is set, its warning says that it applies none of them. On the full runtime, AgentOSConfig.agencies with launch: true registers launch_agency, which requires the agency:launch capability, so only a persona granted it lists and calls it; without launch the runtime registers no such tool and checks the option's bounds at initialization. The default runtime reads a memory.working callback once per session send and prepends its text to the configured system text; other memory settings remain deferred and produce a warning. agent() applies voice only through a configured voice.session binding, which its voiceSession() method starts; other voice fields remain deferred and produce a warning, and the full runtime reads no voice field. agent() without runtime: 'gmi' and agency() warn when they receive a cognitiveMechanisms config, because they run no cognitive memory manager; with runtime: 'gmi' and memory on, the memory manager runs the mechanisms.
Choosing
Use the lightweight path for a call, a session with tools, or a roster of agents over one request. Use agent({ runtime: 'gmi' }) when an agent's sessions need a persona, mood, sentiment-triggered metaprompts or cognitive memory in process, without the runtime's guardrails, retrieval and channels. Use the runtime when the agent must sit behind guardrails and channels, retrieve from a corpus, forge tools, or serve personas loaded from definitions.