@struct-ai/sdk 0.1.0 → 0.1.2

package/README.md

@@ -20,11 +20,15 @@ Requires Node 18+.
 
 ## Quickstart
 
+Get an ingest key from
+[app.struct.ai/settings?tab=ingest-keys](https://app.struct.ai/settings?tab=ingest-keys),
+then:
+
 ```ts
 import { struct } from "@struct-ai/sdk";
 // Initialize once, as early as possible in your process
 struct.init({
-  ingestKey: process.env.STRUCT_INGEST_KEY!,
+  ingestKey: process.env.STRUCT_INGEST_KEY!, // or pass the string directly
   serviceName: "my-agent",
   environment: "production",
 });
@@ -58,6 +62,103 @@ await struct.agent({ name: "checkout" }, async () => {
 | `@langchain/core` `BaseRetriever` | `.invoke` | `retrieval {name}` | |
 | `@langchain/langgraph` `Pregel` | `.invoke`, `.stream` | `invoke_agent {name}` | Covers `createReactAgent`, custom graphs. `thread_id` → `gen_ai.conversation.id` |
 
+## Framework integration
+
+`struct.init()` takes the same options regardless of which framework
+you're instrumenting. Required: `ingestKey` (get one at
+[app.struct.ai/settings?tab=ingest-keys](https://app.struct.ai/settings?tab=ingest-keys)).
+Recommended: `serviceName`, `environment`.
+
+What you need to do beyond `init()` depends on whether you're using an
+**agent framework** (which has built-in concepts of agents and tools) or
+an **LLM SDK directly** (which only knows about chat completions). The
+SDK auto-instruments both, but only agent frameworks get full agent +
+tool spans for free — when you call an LLM SDK directly, you have to
+tell the SDK where the agent and tool boundaries are.
+
+Call `init()` once, as early as possible, *before* the instrumented
+libraries are imported, so their prototypes are patched before any
+instance is constructed.
+
+### Agent frameworks — fully auto-instrumented
+
+For these, calling `struct.init()` is the only setup. Agent, tool, chat,
+and retrieval spans all emit automatically.
+
+#### LangChain / LangGraph (with an agent or graph)
+
+```ts
+import { struct } from "@struct-ai/sdk";
+struct.init({ ingestKey: "pk-...", serviceName: "my-graph" });
+
+import { createReactAgent } from "@langchain/langgraph/prebuilt";
+// Pregel invocations get invoke_agent spans. BaseChatModel calls get
+// chat spans. StructuredTool.invoke gets execute_tool spans.
+// BaseRetriever.invoke gets retrieval spans.
+```
+
+### LLM SDKs used directly — manual agent + tool scopes required
+
+When you call an LLM SDK directly (no agent framework wrapping it), only
+`chat` spans emit automatically. You need to wrap your agent loop in
+`struct.agent()` and each tool execution in `struct.tool()` so the SDK
+knows where to put the agent and tool boundaries — otherwise you'll see
+free-floating chat spans with no agent or tool context around them.
+
+#### Anthropic SDK (raw)
+
+```ts
+import { struct } from "@struct-ai/sdk";
+struct.init({ ingestKey: "pk-...", serviceName: "checkout-agent" });
+
+import Anthropic from "@anthropic-ai/sdk";
+const client = new Anthropic();
+
+// Required: wrap the agent loop yourself.
+await struct.agent({ name: "checkout" }, async () => {
+  const msg = await client.messages.create({
+    model: "claude-3-5-sonnet-20241022",
+    max_tokens: 1024,
+    messages: [...],
+  });
+
+  // Required: wrap each tool execution.
+  // tool_call_id is auto-filled from the preceding Anthropic response.
+  await struct.tool({ name: "search" }, async () => {
+    return await search(...);
+  });
+});
+```
+
+`@anthropic-ai/sdk`, `@anthropic-ai/bedrock-sdk`, and `@anthropic-ai/vertex-sdk`
+are all auto-instrumented for chat spans.
+
+#### LangChain `BaseChatModel` (no agent/graph)
+
+If you call `ChatAnthropic.invoke(...)` (or any other `BaseChatModel`)
+without wrapping it in `AgentExecutor` or a LangGraph graph, only the chat
+span emits automatically. Same rule as raw Anthropic — wrap your agent
+loop in `struct.agent()` and tool execution in `struct.tool()`.
+
+```ts
+import { struct } from "@struct-ai/sdk";
+struct.init({ ingestKey: "pk-...", serviceName: "my-agent" });
+
+import { ChatAnthropic } from "@langchain/anthropic";
+const llm = new ChatAnthropic({ model: "claude-3-5-sonnet-20241022" });
+
+await struct.agent({ name: "my-agent" }, async () => {
+  const response = await llm.invoke([["user", "..."]]);
+  await struct.tool({ name: "search" }, async () => {
+    // ...
+  });
+});
+```
+
+When you do use `ChatAnthropic` *and* have `@anthropic-ai/sdk` installed,
+the chat span comes from the Anthropic patch (single span); the LangChain
+layer suppresses its duplicate.
+
 ## Content capture
 
 The SDK supports four capture modes controlling how prompt/response content is emitted.
@@ -144,25 +245,6 @@ response excludes). Matches the Python SDK.
   attribute is still set, so "Spawned by" on the child side still renders —
   but the parent's forward link to the subagent won't appear.
 
-## Parity with the Python SDK
-
-Span names, attribute keys, and log event shapes match `struct-sdk-python`
-byte-for-byte. Running the same agent logic in both SDKs against the same
-tenant produces structurally identical traces in the Struct UI.
-
-One deliberate divergence: the TS SDK finalizes streaming chat spans via the
-`finalMessage` event, closing a known gap in the Python SDK where
-`messages.stream()` didn't populate the pending-tool-call queue.
-
-## Development
-
-```bash
-pnpm install
-pnpm -F @struct-ai/sdk typecheck
-pnpm -F @struct-ai/sdk test
-pnpm -F @struct-ai/sdk build
-```
-
 ## License
 
 Apache-2.0

package/dist/node_modules/@struct-ai/sdk/dist/node_modules/@struct-ai/sdk/dist/node_modules/@struct-ai/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@struct-ai/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry",
   "type": "module",
   "main": "./dist/commonjs/index.js",

package/dist/node_modules/@struct-ai/sdk/dist/node_modules/@struct-ai/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@struct-ai/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry",
   "type": "module",
   "main": "./dist/commonjs/index.js",

package/dist/node_modules/@struct-ai/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@struct-ai/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry",
   "type": "module",
   "main": "./dist/commonjs/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@struct-ai/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry",
   "type": "module",
   "main": "./dist/commonjs/index.js",