@coreweave/forge-sdk

CoreWeave Forge TypeScript SDK

TypeScript AgentLens tracing

The TypeScript SDK sends agent, LLM, tool, and sub-agent spans to the Weave Agents experience over OTLP/HTTP. It supports Node.js 18 and newer.

Install the package from npm:

npm install @coreweave/forge-sdk@beta

import {tracing} from '@coreweave/forge-sdk/agentlens';

await tracing.init('entity/project'); // Reads WANDB_API_KEY.

await tracing.runIsolated(async () => {
  const conversation = tracing.startConversation({agentName: 'research-agent'});
  try {
    const turn = conversation.startTurn({userMessage: 'Find the answer'});
    const llm = turn.startLLM({model: 'gpt-5'});
    llm.output('The answer is 42.');
    llm.end();
    turn.end();
  } finally {
    conversation.end();
  }
});

await tracing.shutdown();

Tracing is also available as agentlens.tracing from the root package or through the direct @coreweave/forge-sdk/agentlens/tracing subpath.

Wrap each request or agent run in its own tracing.runIsolated callback. It preserves that run's tracing state across await and prevents concurrent requests from sharing conversations. Starting tracing work outside this scope throws an error; there is no process-global fallback. Initialize the exporter once outside these request scopes.

End spans explicitly when their work finishes. Ending a turn or conversation also closes its remaining owned descendants, including tools and sub-agents, so use finally for failure cleanup. Ended parents cannot start new children.

projectName must include the entity because this package does not call W&B account APIs to discover one. tracing.init accepts explicit apiKey and baseUrl options. Otherwise it reads WANDB_API_KEY, WF_TRACE_SERVER_URL, and WANDB_BASE_URL.

Call tracing.forceFlush() before a latency-sensitive process exit. tracing.shutdown() flushes and closes the private OpenTelemetry provider. The SDK does not replace the application's global provider or export spans created by unrelated instrumentation.

Anthropic integration

Preload the Forge instrumentation entry point to patch supported provider SDKs as they are imported or required. Anthropic messages.create() and messages.stream() calls then emit AgentLens chat spans, including streaming output, tool calls, request settings, token usage, prompt-cache usage, and integration provenance.

node --import=@coreweave/forge-sdk/instrument app.mjs

import Anthropic from '@anthropic-ai/sdk';
import {agentlens} from '@coreweave/forge-sdk';

await agentlens.tracing.init('entity/project');
const anthropic = new Anthropic(); // Automatically instrumented by the preload.
await anthropic.messages.create({
  model: 'claude-sonnet-4-5',
  max_tokens: 256,
  messages: [{role: 'user', content: 'Hello'}],
});

For hosts that cannot use a Node preload, wrap a client explicitly:

const anthropic = agentlens.integrations.wrapAnthropic(new Anthropic());

Provider calls made during an active AgentLens turn become children of that turn. A standalone provider call gets its own isolated synthetic turn so it is still visible in AgentLens. The integration supports @anthropic-ai/sdk 0.52.0 and newer and also traces the Messages Batches API as tool operations.

OpenAI integration

The same preload automatically instruments OpenAI Chat Completions, structured output parsing, Responses, and image generation. Both Chat Completions and Responses streams retain their native SDK interfaces while AgentLens collects the completed output and token usage.

import OpenAI from 'openai';
import {agentlens} from '@coreweave/forge-sdk';

await agentlens.tracing.init('entity/project');
const openai = new OpenAI(); // Automatically instrumented by the preload.
await openai.responses.create({
  model: 'gpt-5',
  input: 'Hello',
});

Explicit wrapping is also available:

const openai = agentlens.integrations.wrapOpenAI(new OpenAI());

The integration supports OpenAI SDK 4.0.0 and newer. It records multimodal messages, function/tool calls, request settings, cached and reasoning tokens, and OpenAI Responses prompt-cache writes.

Google Gen AI integration

The preload also instruments @google/genai clients. Gemini models.generateContent(), models.generateContentStream(), chat helpers, and Imagen generation emit AgentLens spans with multimodal messages, function calls, system instructions, request settings, response metadata, cached input, and thinking-token usage.

import {GoogleGenAI} from '@google/genai';
import {agentlens} from '@coreweave/forge-sdk';

await agentlens.tracing.init('entity/project');
const google = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
await google.models.generateContent({
  model: 'gemini-flash-latest',
  contents: 'Hello',
});

For hosts that cannot use the preload, wrap a client explicitly:

const google = agentlens.integrations.wrapGoogleGenAI(
  new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY})
);

The integration supports @google/genai 0.2.0 and newer. Calls made through a Vertex AI client are attributed to vertex_ai; Developer API calls are attributed to gemini.

SDK attribution

Every exported span's OTLP resource includes wandb.sdk.name = "forge" to identify Forge SDK traffic separately from regular Weave SDK traffic. wandb.sdk.version records the package version, and wandb.sdk.language is "node". These attributes are independent of the configurable service.name.

Smoke test

The smoke script emits one synthetic agent turn and LLM span. It does not call an LLM provider.

WANDB_API_KEY=<key> \
FORGE_TRACE_PROJECT=<entity/project> \
npm run smoke:tracing

The command exits only after the exporter flushes and prints the conversation ID to find in the Weave Agents experience.

Media

LLM.attachMedia emits standard GenAI media parts:

• Base64 content becomes a blob part.
• URLs become uri parts.
• Provider-side file identifiers become file parts.

llm.attachMedia({
  uri: 'https://example.test/image.png',
  modality: 'image',
});

Media is serialized into gen_ai.input.messages. The tracing package does not upload media to the Weave object store. Prefer URIs for large media because inline blobs count toward the OTLP request-size limit.

Development

Run these commands from typescript/ after npm ci.

Run npm test, npm run typecheck, and npm run format:check before publishing. npm pack and npm publish build dist through prepack; the test suite checks the packed entry points from a clean source tree.

License

Copyright 2026 CoreWeave, Inc.

Licensed under the Apache License, Version 2.0.