SDK Overview
The Grounded SDK is the programmatic interface to the existing Grounded /api.
It is split into three packages because the product has three distinct runtimes:
| Package | Runtime | Use it when you want to... |
|---|---|---|
@grounded/client | server | automate Grounded resources and workflows |
@grounded/tracing | server | send direct llm and backend traces into Grounded |
@grounded/analytics | browser | send product telemetry and keep stable session context |
The Primitive Model
Grounded is easiest to understand through its primitives:
- traces and telemetry are the write primitives
- sessions are the derived read primitive
- snapshots are the versioned agent-config primitive
- jobs are the async execution primitive
That means:
- you do not manually author sessions through the public SDK
- you write raw runtime data and read sessions back later
- you iterate on snapshots and let jobs do the async work
Ingestion Modes
Grounded supports three ingestion modes:
- import
- historical or recurring sync through connectors
- LangSmith for llm traces
- FullStory for product/session telemetry
- direct
- first-party writes through
@grounded/tracingand@grounded/analytics
- first-party writes through
- mirror
- keep another provider but send a normalized copy into Grounded at the same time
Underlying Routes
The SDK sits on top of the current Grounded routes:
/api/agents/api/connectors/api/traces/api/telemetry/api/sessions/api/insights/api/snapshots/api/jobs/api/job-loops/api/evals
The client package normalizes route-shape differences so callers do not need to care whether a backend list route returns:
- a raw array
{ data: [...] }- a paginated object
Typical Architecture
- The browser uses
@grounded/analyticsand forwardsanalytics.getContext()to your backend. - The backend uses
@grounded/tracingand emits traces that share the same correlation keys. - Grounded merges telemetry and traces into derived sessions.
@grounded/clientreads sessions, traces, snapshots, and jobs, and triggers sync, analysis, optimization, and eval workflows.
Current Distribution
The packages live in the Grounded monorepo today:
sdk/clientsdk/tracingsdk/analytics
The npm publish path is prepared, but public package availability depends on the current release state of the @grounded scope.