Docs/Integrations/Js Sdk

JS/TS SDK

The JS/TS SDK is a set of npm packages built on OpenTelemetry. Spans are exported to https://<your-ants-host>/api/public/otel/v1/traces and mapped to traces and observations.

PackagePurposeRuntime
@antsplatform/tracingstartActiveObservation, startObservation, observe, updateActiveTraceNode.js 20+
@antsplatform/otelAntsPlatformSpanProcessor, which exports spans to ANTS PlatformNode.js 20+
@antsplatform/openaiobserveOpenAI wrapper for the OpenAI SDKAny JS runtime
@antsplatform/langchainCallbackHandler for LangChain.jsAny JS runtime
@antsplatform/clientAntsPlatformClient for prompts, datasets, scores and the REST APIAny JS runtime
@antsplatform/guardrailsGuardrail checks and provider wrappersNode.js
ants-platformRe-exports all of the aboveNode.js 20+

The current version of every package is 1.0.16.

Set up tracing

Install

bash
npm install @antsplatform/tracing @antsplatform/otel @opentelemetry/sdk-node

Set credentials

Create a key pair under Project Settings > API Keys (see API Keys):

bash
export ANTS_PLATFORM_PUBLIC_KEY="pk-ap-..." export ANTS_PLATFORM_SECRET_KEY="sk-ap-..." export ANTS_PLATFORM_BASE_URL="https://<your-ants-host>"
⚠

The JS/TS SDK reads ANTS_PLATFORM_BASE_URL, not ANTS_PLATFORM_HOST (the Python SDK variable). If neither the variable nor baseUrl is set, it sends to https://api.agenticants.ai.

Register the span processor at startup

Create instrumentation.ts and import it before the rest of your app:

typescript
export const antsProcessor = new AntsPlatformSpanProcessor({ environment: "production", agent: { agentName: "support-agent", agentDisplayName: "Support Agent" }, }); const sdk = new NodeSDK({ spanProcessors: [antsProcessor] }); sdk.start();

The agent option tags every span with a stable agent ID so the agent appears in the AI Agent Center. Keep agentName stable. The display name can change later.

Trace an agent

typescript
startActiveObservation, startObservation, updateActiveTrace, } from "@antsplatform/tracing"; const answer = await startActiveObservation( "support-agent", async (agent) => { agent.update({ input: { question } }); updateActiveTrace({ userId: "user-123", sessionId: "session-abc", tags: ["support"], }); const search = startObservation( "kb-search", { input: { query: question } }, { asType: "retriever" }, ); const docs = await searchKnowledgeBase(question); search.update({ output: { documents: docs.length } }).end(); const gen = startObservation( "draft-answer", { model: "gpt-4o-mini", input: [{ role: "user", content: question }] }, { asType: "generation" }, ); const text = await callModel(question, docs); gen.update({ output: text, usageDetails: { input: 120, output: 80 } }).end(); agent.update({ output: { answer: text } }); return text; }, { asType: "agent" }, );

startActiveObservation makes the observation active, so observations created inside it nest under it. It ends the observation when the function returns or its promise settles. startObservation returns an observation that you end with .end().

Cost is calculated by ANTS Platform from the model and token usage. Pass costDetails to send your own cost instead.

Wrap a function with observe

typescript
const lookupOrder = observe( async (orderId: string) => orders.get(orderId), { name: "lookup-order", asType: "tool" }, );

Options: name, asType, captureInput, captureOutput, parentSpanContext and endOnExit.

Observation types and attributes

asType accepts span (default), generation, event, agent, tool, chain, retriever, evaluator, guardrail and embedding.

AttributesFields
All observationsinput, output, metadata, level, statusMessage, version, environment
Generations and embeddingsmodel, modelParameters, usageDetails, costDetails, completionStartTime, prompt
Trace (updateActiveTrace, observation.updateTrace)name, userId, sessionId, version, release, input, output, metadata, tags, public, environment

Flush in short-lived processes

Spans are batched. In scripts and serverless functions, flush before the process ends:

typescript
await antsProcessor.forceFlush();

Or set exportMode: "immediate" on the span processor to export each span as soon as it ends.

Span processor options

OptionEnvironment variableDefault
publicKeyANTS_PLATFORM_PUBLIC_KEYnone
secretKeyANTS_PLATFORM_SECRET_KEYnone
baseUrlANTS_PLATFORM_BASE_URLhttps://api.agenticants.ai
environmentANTS_PLATFORM_TRACING_ENVIRONMENTnone
releaseANTS_PLATFORM_RELEASEnone
flushAtANTS_PLATFORM_FLUSH_ATOpenTelemetry batch default
flushInterval (seconds)ANTS_PLATFORM_FLUSH_INTERVALOpenTelemetry batch default
timeout (seconds)ANTS_PLATFORM_TIMEOUT5
exportModenone"batched"; "immediate" for serverless
agentnone{ agentName, agentDisplayName }
masknoneFunction applied to data before export
shouldExportSpannoneFunction that filters spans
additionalHeadersnoneExtra HTTP headers

Framework integrations

OpenAI SDK
LangChain & LangGraph
AI Guardrails

Already using another OpenTelemetry instrumentation? Add AntsPlatformSpanProcessor to the same tracer provider, or export OTLP directly. See OpenTelemetry (OTLP).

API client

AntsPlatformClient from @antsplatform/client covers prompts, datasets, scores and read access to traces, observations and sessions. It reads the same environment variables (ANTS_PLATFORM_BASE_URL defaults to https://api.agenticants.ai; ANTS_PLATFORM_TIMEOUT defaults to 30 seconds).

typescript
const client = new AntsPlatformClient(); const prompt = await client.getPrompt("support-system-prompt"); const traces = await client.fetchTraces(); client.score.create({ traceId, name: "helpfulness", value: 0.9 }); await client.flush();

Members include prompt, dataset, score, media, api (the full REST client), getPrompt, createPrompt, getDataset, fetchTrace, fetchTraces, fetchObservations, fetchSessions, getTraceUrl, updateAgentDisplayName, flush and shutdown. AntsPlatformClient does not create traces. Use @antsplatform/tracing for that.

Troubleshooting

  • No traces. Check that instrumentation.ts runs before your app code, that the keys and ANTS_PLATFORM_BASE_URL are set, and that the process flushes before it exits.
  • 401 on export. Both keys must belong to the same project.
  • Agent missing from the AI Agent Center. Set the agent option on AntsPlatformSpanProcessor.
Python SDK
Java SDK
Sending Data In
npm package
© 2026 ANTS Platform, Inc.Docs v1.0 · Last updated June 2026