@intelli-1113/stratos-sdk 1.2.3 → 1.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +552 -64
- package/package.json +49 -22
- package/src/cli-inspect.js +95 -0
- package/src/enforcement.js +163 -0
- package/src/index.js +139 -43
- package/src/inspect-langchain.js +428 -0
- package/src/mcp-proxy.js +42 -2
- package/src/postinstall.js +29 -0
- package/src/register.js +57 -5
- package/src/vercel-ai-inject.js +78 -0
- package/src/vercel-ai-loader.js +111 -0
- package/src/vercel-ai.js +62 -0
package/README.md
CHANGED
|
@@ -1,64 +1,552 @@
|
|
|
1
|
-
# @intelli-1113/stratos-sdk
|
|
2
|
-
|
|
3
|
-
One
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
1
|
+
# @intelli-1113/stratos-sdk
|
|
2
|
+
|
|
3
|
+
**One install** for [Stratos AI](https://github.com) agent observability:
|
|
4
|
+
|
|
5
|
+
1. **OpenLLMetry / Traceloop** — LLM traces (model, tokens, prompts, tools, latency)
|
|
6
|
+
2. **OTLP JSON → Stratos** — export to your dashboard (`/api/ingest`)
|
|
7
|
+
3. **Heartbeat** — agent stays “online” between calls (`/api/heartbeat`)
|
|
8
|
+
4. **Vercel AI auto-telemetry** — no `experimental_telemetry` in client code
|
|
9
|
+
5. **`stratos-mcp-proxy`** — tool-call metering for host MCP servers
|
|
10
|
+
|
|
11
|
+
| | |
|
|
12
|
+
|---|---|
|
|
13
|
+
| **Package** | `@intelli-1113/stratos-sdk` |
|
|
14
|
+
| **Version** | `1.3.1` |
|
|
15
|
+
| **Runtime** | Node.js **≥ 18** (ESM; **≥ 20** recommended for LangChain instrumentation) |
|
|
16
|
+
| **Default Stratos URL** | `http://localhost:4000` |
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Table of contents
|
|
21
|
+
|
|
22
|
+
- [What you get](#what-you-get)
|
|
23
|
+
- [Install](#install)
|
|
24
|
+
- [Configure](#configure)
|
|
25
|
+
- [How to use](#how-to-use)
|
|
26
|
+
- [What is supported](#what-is-supported)
|
|
27
|
+
- [LangChain version inspect & fix](#langchain-version-inspect--fix)
|
|
28
|
+
- [Vercel AI SDK (important)](#vercel-ai-sdk-important)
|
|
29
|
+
- [Environment reference](#environment-reference)
|
|
30
|
+
- [Auto-detected metadata](#auto-detected-metadata)
|
|
31
|
+
- [MCP proxy](#mcp-proxy)
|
|
32
|
+
- [How it works](#how-it-works)
|
|
33
|
+
- [Troubleshooting](#troubleshooting)
|
|
34
|
+
- [Security & privacy](#security--privacy)
|
|
35
|
+
- [API](#api)
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## What you get
|
|
40
|
+
|
|
41
|
+
| Feature | Description |
|
|
42
|
+
|--------|-------------|
|
|
43
|
+
| **Liveness** | Heartbeat so the agent shows online in Stratos |
|
|
44
|
+
| **LLM spans** | Model name, token usage, latency, prompts/outputs (when enabled) |
|
|
45
|
+
| **Tool spans** | Tool name, args, results (from instrumented frameworks / MCP proxy) |
|
|
46
|
+
| **Zero agent logic changes** | Prefer `node --import …/register` — no instrumentation in business code |
|
|
47
|
+
| **`.env` load** | On `--import`, loads `./.env` from `cwd` so `STRATOS_TOKEN` is available early |
|
|
48
|
+
| **MCP host tools** | `stratos-mcp-proxy` wraps Claude Desktop / Cursor / VS Code MCP servers |
|
|
49
|
+
| **LangChain inspect** | `stratos-inspect` checks core version; optional uninstall old + install 1.x |
|
|
50
|
+
|
|
51
|
+
Traces go to:
|
|
52
|
+
|
|
53
|
+
```http
|
|
54
|
+
POST {STRATOS_URL}/api/ingest
|
|
55
|
+
Header: x-stratos-token: <STRATOS_TOKEN>
|
|
56
|
+
Body: OTLP/JSON
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Install
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
npm i @intelli-1113/stratos-sdk
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
For MCP proxy use from a host app (global CLI):
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
npm i -g @intelli-1113/stratos-sdk
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Configure
|
|
76
|
+
|
|
77
|
+
1. Open **Stratos AI** → **Add agent** → copy the enrollment **token**.
|
|
78
|
+
2. Set environment variables (shell or `.env` in the project root):
|
|
79
|
+
|
|
80
|
+
```env
|
|
81
|
+
# Required
|
|
82
|
+
STRATOS_TOKEN=your_enrollment_token_here
|
|
83
|
+
|
|
84
|
+
# Optional (defaults shown)
|
|
85
|
+
STRATOS_URL=http://localhost:4000
|
|
86
|
+
STRATOS_APP_NAME=my-agent
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Production example:
|
|
90
|
+
|
|
91
|
+
```env
|
|
92
|
+
STRATOS_TOKEN=...
|
|
93
|
+
STRATOS_URL=https://stratos.example.com
|
|
94
|
+
STRATOS_APP_NAME=checkout-agent
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
> Change token/URL anytime and **restart** the process. No code change required.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## How to use
|
|
102
|
+
|
|
103
|
+
### Option A — Zero app-code changes (**recommended**)
|
|
104
|
+
|
|
105
|
+
Preload the SDK before your app. This is the **required** style for **Vercel AI SDK**.
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
node --import @intelli-1113/stratos-sdk/register server.js
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
`package.json`:
|
|
112
|
+
|
|
113
|
+
```json
|
|
114
|
+
{
|
|
115
|
+
"scripts": {
|
|
116
|
+
"start": "node --import @intelli-1113/stratos-sdk/register server.js",
|
|
117
|
+
"dev": "node --import @intelli-1113/stratos-sdk/register --watch server.js"
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Windows PowerShell (same idea):
|
|
123
|
+
|
|
124
|
+
```powershell
|
|
125
|
+
node --import @intelli-1113/stratos-sdk/register .\server.js
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Your application code stays normal (no Stratos APIs required):
|
|
129
|
+
|
|
130
|
+
```js
|
|
131
|
+
// server.js — business logic only
|
|
132
|
+
import { generateText } from "ai";
|
|
133
|
+
import { mistral } from "@ai-sdk/mistral";
|
|
134
|
+
// or: ChatMistralAI from @langchain/mistralai, OpenAI SDK, etc.
|
|
135
|
+
|
|
136
|
+
const { text } = await generateText({
|
|
137
|
+
model: mistral("mistral-large-latest"),
|
|
138
|
+
prompt: "Hello",
|
|
139
|
+
});
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Option B — First import in the entrypoint
|
|
143
|
+
|
|
144
|
+
Works well for **LangChain**, **OpenAI**, **Anthropic**, **Google GenAI**, etc. (Traceloop auto-patches these **if** this import runs before those libraries load).
|
|
145
|
+
|
|
146
|
+
```js
|
|
147
|
+
import "@intelli-1113/stratos-sdk/register"; // must be first
|
|
148
|
+
import { ChatOpenAI } from "@langchain/openai";
|
|
149
|
+
// ... rest of app
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
> **Vercel AI note:** a normal `import "@intelli-1113/stratos-sdk/register"` in the **same file** as `import { generateText } from "ai"` is often **too late** (ESM links the whole graph before evaluation). Use **Option A (`--import`)** for Vercel AI.
|
|
153
|
+
|
|
154
|
+
### Option C — Programmatic `start()`
|
|
155
|
+
|
|
156
|
+
```js
|
|
157
|
+
import { start } from "@intelli-1113/stratos-sdk";
|
|
158
|
+
|
|
159
|
+
start({
|
|
160
|
+
token: process.env.STRATOS_TOKEN,
|
|
161
|
+
url: process.env.STRATOS_URL, // optional
|
|
162
|
+
appName: "my-agent", // optional
|
|
163
|
+
model: "mistral-large-latest", // optional heartbeat metadata
|
|
164
|
+
tools: ["web_search"], // optional heartbeat metadata
|
|
165
|
+
framework: "vercel-ai", // optional override
|
|
166
|
+
heartbeatMs: 30000, // optional
|
|
167
|
+
});
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
For Vercel AI with Option C, still prefer launching with `--import @intelli-1113/stratos-sdk/register` so the ESM loader is active, **or** call `start()` only after registering the loader yourself (Option A is simpler).
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## What is supported
|
|
175
|
+
|
|
176
|
+
### Auto-instrumented stacks (OpenLLMetry / Traceloop)
|
|
177
|
+
|
|
178
|
+
These emit rich LLM/tool spans **without** client telemetry flags, when the SDK loads **before** the library:
|
|
179
|
+
|
|
180
|
+
| Stack | Node support via this SDK | Notes |
|
|
181
|
+
|-------|---------------------------|--------|
|
|
182
|
+
| **LangChain.js** | Yes | Agents, tools, chat models |
|
|
183
|
+
| **LangGraph.js** | Yes | Same family as LangChain |
|
|
184
|
+
| **LlamaIndex.TS** | Yes | When package is present |
|
|
185
|
+
| **OpenAI SDK** (`openai`) | Yes | Chat/completions |
|
|
186
|
+
| **Anthropic SDK** | Yes | Messages API |
|
|
187
|
+
| **Google Generative AI / GenAI** | Yes | Direct Google SDKs |
|
|
188
|
+
| **AWS Bedrock** (SDK path) | Yes | Via Traceloop instrumentation |
|
|
189
|
+
| **Together AI** | Yes | Via Traceloop |
|
|
190
|
+
| **Vertex AI** | Yes | Via Traceloop |
|
|
191
|
+
| **Vercel AI SDK** (`ai`) | Yes (**Stratos-specific**) | See [below](#vercel-ai-sdk-important) — needs `--import` |
|
|
192
|
+
|
|
193
|
+
### Model providers (examples)
|
|
194
|
+
|
|
195
|
+
Model choice is independent of framework. These are common pairs:
|
|
196
|
+
|
|
197
|
+
| Provider | Typical packages | Observed when |
|
|
198
|
+
|----------|------------------|---------------|
|
|
199
|
+
| OpenAI | `openai`, `@ai-sdk/openai`, LangChain OpenAI | Instrumented path or Vercel AI + Stratos loader |
|
|
200
|
+
| Anthropic | `@anthropic-ai/sdk`, `@ai-sdk/anthropic` | Same |
|
|
201
|
+
| Google / Gemini | `@google/generative-ai`, `@google/genai`, `@ai-sdk/google` | Same |
|
|
202
|
+
| Mistral | `@ai-sdk/mistral`, `@langchain/mistralai` | Same |
|
|
203
|
+
| Azure OpenAI / Bedrock | respective SDKs or LangChain | Via instrumented SDKs / LangChain |
|
|
204
|
+
|
|
205
|
+
### Not automatic (needs extra work or different product path)
|
|
206
|
+
|
|
207
|
+
| Approach | Why |
|
|
208
|
+
|----------|-----|
|
|
209
|
+
| Raw `fetch` to LLM HTTP APIs | Nothing to patch |
|
|
210
|
+
| Custom agent runtimes with no OTel | No spans unless you emit OTLP yourself |
|
|
211
|
+
| Python agents | Use the **Python** Stratos / OpenLLMetry package if provided (this package is **Node**) |
|
|
212
|
+
| Frameworks without OpenLLMetry support | May only show heartbeat until support is added |
|
|
213
|
+
|
|
214
|
+
### Heartbeat-only vs full traces
|
|
215
|
+
|
|
216
|
+
| You see in Stratos | Meaning |
|
|
217
|
+
|--------------------|---------|
|
|
218
|
+
| Agent **online**, little detail | Heartbeat works; few/no LLM spans |
|
|
219
|
+
| Model, tokens, tools, prompts | Spans reached `/api/ingest` |
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## LangChain version inspect & fix
|
|
224
|
+
|
|
225
|
+
Stratos LangChain **metrics** need:
|
|
226
|
+
|
|
227
|
+
```text
|
|
228
|
+
@langchain/core >= 1.0.0 and < 2.0.0
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
(from `@traceloop/instrumentation-langchain`, e.g. `^1.2.4` works).
|
|
232
|
+
|
|
233
|
+
Installing the SDK **does not** auto-upgrade the client’s LangChain 0.x app.
|
|
234
|
+
Use **`stratos-inspect`** in the **client project** to check and optionally fix.
|
|
235
|
+
|
|
236
|
+
### Inspect only
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
cd /path/to/client-agent
|
|
240
|
+
npx stratos-inspect
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
JSON:
|
|
244
|
+
|
|
245
|
+
```bash
|
|
246
|
+
npx stratos-inspect --json
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
### Uninstall old LangChain (<1.0) and install 1.x
|
|
250
|
+
|
|
251
|
+
Interactive (asks y/N):
|
|
252
|
+
|
|
253
|
+
```bash
|
|
254
|
+
npx stratos-inspect --fix
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
Non-interactive (CI / scripts):
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
npx stratos-inspect --fix --yes
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
Dry run (show plan only):
|
|
264
|
+
|
|
265
|
+
```bash
|
|
266
|
+
npx stratos-inspect --fix --dry-run
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
What `--fix` does:
|
|
270
|
+
|
|
271
|
+
1. Detects LangChain family packages in the project
|
|
272
|
+
2. If `@langchain/core` is **< 1.0** → uninstalls those packages
|
|
273
|
+
3. Installs recommended **1.x** set (`@langchain/core@^1.2.4`, `langchain@^1.5.4`, plus any previous `@langchain/*` providers at `^1`)
|
|
274
|
+
4. Uses npm / pnpm / yarn / bun based on lockfile
|
|
275
|
+
|
|
276
|
+
It will **not** auto-downgrade core **≥ 2.0**.
|
|
277
|
+
|
|
278
|
+
### After install of Stratos
|
|
279
|
+
|
|
280
|
+
`postinstall` prints a warning if LangChain is present but incompatible (does **not** change deps).
|
|
281
|
+
|
|
282
|
+
At runtime, `start()` / `register` also warns and suggests `npx stratos-inspect --fix`.
|
|
283
|
+
|
|
284
|
+
Hard-fail on start if desired:
|
|
285
|
+
|
|
286
|
+
---
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
### What the SDK does for Vercel AI
|
|
290
|
+
|
|
291
|
+
1. Registers a Node **custom module loader** on `register`
|
|
292
|
+
2. Intercepts bare imports of `"ai"`
|
|
293
|
+
3. Re-exports the real package
|
|
294
|
+
4. Wraps `generateText`, `streamText`, `generateObject`, `streamObject`, `embed`, `embedMany`, and related helpers
|
|
295
|
+
5. Injects telemetry defaults (`experimental_telemetry` / `telemetry`)
|
|
296
|
+
|
|
297
|
+
### Client code (unchanged)
|
|
298
|
+
|
|
299
|
+
```js
|
|
300
|
+
import { generateText, stepCountIs } from "ai";
|
|
301
|
+
import { openai } from "@ai-sdk/openai";
|
|
302
|
+
// import { mistral } from "@ai-sdk/mistral";
|
|
303
|
+
// import { google } from "@ai-sdk/google";
|
|
304
|
+
|
|
305
|
+
await generateText({
|
|
306
|
+
model: openai("gpt-4o"),
|
|
307
|
+
prompt: "Summarize today's agenda",
|
|
308
|
+
tools: { /* ... */ },
|
|
309
|
+
stopWhen: stepCountIs(5),
|
|
310
|
+
});
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
### How the client starts the process
|
|
314
|
+
|
|
315
|
+
```bash
|
|
316
|
+
node --import @intelli-1113/stratos-sdk/register app.js
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
### Opt-out
|
|
320
|
+
|
|
321
|
+
| Goal | Setting |
|
|
322
|
+
|------|---------|
|
|
323
|
+
| Disable Vercel AI wrapping entirely | `STRATOS_VERCEL_AI=0` |
|
|
324
|
+
| Do not record prompts | `STRATOS_RECORD_INPUTS=0` |
|
|
325
|
+
| Do not record completions | `STRATOS_RECORD_OUTPUTS=0` |
|
|
326
|
+
| Disable one call only | Pass `experimental_telemetry: { isEnabled: false }` (or `telemetry: { isEnabled: false }` on AI SDK v7) |
|
|
327
|
+
|
|
328
|
+
### AI SDK v7
|
|
329
|
+
|
|
330
|
+
If the app also installs `@ai-sdk/otel`, the SDK will try `registerTelemetry(new OpenTelemetry())` when available. The loader-based wrap still covers v5/v6-style `experimental_telemetry`.
|
|
331
|
+
|
|
332
|
+
---
|
|
333
|
+
|
|
334
|
+
## Environment reference
|
|
335
|
+
|
|
336
|
+
### Core
|
|
337
|
+
|
|
338
|
+
| Variable | Required | Default | Description |
|
|
339
|
+
|----------|----------|---------|-------------|
|
|
340
|
+
| `STRATOS_TOKEN` | **Yes** | — | Enrollment token from Stratos → Add agent |
|
|
341
|
+
| `STRATOS_URL` | No | `http://localhost:4000` | Stratos origin (no trailing slash required) |
|
|
342
|
+
| `STRATOS_APP_NAME` | No | `npm_package_name` or `"agent"` | Display name / `service.name` |
|
|
343
|
+
| `STRATOS_HEARTBEAT_MS` | No | `30000` | Heartbeat interval (ms). `0` disables interval |
|
|
344
|
+
|
|
345
|
+
### Metadata overrides
|
|
346
|
+
|
|
347
|
+
| Variable | Description |
|
|
348
|
+
|----------|-------------|
|
|
349
|
+
| `STRATOS_FRAMEWORK` | Force framework label (`langchain`, `vercel-ai`, `langgraph`, …) |
|
|
350
|
+
| `STRATOS_MODEL` | Preferred model label for heartbeat |
|
|
351
|
+
| `NVIDIA_MODEL` / `OPENAI_MODEL` / `ANTHROPIC_MODEL` / `GEMINI_MODEL` / `GOOGLE_MODEL` / `LLM_MODEL` / `MODEL` | Fallback model detection for heartbeat |
|
|
352
|
+
| `STRATOS_TOOLS` | Comma-separated tool names for heartbeat (`web_search,retriever`) |
|
|
353
|
+
| `STRATOS_FUNCTION_ID` | Default `functionId` on injected Vercel AI telemetry |
|
|
354
|
+
| `STRATOS_STRICT_LANGCHAIN` | Set `1` to throw on start if LangChain core is < 1.0 |
|
|
355
|
+
| `STRATOS_SKIP_POSTINSTALL` | Set `1` to skip postinstall LangChain warning |
|
|
356
|
+
|
|
357
|
+
### Vercel AI controls
|
|
358
|
+
|
|
359
|
+
| Variable | Default | Description |
|
|
360
|
+
|----------|---------|-------------|
|
|
361
|
+
| `STRATOS_VERCEL_AI` | on | Set `0` / `false` / `off` to disable auto wrap |
|
|
362
|
+
| `STRATOS_RECORD_INPUTS` | on | Set `0` to skip recording prompts |
|
|
363
|
+
| `STRATOS_RECORD_OUTPUTS` | on | Set `0` to skip recording outputs |
|
|
364
|
+
|
|
365
|
+
---
|
|
366
|
+
|
|
367
|
+
## Auto-detected metadata
|
|
368
|
+
|
|
369
|
+
On each heartbeat the SDK POSTs JSON to `{STRATOS_URL}/api/heartbeat` with:
|
|
370
|
+
|
|
371
|
+
| Field | Source |
|
|
372
|
+
|-------|--------|
|
|
373
|
+
| **framework** | `package.json` deps / resolution, or `STRATOS_FRAMEWORK` |
|
|
374
|
+
| **model** | Env vars above or `start({ model })` |
|
|
375
|
+
| **tools** | `STRATOS_TOOLS` or `start({ tools })` (spans refine tools over time) |
|
|
376
|
+
|
|
377
|
+
Detection order for framework (first match wins, unless overridden):
|
|
378
|
+
|
|
379
|
+
1. Google ADK
|
|
380
|
+
2. OpenAI Agents
|
|
381
|
+
3. LlamaIndex
|
|
382
|
+
4. CrewAI
|
|
383
|
+
5. LangGraph
|
|
384
|
+
6. LangChain
|
|
385
|
+
7. Vercel AI (`ai`)
|
|
386
|
+
8. Google GenAI SDKs
|
|
387
|
+
9. Anthropic SDK
|
|
388
|
+
10. OpenAI SDK
|
|
389
|
+
|
|
390
|
+
> If a project installs **both** LangChain and Vercel AI, framework detection may prefer LangChain. Set `STRATOS_FRAMEWORK=vercel-ai` (or use separate apps/tokens) when needed.
|
|
391
|
+
|
|
392
|
+
---
|
|
393
|
+
|
|
394
|
+
## MCP proxy
|
|
395
|
+
|
|
396
|
+
Host-launched MCP servers (Claude Desktop, Cursor, VS Code, …) do not run your Node agent process. Use the bundled CLI to proxy **tool calls**:
|
|
397
|
+
|
|
398
|
+
```bash
|
|
399
|
+
npm i -g @intelli-1113/stratos-sdk
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
Host config example:
|
|
403
|
+
|
|
404
|
+
```json
|
|
405
|
+
{
|
|
406
|
+
"mcpServers": {
|
|
407
|
+
"weather": {
|
|
408
|
+
"command": "stratos-mcp-proxy",
|
|
409
|
+
"args": ["--", "npx", "-y", "@scope/weather-mcp@latest"],
|
|
410
|
+
"env": {
|
|
411
|
+
"STRATOS_TOKEN": "<token>",
|
|
412
|
+
"STRATOS_URL": "http://localhost:4000",
|
|
413
|
+
"STRATOS_APP_NAME": "weather"
|
|
414
|
+
}
|
|
415
|
+
}
|
|
416
|
+
}
|
|
417
|
+
}
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
| Behavior | Detail |
|
|
421
|
+
|----------|--------|
|
|
422
|
+
| Protocol | Forwards JSON-RPC stdio **verbatim** |
|
|
423
|
+
| Telemetry | Each `tools/call` → OTLP-like span on `/api/ingest` |
|
|
424
|
+
| Liveness | Heartbeat on `/api/heartbeat` |
|
|
425
|
+
| Logging | **stderr only** (stdout is reserved for MCP) |
|
|
426
|
+
| LLM tokens | **Not** captured (MCP servers usually don’t call the LLM) |
|
|
427
|
+
|
|
428
|
+
Usage:
|
|
429
|
+
|
|
430
|
+
```bash
|
|
431
|
+
stratos-mcp-proxy -- <command> [args...]
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
---
|
|
435
|
+
|
|
436
|
+
## How it works
|
|
437
|
+
|
|
438
|
+
```text
|
|
439
|
+
┌─────────────────────┐
|
|
440
|
+
│ Your agent process │
|
|
441
|
+
│ (Node.js) │
|
|
442
|
+
└──────────┬──────────┘
|
|
443
|
+
│ 1. --import register
|
|
444
|
+
▼
|
|
445
|
+
┌─────────────────────┐
|
|
446
|
+
│ stratos-sdk │
|
|
447
|
+
│ • load .env │
|
|
448
|
+
│ • Vercel AI loader │
|
|
449
|
+
│ • Traceloop init │
|
|
450
|
+
│ • OTLP JSON export │
|
|
451
|
+
│ • heartbeat loop │
|
|
452
|
+
└──────────┬──────────┘
|
|
453
|
+
│
|
|
454
|
+
├─ POST /api/ingest (spans: LLM + tools)
|
|
455
|
+
└─ POST /api/heartbeat (online + metadata)
|
|
456
|
+
│
|
|
457
|
+
▼
|
|
458
|
+
┌───────────────┐
|
|
459
|
+
│ Stratos AI │
|
|
460
|
+
│ :4000 UI │
|
|
461
|
+
└───────────────┘
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
- **LangChain / OpenAI / …** → Traceloop instrumentations create spans.
|
|
465
|
+
- **Vercel AI** → Stratos loader injects telemetry so the `ai` package creates OTel spans; Traceloop exports them.
|
|
466
|
+
- **MCP** → `stratos-mcp-proxy` synthesizes tool spans.
|
|
467
|
+
|
|
468
|
+
---
|
|
469
|
+
|
|
470
|
+
## Troubleshooting
|
|
471
|
+
|
|
472
|
+
| Symptom | Likely cause | Fix |
|
|
473
|
+
|---------|--------------|-----|
|
|
474
|
+
| `[stratos] STRATOS_TOKEN not set` | Token missing at process start | Set `STRATOS_TOKEN` or put it in `.env` in `cwd` |
|
|
475
|
+
| Agent online, no tokens/tools | Framework not instrumented or Vercel AI without `--import` | Use `--import …/register`; confirm stack is supported |
|
|
476
|
+
| Vercel AI still no spans | Started without `--import` | `node --import @intelli-1113/stratos-sdk/register app.js` |
|
|
477
|
+
| Wrong framework label | Mixed deps in one `package.json` | Set `STRATOS_FRAMEWORK=vercel-ai` (or `langchain`) |
|
|
478
|
+
| Spans lost on short CLI scripts | Process exited before flush | SDK flushes on `beforeExit` / signals; keep process alive until request finishes |
|
|
479
|
+
| MCP tools not showing | Proxy not wrapping command / no token | Use `stratos-mcp-proxy -- …` and set env on the host config |
|
|
480
|
+
| Local Stratos empty | Wrong URL | Default is `http://localhost:4000`; ensure Stratos is running |
|
|
481
|
+
|
|
482
|
+
Verify the SDK loaded:
|
|
483
|
+
|
|
484
|
+
```text
|
|
485
|
+
[stratos] telemetry → http://localhost:4000/api/ingest (heartbeat 30000ms, framework=…)
|
|
486
|
+
[stratos] vercel-ai auto-telemetry: esm-loader-shim # when Vercel path is active
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
---
|
|
490
|
+
|
|
491
|
+
## Security & privacy
|
|
492
|
+
|
|
493
|
+
- **Token** — treat `STRATOS_TOKEN` like a secret; do not commit it.
|
|
494
|
+
- **Prompts/outputs** — may be sent in spans. Disable with:
|
|
495
|
+
- `STRATOS_RECORD_INPUTS=0`
|
|
496
|
+
- `STRATOS_RECORD_OUTPUTS=0`
|
|
497
|
+
- **Network** — telemetry is sent to `STRATOS_URL` only.
|
|
498
|
+
- **MCP proxy** — tool args/results are reported; avoid secrets in tool arguments when possible.
|
|
499
|
+
|
|
500
|
+
---
|
|
501
|
+
|
|
502
|
+
### Entry points
|
|
503
|
+
|
|
504
|
+
| Import | Purpose |
|
|
505
|
+
|--------|---------|
|
|
506
|
+
| `@intelli-1113/stratos-sdk/register` | Side-effect: env + Vercel loader + `start()` |
|
|
507
|
+
| `@intelli-1113/stratos-sdk` | `{ start }` for programmatic use |
|
|
508
|
+
|
|
509
|
+
### CLI
|
|
510
|
+
|
|
511
|
+
| Command | Purpose |
|
|
512
|
+
|---------|---------|
|
|
513
|
+
| `stratos-inspect` | Check LangChain compatibility in current project |
|
|
514
|
+
| `stratos-inspect --fix [--yes]` | Uninstall old LangChain and install 1.x |
|
|
515
|
+
| `stratos-mcp-proxy -- <cmd> [args…]` | MCP stdio proxy with tool telemetry |
|
|
516
|
+
|
|
517
|
+
### `inspectLangChain()` / `fixLangChain()`
|
|
518
|
+
|
|
519
|
+
See [LangChain version inspect & fix](#langchain-version-inspect--fix).
|
|
520
|
+
|
|
521
|
+
---
|
|
522
|
+
|
|
523
|
+
## Requirements
|
|
524
|
+
|
|
525
|
+
- **Node.js** 18+ (20+ recommended; `.env` via `process.loadEnvFile` when available)
|
|
526
|
+
- Network reachability to Stratos (`STRATOS_URL`)
|
|
527
|
+
- Valid **STRATOS_TOKEN** from the Stratos UI
|
|
528
|
+
|
|
529
|
+
---
|
|
530
|
+
|
|
531
|
+
## License
|
|
532
|
+
|
|
533
|
+
MIT
|
|
534
|
+
|
|
535
|
+
---
|
|
536
|
+
|
|
537
|
+
## Changelog (recent)
|
|
538
|
+
|
|
539
|
+
### 1.3.1
|
|
540
|
+
|
|
541
|
+
- **`stratos-inspect`** CLI: check LangChain core version; optional `--fix` uninstall old + install 1.x
|
|
542
|
+
- **postinstall** warning if LangChain < 1.0
|
|
543
|
+
- Runtime warning on `start()`; optional `STRATOS_STRICT_LANGCHAIN=1`
|
|
544
|
+
- Exports: `inspectLangChain`, `fixLangChain`
|
|
545
|
+
|
|
546
|
+
### 1.3.0
|
|
547
|
+
|
|
548
|
+
- Auto Vercel AI SDK telemetry via ESM module loader (no client `experimental_telemetry`)
|
|
549
|
+
- Load `.env` from `cwd` when using `--import`
|
|
550
|
+
- Document `--import` as the recommended zero-code entry
|
|
551
|
+
- Framework / model / tools heartbeat metadata retained
|
|
552
|
+
- MCP proxy unchanged in purpose (`stratos-mcp-proxy`)
|
package/package.json
CHANGED
|
@@ -1,22 +1,49 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@intelli-1113/stratos-sdk",
|
|
3
|
-
"version": "1.2
|
|
4
|
-
"description": "
|
|
5
|
-
"type": "module",
|
|
6
|
-
"main": "./src/index.js",
|
|
7
|
-
"exports": {
|
|
8
|
-
".": "./src/index.js",
|
|
9
|
-
"./register": "./src/register.js"
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
"
|
|
13
|
-
|
|
14
|
-
"
|
|
15
|
-
},
|
|
16
|
-
"
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
"
|
|
21
|
-
|
|
22
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "@intelli-1113/stratos-sdk",
|
|
3
|
+
"version": "1.3.2",
|
|
4
|
+
"description": "Stratos AI agent telemetry (OpenLLMetry), Vercel AI auto-spans, LangChain inspect/fix, MCP proxy.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./src/index.js",
|
|
7
|
+
"exports": {
|
|
8
|
+
".": "./src/index.js",
|
|
9
|
+
"./register": "./src/register.js",
|
|
10
|
+
"./inspect": "./src/inspect-langchain.js"
|
|
11
|
+
},
|
|
12
|
+
"bin": {
|
|
13
|
+
"stratos-mcp-proxy": "./src/mcp-proxy.js",
|
|
14
|
+
"stratos-inspect": "./src/cli-inspect.js"
|
|
15
|
+
},
|
|
16
|
+
"files": [
|
|
17
|
+
"src"
|
|
18
|
+
],
|
|
19
|
+
"scripts": {
|
|
20
|
+
"postinstall": "node ./src/postinstall.js",
|
|
21
|
+
"test": "node -e \"import('./src/index.js').then(m=>console.log('ok',Object.keys(m)))\"",
|
|
22
|
+
"inspect": "node ./src/cli-inspect.js"
|
|
23
|
+
},
|
|
24
|
+
"keywords": [
|
|
25
|
+
"stratos",
|
|
26
|
+
"openllmetry",
|
|
27
|
+
"opentelemetry",
|
|
28
|
+
"observability",
|
|
29
|
+
"llm",
|
|
30
|
+
"agent",
|
|
31
|
+
"vercel-ai",
|
|
32
|
+
"langchain"
|
|
33
|
+
],
|
|
34
|
+
"license": "MIT",
|
|
35
|
+
"dependencies": {
|
|
36
|
+
"@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
|
|
37
|
+
"@traceloop/node-server-sdk": "^0.27.0",
|
|
38
|
+
"import-in-the-middle": "^1.15.0",
|
|
39
|
+
"require-in-the-middle": "^7.5.2"
|
|
40
|
+
},
|
|
41
|
+
"peerDependencies": {
|
|
42
|
+
"@langchain/core": ">=1.0.0 <2.0.0"
|
|
43
|
+
},
|
|
44
|
+
"peerDependenciesMeta": {
|
|
45
|
+
"@langchain/core": {
|
|
46
|
+
"optional": true
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
}
|