@cloudbase/agent-observability 1.0.1-alpha.9

package/README.md

@@ -0,0 +1,231 @@
+# AG-Kit TypeScript Observability
+
+OpenTelemetry-based observability for AG-Kit with OpenInference semantic conventions.
+
+## Installation
+
+```bash
+# Core package
+npm install @cloudbase/agent-observability
+
+# With LangChain integration
+npm install @cloudbase/agent-observability @langchain/core
+```
+
+## Architecture Overview
+
+This package provides a callback-based observability system that integrates with LangChain/LangGraph through the standard `BaseCallbackHandler` mechanism.
+
+### Core Components
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      AG-Kit Application                          │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │                   Server Layer                            │  │
+│  │  Creates AG-UI.Server span, extracts SpanContext,       │  │
+│  │  propagates via forwardedProps                           │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                              │                                   │
+│                              ▼                                   │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │                 Adapter Layer (LangGraph)                 │  │
+│  │  Restores SpanContext, sets external parent context      │  │
+│  │  in CallbackHandler                                      │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                              │                                   │
+│                              ▼                                   │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │            LangGraph Workflow (streamEvents)              │  │
+│  │  Events flow through patched astream_events              │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                              │                                   │
+│                              ▼                                   │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │              CallbackHandler (BaseCallbackHandler)        │  │
+│  │  on_chain_start, on_llm_start, on_tool_start, etc.       │  │
+│  │  Creates spans with correct parent-child relationships    │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                              │                                   │
+│                              ▼                                   │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │                    OpenTelemetry                          │  │
+│  │  SpanContext propagation, OTLP exporters                  │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Callback Mechanism
+
+The observability system uses LangChain's standard `BaseCallbackHandler` to automatically capture tracing events:
+
+1. **Callback Registration**
+   ```typescript
+   import { CallbackHandler } from '@cloudbase/agent-observability/langchain';
+
+   const handler = new CallbackHandler({
+     adapterName: 'LangGraph'
+   });
+   ```
+
+2. **Span Hierarchy Construction**
+   - Server span created at request entry
+   - SpanContext serialized and passed through `forwardedProps`
+   - Adapter layer restores context and sets external parent
+   - CallbackHandler creates child spans with correct parent relationships
+
+3. **Event Handling**
+   - `on_chain_start`: Creates CHAIN spans (Adapter.LangGraph, nodes)
+   - `on_llm_start`: Creates LLM spans (ChatOpenAI, etc.)
+   - `on_tool_start`: Creates TOOL spans (calculator, etc.)
+   - `on_chain_end` / `on_llm_end` / `on_tool_end`: End spans with duration
+
+## Quick Start
+
+### Basic Span Creation
+
+```typescript
+import { startObservation } from '@cloudbase/agent-observability';
+
+// Create a span
+const span = startObservation(
+  'my-operation',
+  { 'http.method': 'GET' },
+  { asType: 'span' }
+);
+
+// Update and end
+span.update({ 'http.status_code': 200 });
+span.end();
+```
+
+### LangChain Integration
+
+```typescript
+import { CallbackHandler } from '@cloudbase/agent-observability/langchain';
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+
+const handler = CallbackHandler.create({
+  adapterName: 'LangGraph'
+});
+
+// Use with LangChain
+const chain = new LLMChain({ llm, prompt, callbacks: [handler] });
+await chain.invoke({ input: 'Hello' });
+```
+
+### LangGraph Integration
+
+```typescript
+import { CallbackHandler } from '@cloudbase/agent-observability/langchain';
+import { StateGraph } from '@langgraph/langgraph';
+
+const workflow = new StateGraph(StateSchema)
+  .addNode('node_a', nodeA)
+  .addNode('node_b', nodeB)
+  .compile();
+
+// The callback is automatically injected through the agent wrapper
+const agent = new LangGraphAgent({ graph: workflow });
+```
+
+## Span Hierarchy Example
+
+When using LangGraph with AG-Kit server:
+
+```
+AG-UI.Server (Request entry point)
+└─ Adapter.LangGraph (Agent adapter layer)
+        ├─ node_a (LangGraph node)
+        │   └─ ChatOpenAI (LLM call)
+        ├─ node_b (LangGraph node)
+        │   ├─ ChatOpenAI (LLM call)
+        │   └─ calculator (Tool call)
+        └─ synthesizer (LangGraph node)
+            └─ ChatOpenAI (LLM call)
+```
+
+**Internal spans:** LangGraph also emits internal spans like `__start__` and `ChannelWrite<...>` which are tagged with `metadata.tags: ["langsmith:hidden"]`. These can be filtered in visualization tools if desired.
+
+## OpenInference Semantic Conventions
+
+This package follows [OpenInference](https://github.com/Arize-ai/openinference) standards:
+
+| Span Kind | Attribute | Description |
+|-----------|-----------|-------------|
+| `SPAN` | `openinference.span.kind: SPAN` | General operations |
+| `CHAIN` | `openinference.span.kind: CHAIN` | Chain/workflow spans |
+| `LLM` | `openinference.span.kind: LLM` | LLM calls |
+| `TOOL` | `openinference.span.kind: TOOL` | Tool/function calls |
+| `AGENT` | `openinference.span.kind: AGENT` | Agent workflows |
+
+### Key Attributes
+
+- `input.value` / `output.value`: Message content
+- `llm.model_name`: Model identifier
+- `llm.token_count.prompt` / `llm.token_count.completion`: Token usage
+- `tool.name`: Tool function name
+
+## Exporters
+
+### Console (Local Debug)
+
+```typescript
+import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-base';
+import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
+
+provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
+```
+
+### OTLP (Langfuse, etc.)
+
+```typescript
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+
+const exporter = new OTLPTraceExporter({
+  url: 'http://localhost:3000/api/public/otel/v1/traces',
+  headers: {
+    'Authorization': `Basic ${credentials}`
+  }
+});
+```
+
+## API Reference
+
+### Core Functions
+
+- `startObservation(name, attributes, options)`: Create a new span
+- `getActiveTraceId()`: Get current trace ID
+- `getActiveSpanId()`: Get current span ID
+
+### CallbackHandler
+
+```typescript
+interface CallbackHandlerOptions {
+  adapterName: string;           // e.g., 'LangGraph', 'LangChain'
+  traceMetadata?: Record<string, string>;
+  observationCallbacks?: (obs: any) => void;
+}
+```
+
+### Span Types
+
+- `ObservationSpan`: General spans
+- `ObservationLLM`: LLM generation spans
+- `ObservationTool`: Tool invocation spans
+- `ObservationChain`: Chain/workflow spans
+- `ObservationAgent`: Agent spans
+
+## Dependencies
+
+### Peer Dependencies
+
+- `@langchain/core`: For LangChain callback integration
+
+### Dev Dependencies
+
+- `@opentelemetry/sdk-trace-base`: For testing exporters
+- `@opentelemetry/exporter-trace-otlp-http`: For OTLP export

package/dist/chunk-NFEGQTCC.mjs

@@ -0,0 +1,27 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+export {
+  __esm,
+  __export,
+  __toCommonJS
+};
+//# sourceMappingURL=chunk-NFEGQTCC.mjs.map

package/dist/chunk-NFEGQTCC.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}