concevent-ai-agent-sdk 1.0.5 → 2.0.0

package/README.md

@@ -13,6 +13,9 @@ A framework-agnostic AI Agent SDK for building intelligent conversational agents
 - ⛔ **Abort Support** - Cancel ongoing requests with AbortController
 - 🔄 **Retry Logic** - Built-in retry mechanism for resilient operations
 - 📝 **Reasoning Support** - Access model reasoning/thinking outputs
+- 🔌 **Middleware System** - Extensible plugin architecture for logging, sanitization, and more
+- 📋 **Structured Output** - JSON schema validation with Zod for type-safe responses
+- 🎭 **Multi-Agent Orchestration** - Route tasks to specialized sub-agents based on their capabilities
 
 ## Installation
 
@@ -89,7 +92,11 @@ console.log(result.message);
   - [Parallel Tool Execution](#parallel-tool-execution)
   - [Conversation Summarization](#conversation-summarization)
   - [Error Handling](#error-handling)
+  - [Retry Configuration](#retry-configuration)
+  - [Structured Output](#structured-output)
   - [Abort Requests](#abort-requests)
+  - [Middleware](#middleware)
+  - [Multi-Agent Orchestration](#multi-agent-orchestration)
 
 ---
 
@@ -140,6 +147,9 @@ const agent = createAgent(config: AgentConfig): Agent;
 | `summarization`   | `SummarizationConfig`         | ❌       | `{ enabled: true }` | Summarization settings                                   |
 | `parallelToolExecution` | `ParallelExecutionConfig` | ❌    | `{ maxConcurrency: 5 }` | Parallel tool execution settings                     |
 | `errorMessages`   | `ErrorMessages`               | ❌       | Default messages    | Custom error messages                                    |
+| `retry`           | `RetryConfig`                 | ❌       | `{ maxAttempts: 3 }` | Retry configuration for API failures and validation retries |
+| `responseFormat`  | `ResponseFormatConfig`        | ❌       | `undefined` (text)  | Structured output format (text, json_object, json_schema) |
+| `middleware`      | `Middleware[]`                | ❌       | `[]`                | Middleware array for intercepting agent behavior         |
 
 #### SummarizationConfig
 
@@ -159,6 +169,31 @@ interface ParallelExecutionConfig {
 }
 ```
 
+#### RetryConfig
+
+```typescript
+interface RetryConfig {
+  maxAttempts?: number;      // Default: 3 - Total attempts including initial (also used for validation retries)
+  baseDelayMs?: number;      // Default: 1000 - Initial delay before first retry
+  maxDelayMs?: number;       // Default: 30000 - Maximum delay cap
+  backoffMultiplier?: number; // Default: 2 - Exponential backoff multiplier
+}
+```
+
+#### ResponseFormatConfig
+
+```typescript
+type ResponseFormatConfig =
+  | { type: 'text' }                        // Default free-form text
+  | { type: 'json_object' }                 // JSON without validation
+  | {
+      type: 'json_schema';
+      schema: ZodType<unknown>;             // Zod schema for validation
+      name?: string;                        // Schema name (default: 'response')
+      strict?: boolean;                     // Strict mode (default: true)
+    };
+```
+
 #### Example with Full Configuration
 
 ```typescript
@@ -231,8 +266,9 @@ const result = await agent.chat(
 **Returns:** `AgentResult`
 
 ```typescript
-interface AgentResult {
+interface AgentResult<T = unknown> {
   message: string; // Final response message
+  parsedResponse?: T; // Parsed/validated response (when using json_schema)
   reasoning?: {
     // Model's reasoning (if available)
     text?: string;
@@ -429,6 +465,7 @@ interface AgentCallbacks {
   onSummarizationStart?: (originalMessageCount: number) => void;
   onSummarizationEnd?: (summary: string, tokensEstimate: number) => void;
   onIterationStart?: (iteration: number, maxIterations: number) => void;
+  onRetry?: (attempt: number, maxAttempts: number, error: Error, delayMs: number) => void;
   onError?: (error: {
     code: string;
     message: string;
@@ -907,7 +944,7 @@ await agent.chat("Do something", context, {
 | ----------------------- | --------------------------- | ----------- |
 | `API_KEY_REQUIRED`      | API key not provided        | No          |
 | `MODEL_REQUIRED`        | Model name not provided     | No          |
-| `EMPTY_RESPONSE`        | API returned empty response | No          |
+| `EMPTY_RESPONSE`        | API returned empty response | Yes         |
 | `REQUEST_ABORTED`       | Request was aborted         | No          |
 | `NO_RESPONSE`           | No response from API        | No          |
 | `NO_RESPONSE_MESSAGE`   | Response missing message    | No          |
@@ -916,6 +953,181 @@ await agent.chat("Do something", context, {
 | `SUMMARIZATION_FAILED`  | Summarization failed        | Yes         |
 | `GENERIC_ERROR`         | Unknown error occurred      | No          |
 
+### Retry Configuration
+
+The SDK includes automatic retry logic with exponential backoff and jitter for handling transient API failures (e.g., rate limits, network errors).
+
+#### Configuration
+
+```typescript
+const agent = createAgent({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "anthropic/claude-3.5-sonnet",
+  systemPrompts: ["You are a helpful assistant."],
+  tools: [],
+  retry: {
+    maxAttempts: 5,        // Total attempts including initial (default: 3)
+    baseDelayMs: 1000,     // Initial delay before first retry (default: 1000)
+    maxDelayMs: 30000,     // Maximum delay cap (default: 30000)
+    backoffMultiplier: 2,  // Exponential multiplier (default: 2)
+  },
+});
+```
+
+#### How It Works
+
+1. **Exponential Backoff**: Delay doubles with each retry attempt
+2. **Jitter**: Random ±25% variation prevents thundering herd problems
+3. **Retry-After Support**: Honors server-provided `Retry-After` headers
+4. **Abort Integration**: Respects abort signals during retry delays
+
+**Delay Calculation:**
+```
+delay = min(baseDelayMs * (backoffMultiplier ^ attempt), maxDelayMs) * jitter
+```
+
+For example, with defaults (base=1000ms, multiplier=2, max=30000ms):
+- Retry 1: ~1000ms (±250ms jitter)
+- Retry 2: ~2000ms (±500ms jitter)
+- Retry 3: ~4000ms (±1000ms jitter)
+
+#### Retry Callback
+
+Monitor retry attempts using the `onRetry` callback:
+
+```typescript
+await agent.chat("Hello", context, {
+  onRetry: (attempt, maxAttempts, error, delayMs) => {
+    console.log(`Retry ${attempt}/${maxAttempts} after ${delayMs}ms`);
+    console.log(`Error: ${error.message}`);
+  },
+});
+```
+
+#### Retryable Errors
+
+The following HTTP status codes trigger automatic retries:
+- `408` - Request Timeout
+- `429` - Too Many Requests (Rate Limited)
+- `500` - Internal Server Error
+- `502` - Bad Gateway
+- `503` - Service Unavailable
+- `504` - Gateway Timeout
+
+### Structured Output
+
+The SDK supports structured JSON output with automatic Zod schema validation. This ensures type-safe responses from the AI model.
+
+#### Response Format Types
+
+| Type | Description | Validation |
+|------|-------------|------------|
+| `text` | Default free-form text response | None |
+| `json_object` | Forces JSON response | JSON parsing only |
+| `json_schema` | Forces JSON with schema validation | Zod schema validation |
+
+#### Basic JSON Mode
+
+Force the model to return valid JSON without schema validation:
+
+```typescript
+const agent = createAgent({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "anthropic/claude-3.5-sonnet",
+  systemPrompts: ["Return responses as JSON objects."],
+  tools: [],
+  responseFormat: { type: "json_object" },
+});
+
+const result = await agent.chat("List 3 colors", context);
+// result.message: '{"colors": ["red", "blue", "green"]}'
+```
+
+#### Schema-Validated JSON
+
+Define a Zod schema for type-safe, validated responses:
+
+```typescript
+import { z } from "zod";
+
+// Define the expected response structure
+const WeatherSchema = z.object({
+  location: z.string(),
+  temperature: z.number(),
+  unit: z.enum(["celsius", "fahrenheit"]),
+  conditions: z.array(z.string()),
+});
+
+type WeatherResponse = z.infer<typeof WeatherSchema>;
+
+const agent = createAgent({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "anthropic/claude-3.5-sonnet",
+  systemPrompts: ["You provide weather information."],
+  tools: [],
+  responseFormat: {
+    type: "json_schema",
+    schema: WeatherSchema,
+    name: "WeatherResponse",  // Optional: schema name for API
+    strict: true,             // Optional: strict mode (default: true)
+  },
+});
+
+const result = await agent.chat("Weather in Tokyo", context);
+
+// Access typed, validated response
+const weather = result.parsedResponse as WeatherResponse;
+console.log(weather.temperature); // Typed as number
+console.log(weather.conditions);  // Typed as string[]
+```
+
+#### Validation Retries
+
+When schema validation fails, the SDK can automatically retry with error feedback. This uses the same `retry` configuration as API failures:
+
+```typescript
+const agent = createAgent({
+  // ... config
+  responseFormat: {
+    type: "json_schema",
+    schema: MySchema,
+  },
+  retry: { maxAttempts: 3 }, // 3 total attempts (2 validation retries)
+});
+```
+
+When validation fails:
+1. The SDK captures the Zod validation error
+2. Sends the error details back to the model as feedback
+3. Model attempts to generate a corrected response
+4. Process repeats until validation passes or retries exhausted
+
+#### Custom Error Messages
+
+Customize validation error messages:
+
+```typescript
+const agent = createAgent({
+  // ... config
+  errorMessages: {
+    jsonParseError: "Failed to parse JSON response",
+    responseSchemaValidationFailed: "Response didn't match expected format",
+  },
+});
+```
+
+#### AgentResult with Parsed Response
+
+When using `json_schema` format, `AgentResult` includes the validated data:
+
+```typescript
+interface AgentResult<T = unknown> {
+  message: string;        // Raw JSON string
+  parsedResponse?: T;     // Parsed & validated object (only with json_schema)
+  // ... other fields
+}
+```
+
 ### Abort Requests
 
 Cancel ongoing requests using the abort functionality.
@@ -1030,6 +1242,288 @@ async function sendMessage(message: string) {
 
 > **Note:** The SDK handles summarization automatically when context limits are approached. The summarized history is included in `result.conversationHistory`, so clients always receive the properly managed history state.
 
+### Middleware
+
+Middleware allows you to intercept and modify the agent's execution flow at key points. Use middleware for logging, analytics, rate limiting, input sanitization, and output filtering.
+
+#### Middleware Interface
+
+```typescript
+import type { Middleware } from "concevent-ai-agent-sdk";
+
+interface Middleware {
+  name: string;
+  beforeChat?: (ctx: BeforeChatContext) => Promise<string>;
+  afterChat?: (ctx: AfterChatContext) => Promise<AgentResult>;
+  beforeToolCall?: (ctx: BeforeToolCallContext) => Promise<ToolCall>;
+  afterToolCall?: (ctx: AfterToolCallContext) => Promise<FunctionCallResult>;
+  onError?: (ctx: ErrorContext) => Promise<void>;
+}
+```
+
+#### Middleware Hooks
+
+| Hook | When Called | Can Modify |
+|------|-------------|------------|
+| `beforeChat` | Before chat processing begins | User message |
+| `afterChat` | After chat completes successfully | AgentResult |
+| `beforeToolCall` | Before each tool executes | ToolCall args |
+| `afterToolCall` | After each tool executes | FunctionCallResult |
+| `onError` | When an error occurs | Observation only |
+
+#### Creating Middleware
+
+```typescript
+import { createAgent } from "concevent-ai-agent-sdk";
+import type { Middleware } from "concevent-ai-agent-sdk";
+
+// Logging middleware
+const loggingMiddleware: Middleware = {
+  name: "logging",
+  beforeChat: async (ctx) => {
+    console.log(`[${new Date().toISOString()}] Chat started:`, ctx.message);
+    return ctx.message;
+  },
+  afterChat: async (ctx) => {
+    console.log(`[${new Date().toISOString()}] Chat completed:`, ctx.result.message);
+    return ctx.result;
+  },
+  beforeToolCall: async (ctx) => {
+    console.log(`[${new Date().toISOString()}] Tool call:`, ctx.toolCall.name);
+    return ctx.toolCall;
+  },
+  onError: async (ctx) => {
+    console.error(`[${new Date().toISOString()}] Error:`, ctx.error.code, ctx.error.message);
+  },
+};
+
+// Input sanitization middleware
+const sanitizationMiddleware: Middleware = {
+  name: "sanitization",
+  beforeChat: async (ctx) => {
+    // Remove potentially harmful content from user input
+    const sanitized = ctx.message.replace(/<script[^>]*>.*?<\/script>/gi, "");
+    return sanitized;
+  },
+};
+
+// Rate limiting middleware
+const rateLimitMiddleware: Middleware = {
+  name: "rate-limit",
+  beforeChat: async (ctx) => {
+    const userId = ctx.toolContext.userId;
+    if (await isRateLimited(userId)) {
+      throw new Error("Rate limit exceeded. Please try again later.");
+    }
+    return ctx.message;
+  },
+};
+
+// Output filtering middleware
+const outputFilterMiddleware: Middleware = {
+  name: "output-filter",
+  afterChat: async (ctx) => {
+    // Remove sensitive data from responses
+    const filteredMessage = ctx.result.message.replace(/\b\d{3}-\d{2}-\d{4}\b/g, "[REDACTED]");
+    return { ...ctx.result, message: filteredMessage };
+  },
+  afterToolCall: async (ctx) => {
+    // Filter sensitive data from tool results
+    if (typeof ctx.result.result === "object" && ctx.result.result !== null) {
+      const filtered = JSON.parse(
+        JSON.stringify(ctx.result.result).replace(/"password":\s*"[^"]*"/g, '"password": "[REDACTED]"')
+      );
+      return { ...ctx.result, result: filtered };
+    }
+    return ctx.result;
+  },
+};
+```
+
+#### Registering Middleware
+
+Middleware is registered via the `middleware` property in `AgentConfig`. Middleware executes in registration order (first in array = first executed).
+
+```typescript
+const agent = createAgent({
+  apiKey: process.env.API_KEY!,
+  model: "anthropic/claude-3.5-sonnet",
+  systemPrompts: ["You are a helpful assistant."],
+  tools: myTools,
+  middleware: [
+    loggingMiddleware,      // Executes first
+    sanitizationMiddleware, // Executes second
+    rateLimitMiddleware,    // Executes third
+    outputFilterMiddleware, // Executes fourth
+  ],
+});
+```
+
+#### Middleware Context
+
+Each middleware hook receives a context object with relevant information:
+
+```typescript
+// BeforeChatContext & AfterChatContext
+interface MiddlewareContext {
+  message: string;              // The user's input message
+  history: ChatMessage[];       // Current conversation history
+  toolContext: ToolExecutorContext; // userId, timezone, abortSignal
+}
+
+// BeforeToolCallContext (extends MiddlewareContext)
+interface BeforeToolCallContext extends MiddlewareContext {
+  toolCall: ToolCall;           // The tool call to be executed
+}
+
+// AfterToolCallContext (extends BeforeToolCallContext)
+interface AfterToolCallContext extends BeforeToolCallContext {
+  result: FunctionCallResult;   // The tool execution result
+}
+
+// AfterChatContext (extends MiddlewareContext)
+interface AfterChatContext extends MiddlewareContext {
+  result: AgentResult;          // The chat result
+}
+
+// ErrorContext (extends MiddlewareContext)
+interface ErrorContext extends MiddlewareContext {
+  error: AgentError;            // The error that occurred
+}
+```
+
+#### Error Handling in Middleware
+
+- If a middleware hook throws an error, the error propagates and stops the chain
+- `onError` hooks are called for observation only and do not affect the error flow
+- Errors in `onError` hooks are logged but do not throw
+
+### Multi-Agent Orchestration
+
+The SDK supports multi-agent orchestration, allowing you to create specialized agents and have an orchestrator agent route tasks to them based on their capabilities.
+
+#### Creating an Orchestrator
+
+```typescript
+import { createAgent, createOrchestratorAgent } from "concevent-ai-agent-sdk";
+import type { AgentDefinition } from "concevent-ai-agent-sdk";
+
+// Create specialized sub-agents
+const codeAgent = createAgent({
+  apiKey: process.env.API_KEY!,
+  model: "anthropic/claude-3.5-sonnet",
+  systemPrompts: ["You are an expert programmer. Write clean, efficient code."],
+  tools: codingTools,
+});
+
+const researchAgent = createAgent({
+  apiKey: process.env.API_KEY!,
+  model: "anthropic/claude-3.5-sonnet",
+  systemPrompts: ["You are a research specialist. Find accurate information."],
+  tools: researchTools,
+});
+
+const dataAgent = createAgent({
+  apiKey: process.env.API_KEY!,
+  model: "anthropic/claude-3.5-sonnet",
+  systemPrompts: ["You are a data analyst. Analyze data and provide insights."],
+  tools: analysisTools,
+});
+
+// Define sub-agents with descriptions
+const subAgents: AgentDefinition[] = [
+  {
+    agent: codeAgent,
+    name: "code_expert",
+    description: "Handles coding tasks: writing, reviewing, and debugging code",
+    parallel: true,  // Can run in parallel with other parallel agents
+  },
+  {
+    agent: researchAgent,
+    name: "researcher",
+    description: "Researches topics, finds documentation, and gathers information",
+    parallel: true,
+  },
+  {
+    agent: dataAgent,
+    name: "data_analyst",
+    description: "Analyzes data, creates visualizations, and provides statistical insights",
+  },
+];
+
+// Create the orchestrator
+const orchestrator = createOrchestratorAgent({
+  apiKey: process.env.API_KEY!,
+  model: "anthropic/claude-3.5-sonnet",
+  systemPrompts: ["Additional instructions for the orchestrator..."],
+  subAgents,
+});
+```
+
+#### Using the Orchestrator
+
+The orchestrator automatically routes requests to appropriate sub-agents:
+
+```typescript
+// The orchestrator decides which sub-agent(s) to use
+const result = await orchestrator.chat(
+  "Research the best sorting algorithms and implement quicksort in TypeScript",
+  { userId: "user-123", timezone: "UTC" },
+  {
+    // Track sub-agent delegation
+    onSubAgentStart: (data) => {
+      console.log(`Delegating to ${data.agentName}: ${data.message}`);
+    },
+    onSubAgentComplete: (data) => {
+      console.log(`${data.agentName} completed in ${data.result.iterations} iterations`);
+    },
+    // Standard callbacks also work
+    onToolCallStart: (calls) => {
+      console.log("Tool calls:", calls.map(c => c.name));
+    },
+  }
+);
+```
+
+#### OrchestratorConfig
+
+| Property        | Type                | Required | Default           | Description                                  |
+|-----------------|---------------------|----------|-------------------|----------------------------------------------|
+| `apiKey`        | `string`            | ✅       | -                 | API key for the orchestrator                 |
+| `model`         | `string`            | ✅       | -                 | Model for the orchestrator                   |
+| `systemPrompts` | `string[]`          | ✅       | -                 | Additional prompts (orchestrator prompt auto-injected) |
+| `subAgents`     | `AgentDefinition[]` | ✅       | -                 | Array of sub-agent definitions               |
+| *(other)*       | -                   | -        | Same as AgentConfig | All other AgentConfig options except `tools` |
+
+#### AgentDefinition
+
+```typescript
+interface AgentDefinition {
+  agent: Agent;           // The agent instance
+  name: string;           // Unique name (used as tool name)
+  description: string;    // Describes capabilities (helps routing)
+  parallel?: boolean;     // Can run in parallel (default: false)
+}
+```
+
+#### OrchestratorAgent Interface
+
+```typescript
+interface OrchestratorAgent extends Agent {
+  getSubAgents(): AgentDefinition[];  // Returns registered sub-agents
+}
+```
+
+#### Key Concepts
+
+1. **Stateless Delegation**: Sub-agents have their history cleared before each delegation. The orchestrator must include all necessary context in the delegated message.
+
+2. **Parallel Execution**: Sub-agents marked with `parallel: true` can be called concurrently when the orchestrator needs multiple specialists.
+
+3. **No Nested Orchestrators**: Sub-agents cannot themselves be orchestrators. This prevents infinite delegation loops.
+
+4. **Automatic Routing**: The orchestrator's LLM decides which sub-agent(s) to use based on their descriptions and the user's request.
+
 ---
 
 ## Exports Summary
@@ -1039,6 +1533,7 @@ async function sendMessage(message: string) {
 ```typescript
 // Functions
 export { createAgent } from "./core/agent";
+export { createOrchestratorAgent } from "./core/orchestrator";
 export { createEvent } from "./types/events";
 
 // Constants
@@ -1053,6 +1548,8 @@ export type {
   ToolExecutorContext,
   ToolDefinition,
   AgentConfig,
+  ParallelExecutionConfig,
+  RetryConfig,
   UsageMetadata,
   AgentResult,
   ToolCallStartData,
@@ -1061,11 +1558,28 @@ export type {
   AgentEventType,
   ThinkingEventData,
   UsageUpdateEventData,
+  RetryEventData,
   ErrorEventData,
   CompleteEventData,
   MessageDeltaEventData,
   ReasoningDeltaEventData,
   AgentEvent,
+  ResponseFormatConfig,
+  // Middleware types
+  Middleware,
+  MiddlewareContext,
+  BeforeChatContext,
+  AfterChatContext,
+  BeforeToolCallContext,
+  AfterToolCallContext,
+  ErrorContext,
+  // Orchestrator types
+  AgentDefinition,
+  OrchestratorConfig,
+  OrchestratorAgent,
+  SubAgentStartData,
+  SubAgentCompleteData,
+  OrchestratorCallbacks,
 } from "./types";
 ```
 

package/dist/core/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,aAAa,EAEd,MAAM,mBAAmB,CAAC;AA8C3B,MAAM,WAAW,KAAK;IACpB,IAAI,CACF,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB,EAC5B,SAAS,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,WAAW,CAAC,CAAC;IACxB,KAAK,IAAI,IAAI,CAAC;IACd,UAAU,IAAI,WAAW,EAAE,CAAC;IAC5B,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACzC,YAAY,IAAI,IAAI,CAAC;IACrB,aAAa,IAAI,aAAa,CAAC;CAChC;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CA8jBtD"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,aAAa,EAId,MAAM,mBAAmB,CAAC;AAqD3B,MAAM,WAAW,KAAK;IACpB,IAAI,CACF,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB,EAC5B,SAAS,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,WAAW,CAAC,CAAC;IACxB,KAAK,IAAI,IAAI,CAAC;IACd,UAAU,IAAI,WAAW,EAAE,CAAC;IAC5B,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IACzC,YAAY,IAAI,IAAI,CAAC;IACrB,aAAa,IAAI,aAAa,CAAC;CAChC;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CA8pBtD"}