SDK Overview

The Grounded SDK is the programmatic interface to the existing Grounded /api.

It is split into two packages because they solve different problems:

Package	Use it when you want to...
`@grounded/client`	automate Grounded resources and workflows
`@grounded/tracing`	send traces from your app directly into Grounded

Why Two Packages

@grounded/client is for control-plane automation.

Examples:

create an agent
configure or sync a connector
inspect sessions and insights
fork a snapshot
enqueue an optimize job
run an eval

@grounded/tracing is for runtime instrumentation.

Examples:

trace one request in your backend
capture LLM spans and retrieval spans
add scores and events
tag requests by environment or release
send batched traces to Grounded

Keeping them separate gives you a cleaner auth model and a cleaner programming model:

secret keys for control-plane access
publishable keys for trace ingestion

The Underlying API

The SDK does not introduce a new public namespace right now. It sits on top of the existing Grounded routes:

/api/agents
/api/connectors
/api/sessions
/api/insights
/api/snapshots
/api/jobs
/api/job-loops
/api/evals
/api/traces

The client SDK also normalizes the current inconsistencies across those routes. Some existing endpoints return raw arrays, some return { data: [...] }, and some return paginated objects. The SDK presents consistent return types on top of them.

Distribution Status

The implementation exists in the Grounded monorepo today:

sdk-client/ published as @grounded/client
sdk-tracing/ published as @grounded/tracing

Public npm publication is not live yet, so current development happens monorepo-first.

Typical Architecture

One common setup looks like this:

Your backend uses @grounded/client to configure agents, connectors, snapshots, jobs, and evals.
The same backend uses @grounded/tracing to send request-level traces to Grounded.
Grounded stores the raw traces and, when it can resolve an agent snapshot, converts them into sessions.
Those sessions become input for insights, evals, and optimization.

First Combined Example

import { Grounded } from '@grounded/client';
import { GroundedTracing } from '@grounded/tracing';
 
const grounded = new Grounded({
  apiKey: process.env.GROUNDED_SECRET_KEY!,
  baseUrl: 'http://localhost:3001',
});
 
const tracing = new GroundedTracing({
  publishableKey: process.env.GROUNDED_PUBLISHABLE_KEY!,
  baseUrl: 'http://localhost:3001',
  environment: 'staging',
  release: '2026-03-06',
});
 
const agent = await grounded.agents.create({
  name: 'support-agent',
});
 
const connector = await grounded.connectors.create({
  agentId: agent.id,
  name: 'LangSmith support',
  category: 'llm-tracing',
  config: { projectName: 'support-prod' },
});
 
await grounded.connectors.connect(connector.id);
 
const trace = tracing.startTrace({
  name: 'support.reply',
  sessionId: 'chat_123',
  userId: 'user_123',
  resource: { agentId: agent.id },
  input: { message: 'where is my refund?' },
});
 
const span = trace.startSpan({
  name: 'classifier',
  kind: 'app',
  input: { feature: 'intent-routing' },
});
 
span.end({
  status: 'ok',
  output: { intent: 'refund_status' },
});
 
await trace.end({
  status: 'ok',
  output: { text: 'your refund is processing' },
});
 
await tracing.flush();

Reference Sections

Quickstart Installation