@raindrop-ai/ai-sdk 0.0.31 → 0.0.33

package/README.md

@@ -115,9 +115,50 @@ raindrop.traces.endSpan(agentTurn);
 await raindrop.flush();
 ```
 
-### AI SDK v7+ native telemetry (opt-in)
+### AI SDK v7 quick start: `registerTelemetry(raindrop())`
 
-On AI SDK v7+, you can use the native `Telemetry` callback interface (formerly `TelemetryIntegration` before beta.111) instead of Proxy wrapping. This avoids Proxy overhead and works with all AI SDK entry points (including `ToolLoopAgent`).
+On AI SDK v7, the simplest setup is the `raindrop()` factory, which returns a
+ready-to-register telemetry integration. The `writeKey` defaults to the
+`RAINDROP_WRITE_KEY` environment variable.
+
+```ts
+import { generateText, registerTelemetry } from "ai";
+import { OpenTelemetry } from "@ai-sdk/otel";
+import { raindrop } from "@raindrop-ai/ai-sdk";
+
+registerTelemetry(new OpenTelemetry(), raindrop());
+
+const result = await generateText({
+  model: anthropic("claude-sonnet-4-5"),
+  prompt: "what is the weather in Tokyo?",
+  telemetry: { functionId: "weather-agent" }, // no `isEnabled` needed in v7
+});
+```
+
+`raindrop()` is self-contained — `@ai-sdk/otel` is optional; you can register
+Raindrop on its own with `registerTelemetry(raindrop())`. Pass `context` and
+`subagentWrapping` to customise behaviour, e.g. `raindrop({ context: { userId: "user_123" } })`.
+
+For short-lived scripts that exit before the background flush timer fires, keep
+the reference and drain it before exiting:
+
+```ts
+const rd = raindrop();
+registerTelemetry(rd);
+// ... run your generations ...
+await rd.flush(); // or rd.shutdown()
+```
+
+Sub-agents (a `generateText`/`streamText` invoked from inside a tool's
+`execute`) nest automatically: the inner generation's spans are parented under
+the tool span so parent and child spans stay correctly nested.
+
+### AI SDK v7+ native telemetry (advanced)
+
+For finer control you can build the integration from a `createRaindropAISDK`
+client instead. The native `Telemetry` callback interface (formerly
+`TelemetryIntegration` before beta.111) avoids Proxy overhead and works with all
+AI SDK entry points (including `ToolLoopAgent`).
 
 ```ts
 // Option A: wrap() with nativeTelemetry flag
@@ -136,6 +177,43 @@ registerTelemetry(
 );
 ```
 
+### Standalone self-diagnostics tool
+
+When registering the native telemetry integration directly, create the
+self-diagnostics tool from the same Raindrop client:
+
+```ts
+import { createRaindropAISDK } from "@raindrop-ai/ai-sdk";
+import { generateText, registerTelemetry } from "ai";
+
+const raindrop = createRaindropAISDK({
+  writeKey: process.env.RAINDROP_WRITE_KEY!,
+});
+
+registerTelemetry(raindrop.createTelemetryIntegration({ userId: "user_123" }));
+
+const diagnostics = raindrop.createSelfDiagnosticsTool();
+
+await generateText({
+  model,
+  prompt,
+  tools: {
+    [diagnostics.name]: diagnostics,
+  },
+  experimental_telemetry: { isEnabled: true },
+});
+```
+
+With native telemetry and tracing enabled, the tool automatically attaches its
+signal to the active Raindrop event. When there is no active trace context,
+provide `eventId` or `getEventId`:
+
+```ts
+const diagnostics = raindrop.createSelfDiagnosticsTool({
+  getEventId: () => currentEventId,
+});
+```
+
 Setting `nativeTelemetry: true` on pre-v7 throws a clear error. The Proxy path remains the default and supports features not yet available on the native path (`buildEvent`, output attachment extraction).
 
 #### Per-call routing on AI SDK v7 beta.94+
@@ -214,7 +292,7 @@ This package is tested against multiple Vercel AI SDK versions:
 | v4.x    | ✅ Supported | Proxy |
 | v5.x    | ✅ Supported | Proxy |
 | v6.x    | ✅ Supported | Proxy |
-| v7.x (beta) | ✅ Supported | Proxy (default) or native `Telemetry` (opt-in, formerly `TelemetryIntegration` pre-beta.111). Verified against beta.116. |
+| v7.x (beta/canary) | ✅ Supported | Proxy (default) or native `Telemetry` (opt-in, formerly `TelemetryIntegration` pre-beta.111). Verified against beta.116 and canary.171. |
 
 ### Version Differences Handled