@iqai/adk 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @iqai/adk
 
+## 0.6.3
+
+### Patch Changes
+
+- ad1b38b: Improve tracing with sequential span indices for better observability.
+  - Add span counters to `InvocationContext` for tracking LLM, tool, and agent invocations
+  - Update trace span names to include indices (e.g., `agent_run [my-agent] #1`, `execute_tool [search] #1`, `llm_generate [gpt-4] #1`)
+  - Include app name in invocation span for better traceability
+  - Disable auto instrumentation by default to reduce trace noise
+  - Update telemetry documentation with new span naming conventions
+
+## 0.6.2
+
+### Patch Changes
+
+- 8f2167a: Adds a new suite of default ADK tools and refactors common tooling, including a major upgrade to the Google Search tool.
+  - Introduces a comprehensive set of **default tools** for the ADK (file system, shell, and web utilities) to provide a strong out-of-the-box agent experience.
+  - Adds a new **Tavily-powered web search tool** as part of the default toolset.
+  - Refactors the **Google Search tool** to use the real Google Custom Search API with Axios and Zod-based argument validation.
+  - Improves **type safety** across several common tools by replacing `any` return types with explicit interfaces.
+  - Updates the memory loading tool to return a structured result object.
+
+  This is a **non-breaking feature and refactor** that expands functionality, improves reliability, and strengthens type safety without changing existing APIs.
+
+- f2dfa13: fix: remove unnecessary any type
+- 96e9661: Add Context Caching support for ADK Apps using Gemini 2.0+ models.
+
+  This feature allows agents to reuse extended instructions or large contextual data across requests, reducing token usage and improving performance. Caching behavior is configurable at the App or Agent level via `contextCacheConfig`, with controls for minimum token threshold, cache TTL, and maximum usage intervals.
+
+  All agents within an App can benefit from shared cached context, minimizing redundant data sent to the model while preserving correctness.
+
 ## 0.6.1
 
 ### Patch Changes
@@ -9,7 +40,6 @@
   The PluginManager had several callback methods defined but never invoked, causing plugins implementing guardrails, logging, or error recovery to be silently ignored.
 
   This fix adds the missing calls for:
-
   - `beforeModelCallback` / `afterModelCallback` - intercept LLM requests/responses
   - `onModelErrorCallback` - handle/recover from LLM errors
   - `beforeToolCallback` / `afterToolCallback` - intercept tool execution
@@ -28,52 +58,44 @@
   ### ✨ 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
@@ -81,13 +103,11 @@
   ### 📊 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
@@ -95,12 +115,10 @@
   ### 🛠️ 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
@@ -123,14 +141,12 @@
   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`
@@ -140,7 +156,6 @@
   - 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
@@ -152,7 +167,6 @@
 ### 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.
 
@@ -177,7 +191,6 @@
   - 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.).
@@ -236,7 +249,6 @@
 ### Minor Changes
 
 - 9c8441c: Enhanced CoinGecko MCP server support with remote endpoints
-
   - **Enhanced createMcpConfig function**: Now automatically detects URLs and uses `mcp-remote` for remote MCP endpoints while maintaining backward compatibility with npm packages
   - **Updated McpCoinGecko**: Now uses the remote CoinGecko MCP API endpoint (`https://mcp.api.coingecko.com/mcp`) instead of the npm package
   - **Added McpCoinGeckoPro**: New function for accessing the professional CoinGecko MCP API endpoint (`https://mcp.pro-api.coingecko.com/mcp`) with enhanced features and higher rate limits
@@ -256,7 +268,6 @@
 ### Minor Changes
 
 - c538a1a: feat(adk): align before/after model callback signatures with runtime (single object arg) and wire before/after tool callbacks into tool execution.
-
   - beforeModelCallback/afterModelCallback now receive `{ callbackContext, llmRequest|llmResponse }` to match runtime invocation; removes need for casts in examples.
   - beforeToolCallback/afterToolCallback are now invoked around tool execution; allow argument mutation and result override.
   - tracing updated to include final args and the produced event.
@@ -297,21 +308,17 @@
 ### Patch Changes
 
 - 2da690a: - **Dependency Updates:**
-
   - Upgraded dependencies and devDependencies across multiple packages ensuring compatibility with the latest library versions.
 
   - **Schema Handling:**
-
     - Transitioned schema conversion to use `z.toJSONSchema`, reducing dependencies.
     - Enhanced type safety in the workflow tool's schema handling.
 
   - **Error Reporting and Validation:**
-
     - Improved error messages in `AgentBuilder` for better debugging.
     - Enhanced output validation for LLM.
 
   - **AI SDK and Model Integration:**
-
     - Refined model ID handling in `AiSdkLlm`.
     - Updated field references to align with AI SDK changes.
 
@@ -331,17 +338,14 @@
 ### Minor Changes
 
 - 3561208: ## Features
-
   - Introduced conditional typing for multi-agent responses in `EnhancedRunner`, `BuiltAgent`, and `AgentBuilderWithSchema`. The ask() method now returns appropriate response type based on agent configuration.
   - Improved `AgentBuilder` methods (asSequential, asParallel, and related build methods) for better type propagation and correct return types for multi-agent aggregators.
   - Output schemas can no longer be set directly on multi-agent aggregators. Schemas must now be defined on individual sub-agents.
 
   ## Fixes
-
   - Bugfix in mergeAgentRun that caused incorrect removal of resolved promises.
 
   ## Changes
-
   - `ask()` implementation tailored to aggregate and return per-agent responses for multi-agent setups while maintaining schema validation for single-agent cases.
   - Now, `AgentBuilder` and `BuiltAgent` are being re-exported explicitly from the ADK entrypoint for type preservation in bundled declarations.
 
@@ -392,7 +396,6 @@
   This major enhancement improves the ADK CLI server's agent loading capabilities and adds new features to the core framework:
 
   **CLI Server Improvements:**
-
   - **Modular Architecture**: Refactored monolithic server file into organized modules (`server/index.ts`, `server/routes.ts`, `server/services.ts`, `server/types.ts`)
   - **Enhanced Agent Resolution**: New `resolveAgentExport` method supports multiple export patterns:
     - Direct agent exports: `export const agent = new LlmAgent(...)`
@@ -403,13 +406,11 @@
   - **Improved TypeScript Import Handling**: Better project root detection and module resolution for TypeScript files
 
   **Core Framework Enhancements:**
-
   - **New AgentBuilder Method**: Added `withAgent()` method to directly provide existing agent instances with definition locking to prevent accidental configuration overwrites
   - **Two-Tier Tool Deduplication**: Implemented robust deduplication logic to prevent duplicate function declarations that cause errors with LLM providers (especially Google)
   - **Better Type Safety**: Improved type definitions and replaced `any[]` usage with proper typed interfaces
 
   **Testing & Reliability:**
-
   - **Comprehensive Test Coverage**: New `agent-resolution.test.ts` with extensive fixtures testing various agent export patterns
   - **Multiple Test Fixtures**: Added 6 different agent export pattern examples for validation
   - **Edge Case Handling**: Improved error handling and logging throughout the agent loading pipeline
@@ -419,7 +420,6 @@
 - 1564b7b: Port Python evaluation framework to TypeScript
 
   This change introduces a comprehensive evaluation framework for testing AI agent performance. Key features include:
-
   - **Core evaluation engine** with agent-evaluator and local evaluation service
   - **Built-in evaluators** for response matching, trajectory analysis, LLM-as-judge, and safety checks
   - **Metrics system** with ROUGE scoring and tool trajectory analysis
@@ -552,14 +552,12 @@
   This release introduces integration with Vercel's AI SDK, expanding the platform's capabilities to support a wider range of large language models without requiring manual maintenance of model synchronization.
 
   ## Key Features
-
   - **AI-SDK Integration**: New `AiSdkLlm` class that integrates with Vercel AI SDK, supporting multiple providers (Google, OpenAI, Anthropic)
   - **Tool Calling Support**: Robust tool calling capabilities with automatic transformation of ADK function declarations to AI SDK tool definitions using Zod schemas
   - **Agent Builder Support**: Enhanced agent builder with AI-SDK model support
   - **Example Implementation**: Complete weather agent example demonstrating AI-SDK usage with tool calling
 
   ## Technical Details
-
   - Adds `ai-sdk.ts` model implementation with streaming support
   - Implements message format conversion between ADK and AI SDK formats
   - Supports both streaming and non-streaming model interactions

package/LICENSE.md

@@ -6,4 +6,4 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -50,11 +50,11 @@ npm install @iqai/adk
 ### Simple Example
 
 ```typescript
-import { AgentBuilder } from '@iqai/adk';
+import { AgentBuilder } from "@iqai/adk";
 
-const response = await AgentBuilder
-  .withModel("gpt-4.1")
-  .ask("What is the primary function of an AI agent?");
+const response = await AgentBuilder.withModel("gpt-4.1").ask(
+  "What is the primary function of an AI agent?",
+);
 
 console.log(response);
 ```
@@ -76,8 +76,8 @@ The library uses `dotenv` to load these variables automatically if `dotenv.confi
 Here's a fundamental example of creating and running an agent:
 
 ```typescript
-import { Agent } from '@iqai/adk';
-import dotenv from 'dotenv';
+import { Agent } from "@iqai/adk";
+import dotenv from "dotenv";
 
 // Load environment variables
 dotenv.config();
@@ -87,7 +87,7 @@ 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.",
-  instructions: "You are a helpful AI. Respond clearly and concisely."
+  instructions: "You are a helpful AI. Respond clearly and concisely.",
 });
 
 // Asynchronously run the agent
@@ -97,7 +97,7 @@ async function runQuery() {
     console.log(`User: ${query}`);
 
     const response = await myAgent.run({
-      messages: [{ role: 'user', content: query }]
+      messages: [{ role: "user", content: query }],
     });
 
     console.log(`Agent: ${response.content}`);
@@ -114,15 +114,14 @@ runQuery();
 The `AgentBuilder` provides a fluent interface for creating agents with minimal boilerplate. It's perfect for rapid prototyping and reduces the complexity of agent setup.
 
 ```typescript
-import { AgentBuilder } from '@iqai/adk';
-import dotenv from 'dotenv';
+import { AgentBuilder } from "@iqai/adk";
+import dotenv from "dotenv";
 
 dotenv.config();
 
 // Simple agent creation and execution in one fluent chain
 async function quickQuery() {
-  const response = await AgentBuilder
-    .create("query_assistant")
+  const response = await AgentBuilder.create("query_assistant")
     .withModel("gemini-2.5-flash")
     .withInstruction("You are a helpful AI. Respond clearly and concisely.")
     .ask("What is the capital of France?");
@@ -132,11 +131,14 @@ async function quickQuery() {
 
 // For more complex scenarios, build the agent and get full control
 async function advancedSetup() {
-  const { agent, runner, session } = await AgentBuilder
-    .create("research_assistant")
+  const { agent, runner, session } = await AgentBuilder.create(
+    "research_assistant",
+  )
     .withModel("gpt-4-turbo")
     .withDescription("An advanced research assistant")
-    .withInstruction("You are a research assistant with access to various tools")
+    .withInstruction(
+      "You are a research assistant with access to various tools",
+    )
     .withTools(new GoogleSearchTool(), new FileOperationsTool())
     .withQuickSession("research-app", "researcher-456")
     .build();
@@ -148,15 +150,13 @@ async function advancedSetup() {
 // Specialized agent types for orchestration
 async function createWorkflowAgent() {
   // Sequential execution of multiple agents
-  const workflow = await AgentBuilder
-    .create("data_pipeline")
+  const workflow = await AgentBuilder.create("data_pipeline")
     .asSequential([dataCollector, dataProcessor, dataAnalyzer])
     .withQuickSession("pipeline-app", "admin")
     .build();
 
   // Parallel execution for concurrent tasks
-  const parallelAnalysis = await AgentBuilder
-    .create("multi_analysis")
+  const parallelAnalysis = await AgentBuilder.create("multi_analysis")
     .asParallel([sentimentAnalyzer, topicExtractor, summaryGenerator])
     .build();
 }
@@ -176,8 +176,8 @@ async function createWorkflowAgent() {
 Extend your agent's capabilities by defining and integrating custom tools.
 
 ```typescript
-import { Agent, BaseTool } from '@iqai/adk';
-import dotenv from 'dotenv';
+import { Agent, BaseTool } from "@iqai/adk";
+import dotenv from "dotenv";
 
 dotenv.config();
 
@@ -185,8 +185,9 @@ dotenv.config();
 class CalculatorTool extends BaseTool {
   constructor() {
     super({
-      name: 'calculator',
-      description: 'Performs basic arithmetic operations: add, subtract, multiply, divide.'
+      name: "calculator",
+      description:
+        "Performs basic arithmetic operations: add, subtract, multiply, divide.",
     });
   }
 
@@ -195,30 +196,38 @@ class CalculatorTool extends BaseTool {
       name: this.name,
       description: this.description,
       parameters: {
-        type: 'object',
+        type: "object",
         properties: {
           operation: {
-            type: 'string',
-            enum: ['add', 'subtract', 'multiply', 'divide']
+            type: "string",
+            enum: ["add", "subtract", "multiply", "divide"],
           },
-          operand1: { type: 'number' },
-          operand2: { type: 'number' }
+          operand1: { type: "number" },
+          operand2: { type: "number" },
         },
-        required: ['operation', 'operand1', 'operand2']
-      }
+        required: ["operation", "operand1", "operand2"],
+      },
     };
   }
 
-  async runAsync(args: { operation: string; operand1: number; operand2: number }) {
+  async runAsync(args: {
+    operation: string;
+    operand1: number;
+    operand2: number;
+  }) {
     const { operation, operand1, operand2 } = args;
     switch (operation) {
-      case 'add': return { result: operand1 + operand2 };
-      case 'subtract': return { result: operand1 - operand2 };
-      case 'multiply': return { result: operand1 * operand2 };
-      case 'divide':
-        if (operand2 === 0) return { error: 'Cannot divide by zero.' };
+      case "add":
+        return { result: operand1 + operand2 };
+      case "subtract":
+        return { result: operand1 - operand2 };
+      case "multiply":
+        return { result: operand1 * operand2 };
+      case "divide":
+        if (operand2 === 0) return { error: "Cannot divide by zero." };
         return { result: operand1 / operand2 };
-      default: return { error: `Unknown operation: ${operation}` };
+      default:
+        return { error: `Unknown operation: ${operation}` };
     }
   }
 }
@@ -229,14 +238,12 @@ const mathAgent = new LlmAgent({
   model: "gpt-4-turbo", // Choose a model proficient with tool usage
   instructions:
     "You are a helpful assistant. Use the calculator tool for any mathematical calculations requested.",
-  tools: [new CalculatorTool()]
+  tools: [new CalculatorTool()],
 });
 
 async function performCalculation() {
   const response = await mathAgent.run({
-    messages: [
-      { role: 'user', content: 'What is 15 multiplied by 4?' }
-    ]
+    messages: [{ role: "user", content: "What is 15 multiplied by 4?" }],
   });
   // The response.content will likely include the thought process and the tool's output.
   console.log(JSON.stringify(response, null, 2));
@@ -250,18 +257,16 @@ performCalculation().catch(console.error);
 ### Multi-Agent Systems
 
 ```typescript
-import { AgentBuilder } from '@iqai/adk';
+import { AgentBuilder } from "@iqai/adk";
 
 // Sequential workflow
-const workflow = await AgentBuilder
-  .create("data_pipeline")
+const workflow = await AgentBuilder.create("data_pipeline")
   .asSequential([dataCollector, dataProcessor, dataAnalyzer])
   .withQuickSession("pipeline-app", "admin")
   .build();
 
 // Parallel execution
-const parallelAnalysis = await AgentBuilder
-  .create("multi_analysis")
+const parallelAnalysis = await AgentBuilder.create("multi_analysis")
   .asParallel([sentimentAnalyzer, topicExtractor, summaryGenerator])
   .build();
 ```
@@ -269,32 +274,32 @@ const parallelAnalysis = await AgentBuilder
 ### Memory & Sessions
 
 ```typescript
-import { Agent, InMemorySessionService } from '@iqai/adk';
+import { Agent, InMemorySessionService } from "@iqai/adk";
 
 const agent = new LlmAgent({
   name: "persistent_assistant",
   model: "gpt-4-turbo",
   sessionService: new InMemorySessionService(),
-  instructions: "Remember our conversation history."
+  instructions: "Remember our conversation history.",
 });
 ```
 
 ### Custom Tools
 
 ```typescript
-import { BaseTool } from '@iqai/adk';
+import { BaseTool } from "@iqai/adk";
 
 class WeatherTool extends BaseTool {
   constructor() {
     super({
-      name: 'weather',
-      description: 'Get current weather information'
+      name: "weather",
+      description: "Get current weather information",
     });
   }
 
   async runAsync(args: { location: string }) {
     // Implementation here
-    return { temperature: 72, condition: 'sunny' };
+    return { temperature: 72, condition: "sunny" };
   }
 }
 ```