@iqai/adk 0.5.7 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,174 @@
 # @iqai/adk
 
+## 0.6.0
+
+### Minor Changes
+
+- c2f9b02: ## Comprehensive Telemetry System Overhaul
+
+  This release introduces a complete redesign of the telemetry system with extensive features for observability and monitoring.
+
+  ### ✨ New Features
+
+  **Modular Architecture**
+
+  - Refactored from monolithic to service-based design
+  - Separate modules for tracing, metrics, setup, and utilities
+  - Clean `telemetryService` API replacing low-level functions
+
+  **Metrics Support**
+
+  - Full metrics collection with OpenTelemetry SDK
+  - Counters: agent invocations, tool executions, LLM calls
+  - Histograms: duration tracking, token usage (input/output/total)
+  - OTLP HTTP exporter for metrics
+
+  **Privacy Controls**
+
+  - `ADK_CAPTURE_MESSAGE_CONTENT` environment variable
+  - Fine-grained control over sensitive data capture
+  - Disable prompt/completion logging for production
+
+  **Semantic Conventions**
+
+  - OpenTelemetry GenAI conventions (v1.37+)
+  - ADK-specific namespace (`adk.*`) for custom attributes
+  - Standardized attribute names across all spans
+
+  **Enhanced Tracing**
+
+  - Automatic agent invocation tracing with status tracking
+  - Tool execution spans with arguments and results
+  - LLM call tracing with token usage metrics
+  - Async generator support for streaming responses
+
+  **Resource Auto-Detection**
+
+  - Automatic detection of host, OS, and process information
+  - Custom resource attributes support
+  - Service instance identification
+
+  **Configuration**
+
+  - Comprehensive initialization options
+  - Sampling ratio control for production
+  - Configurable metric export intervals
+  - Custom OTLP headers for authentication
+
+  ### 🔧 Breaking Changes
+
+  - `initializeTelemetry()` → `telemetryService.initialize()`
+  - `shutdownTelemetry()` → `telemetryService.shutdown()`
+  - Legacy `telemetry.ts` now wraps new service for backward compatibility
+
+  ### 📊 Integration
+
+  All core components now automatically report metrics:
+
+  - `BaseAgent.runAsyncInternal()`: Agent metrics
+  - `functions.ts`: Tool execution metrics
+  - `base-llm-flow.ts`: LLM token and duration metrics
+
+  ### 📚 Documentation
+
+  - Comprehensive README in `src/telemetry/`
+  - Updated observability example with Jaeger + Langfuse
+  - Practical examples demonstrating all features
+
+  ### 🛠️ Technical Details
+
+  **Dependencies Added**:
+
+  - `@opentelemetry/sdk-metrics@^2.1.0`
+  - `@opentelemetry/exporter-metrics-otlp-http@^0.205.0`
+
+  **Supported Backends**:
+
+  - Jaeger (local development)
+  - Langfuse
+  - Datadog
+  - New Relic
+  - Any OTLP-compatible backend
+
+  This release provides a production-ready observability foundation for AI applications built with ADK.
+
+### Patch Changes
+
+- 7186de5: Fix: Convert Zod schemas to JSON Schema in BasicLlmRequestProcessor
+- 1387333: Improvements to telementry
+
+## Unreleased
+
+### Major Changes
+
+- **BREAKING: Telemetry aligned with OpenTelemetry GenAI Semantic Conventions v1.38.0**
+
+  The ADK telemetry system has been updated to fully comply with the latest OpenTelemetry GenAI semantic conventions. This ensures better interoperability with industry-standard observability platforms and provides richer, more standardized telemetry data.
+
+  **Breaking Changes:**
+
+  - `gen_ai.system` → `gen_ai.provider.name` (automatic provider detection from model names)
+  - `gen_ai.usage.total_tokens` removed (compute client-side: input + output)
+  - `call_llm` operation deprecated in favor of standard `chat`, `text_completion`, `generate_content`
+  - `traceCallback` signature changed: removed unused `targetName` parameter
+
+  **New Features:**
+
+  - Automatic provider detection (OpenAI, Anthropic, Google, AWS Bedrock, Mistral, Groq, Cohere, etc.)
+  - Enhanced LLM attributes: `response.id`, `response.model`, `output.type`, `top_k`, `frequency_penalty`, `presence_penalty`, `stop_sequences`, `seed`
+  - Structured content capture: `system_instructions`, `input.messages`, `output.messages`, `tool.definitions`
+  - Agent ID tracking: `gen_ai.agent.id` for unique agent identification
+  - Tool argument/result capture: `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result`
+  - Standard metrics constants: `gen_ai.client.operation.duration`, `gen_ai.client.token.usage`
+  - Error type tracking: `error.type` attribute for low-cardinality error identification
+
+  **Backward Compatibility:**
+
+  - Deprecated constants are still available but will be removed in v1.0.0
+  - All `adk.*` namespace attributes remain unchanged
+  - Legacy content events preserved for one release cycle
+
+  See [TELEMETRY_MIGRATION.md](./TELEMETRY_MIGRATION.md) for detailed migration guide.
+
+## 0.5.9
+
+### Patch Changes
+
+- 27d6bd9: Refactored MCP sampling parameters to align with the official protocol specification by moving from direct model assertions to the `modelPreferences` hint system.
+
+  - **Protocol Alignment**
+    Removed the invalid `mcpParams.model` type assertion, as the MCP spec does not define a top-level string for the model in sampling requests.
+
+  - **Preference Logic**
+    Implemented support for `modelPreferences.hints`, allowing the server to interpret model suggestions via the `name` property within the hints array.
+
+  - **Resilience**
+    Added optional chaining across the parameter parsing logic to prevent runtime errors when `modelPreferences` or `hints` are undefined.
+
+  - **Fallback Strategy**
+    Established `gemini-2.0-flash` as the default model if the client provides no specific hints or valid preferences.
+
+## 0.5.8
+
+### Patch Changes
+
+- d92892c: - Added aggregated token usage tracking (input, output, total) across agents, nested agents, and LLM generations.
+  - Introduced model usage tracking per agent and invocation for improved model attribution.
+  - Embedded aggregated token and model usage data into Langfuse agent spans and root trace metadata.
+  - Ensured compatibility with nested agents without modifying the existing span hierarchy.
+  - Implemented cleanup of internal token and model tracking maps after each invocation to prevent memory leaks.
+  - Improved event naming with descriptive suffixes (`.function_call`, `.final_response`, `.event`).
+  - Included `finishReason` in event metadata for enhanced execution context and observability.
+- 0ada268: Added full plugin support across the agent lifecycle, enabling interception and extension of agent behavior during execution, model calls, and tool invocations.
+
+  - Integrated plugin manager into `BaseAgent`, giving plugins priority over canonical callbacks.
+  - Added `plugins` configuration to `AgentBuilder` and introduced `withPlugins()` API.
+  - Updated `LlmAgent` and `BaseAgent` flows to run plugin lifecycle hooks (`before/after agent`, `before/after model`, `before/after tool`, error hooks, etc.).
+  - Plugins can now override or modify behavior at multiple stages.
+
+  - Fully backward compatible (optional chaining, canonical callbacks still work).
+  - Enables custom logging, monitoring, request rewriting, caching, rate limiting, and more via plugins.
+
 ## 0.5.7
 
 ### Patch Changes

package/README.md

@@ -1,34 +1,29 @@
 <div align="center">
-
-<img src="https://files.catbox.moe/vumztw.png" alt="ADK TypeScript Logo" width="100" />
-
-<br/>
-
-# @iqai/adk
-
-**The core TypeScript library for building sophisticated AI agents with multi-LLM support, advanced tools, and flexible conversation flows.**
-
-*Production-ready • Multi-Agent Systems • Extensible Architecture*
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/@iqai/adk">
-    <img src="https://img.shields.io/npm/v/@iqai/adk" alt="NPM Version" />
-  </a>
-  <a href="https://www.npmjs.com/package/@iqai/adk">
-    <img src="https://img.shields.io/npm/dm/@iqai/adk" alt="NPM Downloads" />
-  </a>
-  <a href="https://github.com/IQAIcom/adk-ts/blob/main/LICENSE.md">
-    <img src="https://img.shields.io/npm/l/@iqai/adk" alt="License" />
-  </a>
-  <a href="https://github.com/IQAIcom/adk-ts">
-    <img src="https://img.shields.io/github/stars/IQAIcom/adk-ts?style=social" alt="GitHub Stars" />
-  </a>
-</p>
+  <img src="https://files.catbox.moe/vumztw.png" alt="ADK-TS Logo" width="100" />
+  <br/>
+  <h1>@iqai/adk</h1>
+  <b>The core TypeScript library for building sophisticated AI agents with multi-LLM support, advanced tools, and flexible conversation flows.</b>
+  <br/>
+  <i>Production-ready • Multi-Agent Systems • Extensible Architecture</i>
+
+  <p align="center">
+    <a href="https://www.npmjs.com/package/@iqai/adk">
+      <img src="https://img.shields.io/npm/v/@iqai/adk" alt="NPM Version" />
+    </a>
+    <a href="https://www.npmjs.com/package/@iqai/adk">
+      <img src="https://img.shields.io/npm/dm/@iqai/adk" alt="NPM Downloads" />
+    </a>
+    <a href="https://github.com/IQAIcom/adk-ts/blob/main/LICENSE.md">
+      <img src="https://img.shields.io/npm/l/@iqai/adk" alt="License" />
+    </a>
+    <a href="https://github.com/IQAIcom/adk-ts">
+      <img src="https://img.shields.io/github/stars/IQAIcom/adk-ts?style=social" alt="GitHub Stars" />
+    </a>
+  </p>
+</div>
 
 ---
 
-</div>
-
 ## 🌟 Overview
 
 `@iqai/adk` is the core TypeScript library for the Agent Development Kit, providing the foundational tools and abstractions to build sophisticated AI agents. It enables seamless integration with multiple Large Language Models (LLMs), advanced tool usage, and persistent memory capabilities.
@@ -88,7 +83,7 @@ import dotenv from 'dotenv';
 dotenv.config();
 
 // Instantiate the agent
-const myAgent = new Agent({
+const myAgent = new LlmAgent({
   name: "simple_query_assistant",
   model: "gemini-2.5-flash", // Or "gpt-4-turbo", "claude-3-opus"
   description: "A basic assistant to answer questions.",
@@ -229,7 +224,7 @@ class CalculatorTool extends BaseTool {
 }
 
 // Create an agent equipped with the calculator tool
-const mathAgent = new Agent({
+const mathAgent = new LlmAgent({
   name: "math_assistant_agent",
   model: "gpt-4-turbo", // Choose a model proficient with tool usage
   instructions:
@@ -276,7 +271,7 @@ const parallelAnalysis = await AgentBuilder
 ```typescript
 import { Agent, InMemorySessionService } from '@iqai/adk';
 
-const agent = new Agent({
+const agent = new LlmAgent({
   name: "persistent_assistant",
   model: "gpt-4-turbo",
   sessionService: new InMemorySessionService(),