Skills vs Tools vs Extensions
Which capability system to reach for when. The decision is rarely ambiguous if you know what each one actually owns — this page is a verified-against-the-source map of the three.
Observability (OpenTelemetry)
AgentOS emits OpenTelemetry signals and leaves the SDK to the host. The host installs and starts the SDK and owns exporters, sampling and context propagation; AgentOS creates spans, records metrics, adds trace ids to logs and streamed chunks, and can emit log records, all through @opentelemetry/api, so whatever exporter the host wires (OTLP to Honeycomb, Tempo, Jaeger, Grafana Cloud) receives them. Every signal is off by default.
Logging (Pino + OpenTelemetry)
AgentOS uses structured JSON logs via pino and supports opt-in OpenTelemetry (OTEL) correlation and export.
Content-Safe Voice Diagnostics
Enable the host sink once before provider work, in every process that loads AgentOS. State belongs to the loaded package copy. Worker installation does not configure a different process or an independently loaded copy.
LLM Providers
AgentOS abstracts every LLM behind a single IProvider interface. Thirteen providers are wired in directly OpenRouter and Requesty route to models from many vendors, and LiteLLM is a proxy you host. Every provider speaks the same streaming protocol, supports the same tool-call shape (with the documented exceptions below), and reports each call's token usage in the same shape; Prices and Cost Reporting says which providers also report the call's cost. The fallback chain is auto-built from whichever keys are set in the environment and is overridable per agent.
API Key Rotation
AgentOS runs several API keys per provider from one key string. Set the provider's API key environment variable (or the apiKey you pass) to a comma-separated list and the provider instance builds a key pool from it: a strategy picks the key for each request, a key-scoped failure takes a key out of rotation and moves the request to the next usable key, a probe brings a failed key back only when it works again, and a host can persist the keys' standing across restarts.
CLI Error Codes
CLISubprocessError is the error a CLISubprocessBridge throws when the CLI it runs fails, and CLI_ERROR names nine codes for it. AgentOS ships two bridges, for the claude and gemini binaries behind the claude-code-cli and gemini-cli providers (CLI Providers). Those two bridges and their providers are the only AgentOS code that raises these errors: the CLI Registry reports a missing binary in its scan result and throws none of them. This page gives the class, each code, and when the built-in bridges and providers raise it.
Streaming Semantics
agency().stream(...) exposes multiple streaming surfaces because "what is
OAuth Auth
The @framers/agentos/auth subpath export provides OAuth primitives: a browser-based OAuth 2.0 authorization-code flow with PKCE for OpenAI (obtaining API access from a ChatGPT subscription, as the Codex CLI does), the same flow for Twitter, Instagram, LinkedIn and Facebook, and the token store, callback server and PKCE helpers they share. For a web server it provides the same grant split across two requests (RedirectOAuthFlow), secrets sealed at rest with AES-256-GCM (sealSecret, openSecret) and a token store that keeps each grant sealed (SealedTokenStore).