concevent-ai-agent-sdk 1.0.2 → 1.0.4

package/README.md

@@ -84,6 +84,7 @@ console.log(result.message);
   - [Tool Definitions](#tool-definitions)
   - [Callbacks & Events](#callbacks--events)
   - [Types](#types)
+- [Streaming](#streaming)
 - [Advanced Usage](#advanced-usage)
   - [Conversation Summarization](#conversation-summarization)
   - [Error Handling](#error-handling)
@@ -134,6 +135,7 @@ const agent = createAgent(config: AgentConfig): Agent;
 | `temperature`     | `number`                      | ❌       | `0.1`               | Sampling temperature (0-2)                               |
 | `reasoningEffort` | `'low' \| 'medium' \| 'high'` | ❌       | `'high'`            | Reasoning effort level for supported models              |
 | `maxIterations`   | `number`                      | ❌       | `20`                | Maximum tool execution iterations per chat               |
+| `stream`          | `boolean`                     | ❌       | `true`              | Enable streaming responses with delta callbacks          |
 | `summarization`   | `SummarizationConfig`         | ❌       | `{ enabled: true }` | Summarization settings                                   |
 | `errorMessages`   | `ErrorMessages`               | ❌       | Default messages    | Custom error messages                                    |
 
@@ -408,6 +410,8 @@ interface AgentCallbacks {
       tokenCount?: number;
     }
   ) => void;
+  onMessageDelta?: (delta: string) => void;
+  onReasoningDelta?: (detail: ReasoningDetail) => void;
   onToolCallStart?: (calls: ToolCallStartData[]) => void;
   onToolResult?: (result: ToolResultData) => void;
   onUsageUpdate?: (usage: UsageMetadata) => void;
@@ -424,6 +428,10 @@ interface AgentCallbacks {
 }
 ```
 
+> ⚠️ **Security Note for Browser/Client-Side Usage**
+>
+> When using callbacks in browser environments, be careful not to expose sensitive information. Callbacks like `onToolResult`, `onThinking`, `onSummarizationEnd`, and `onComplete` may contain internal data, tool execution details, or conversation content that should not be logged to the browser console or sent to client-side analytics in production. The SDK does not restrict this by design, as server-side integrations may safely log such data. It is the consumer's responsibility to sanitize or filter callback data before exposing it in client-side contexts.
+
 #### Callback Examples
 
 ```typescript
@@ -441,6 +449,18 @@ await agent.chat("Help me with my task", context, {
     }
   },
 
+  // Called for each chunk of streaming message content
+  onMessageDelta: (delta) => {
+    process.stdout.write(delta); // Real-time output
+  },
+
+  // Called for each chunk of streaming reasoning (for reasoning models)
+  onReasoningDelta: (detail) => {
+    if (detail.text) {
+      process.stdout.write(detail.text);
+    }
+  },
+
   // Called before tool execution starts
   onToolCallStart: (calls) => {
     calls.forEach((call) => {
@@ -586,6 +606,154 @@ interface ToolResultData {
 
 ---
 
+## Streaming
+
+The SDK supports streaming responses by default, providing real-time updates as the model generates content.
+
+### Enabling/Disabling Streaming
+
+Streaming is **enabled by default**. You can disable it in the agent configuration:
+
+```typescript
+const agent = createAgent({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "anthropic/claude-3.5-sonnet",
+  systemPrompts: ["You are a helpful assistant."],
+  tools: [],
+  stream: false, // Disable streaming (default: true)
+});
+```
+
+### Streaming Callbacks
+
+When streaming is enabled, you can use delta callbacks to receive real-time updates:
+
+#### onMessageDelta
+
+Called whenever a new chunk of the message content is received:
+
+```typescript
+await agent.chat("Tell me a story", context, {
+  onMessageDelta: (delta) => {
+    // Append each chunk to your UI in real-time
+    process.stdout.write(delta);
+  },
+  onMessage: (fullMessage) => {
+    // Called when the complete message is ready
+    console.log("\n\nFull message:", fullMessage);
+  },
+});
+```
+
+#### onReasoningDelta
+
+Called whenever a new chunk of model reasoning is received (for models that support reasoning):
+
+```typescript
+await agent.chat("Solve this problem step by step", context, {
+  onReasoningDelta: (detail) => {
+    if (detail.type === "reasoning.text" && detail.text) {
+      // Stream the reasoning/thinking output
+      process.stdout.write(detail.text);
+    }
+  },
+  onThinking: (fullThinking, details) => {
+    // Called when reasoning is complete
+    console.log("\n\nFull reasoning:", fullThinking);
+  },
+});
+```
+
+### Complete Streaming Example
+
+```typescript
+import { createAgent } from "concevent-ai-agent-sdk";
+
+const agent = createAgent({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "anthropic/claude-3.5-sonnet",
+  systemPrompts: ["You are a helpful assistant."],
+  tools: myTools,
+  stream: true, // Enabled by default
+});
+
+let messageBuffer = "";
+let reasoningBuffer = "";
+
+const result = await agent.chat(
+  "Explain quantum computing",
+  { userId: "user-123", timezone: "UTC" },
+  {
+    // Real-time message chunks
+    onMessageDelta: (delta) => {
+      messageBuffer += delta;
+      updateUI(messageBuffer); // Update your UI with partial content
+    },
+
+    // Real-time reasoning chunks (for reasoning models)
+    onReasoningDelta: (detail) => {
+      if (detail.text) {
+        reasoningBuffer += detail.text;
+        updateReasoningUI(reasoningBuffer);
+      }
+    },
+
+    // Tool execution still works with streaming
+    onToolCallStart: (calls) => {
+      showToolIndicator(calls.map((c) => c.name));
+    },
+
+    onToolResult: (result) => {
+      hideToolIndicator(result.functionName);
+    },
+
+    // Final complete message
+    onMessage: (message, reasoning) => {
+      console.log("Complete message received");
+    },
+  }
+);
+```
+
+### Streaming Event Types
+
+The SDK exports event types for building event-driven streaming systems:
+
+```typescript
+import { createEvent } from "concevent-ai-agent-sdk";
+import type {
+  MessageDeltaEventData,
+  ReasoningDeltaEventData,
+} from "concevent-ai-agent-sdk";
+
+// Create typed streaming events
+const messageDeltaEvent = createEvent("message_delta", {
+  delta: "Hello, ",
+});
+
+const reasoningDeltaEvent = createEvent("reasoning_delta", {
+  detail: {
+    type: "reasoning.text",
+    text: "Let me think about this...",
+    format: "text",
+    index: 0,
+  },
+});
+```
+
+### Streaming vs Non-Streaming
+
+| Feature             | Streaming (`stream: true`)              | Non-Streaming (`stream: false`) |
+| ------------------- | --------------------------------------- | ------------------------------- |
+| Message delivery    | Real-time chunks via `onMessageDelta`   | Complete message only           |
+| Reasoning output    | Real-time via `onReasoningDelta`        | Complete reasoning only         |
+| Perceived latency   | Lower (immediate feedback)              | Higher (wait for completion)    |
+| Tool calls          | Fully supported                         | Fully supported                 |
+| Token usage         | Included in final chunk                 | Included in response            |
+| Default             | ✅ Enabled                              | Must explicitly disable         |
+
+---
+
 ## Advanced Usage
 
 ### Conversation Summarization
@@ -726,6 +894,76 @@ agent.chat("Hello", {
 abortController.abort();
 ```
 
+### Serverless / Stateless Deployments
+
+When deploying in serverless environments (e.g., AWS Lambda, Vercel, Cloudflare Workers) or stateless API routes (e.g., Next.js API routes), the agent instance is created fresh for each request. To maintain conversation continuity, **the client must store and forward the conversation history with each request**.
+
+#### Pattern
+
+1. **Client** maintains `conversationHistory` state
+2. **Client** sends the history with each chat request
+3. **Server** creates a fresh agent, restores history via `setHistory()`, processes the message
+4. **Server** returns the result including `conversationHistory`
+5. **Client** updates its local history from the response
+
+#### Server-Side Example (Next.js API Route)
+
+```typescript
+import { createAgent } from "concevent-ai-agent-sdk";
+import type { ChatMessage } from "concevent-ai-agent-sdk";
+
+export async function POST(request: Request) {
+  const { message, conversationHistory = [] } = await request.json();
+
+  const agent = createAgent({
+    apiKey: process.env.API_KEY!,
+    model: "anthropic/claude-3.5-sonnet",
+    systemPrompts: ["You are a helpful assistant."],
+    tools: myTools,
+  });
+
+  // Restore conversation history from the client
+  if (conversationHistory.length > 0) {
+    agent.setHistory(conversationHistory);
+  }
+
+  const result = await agent.chat(message, {
+    userId: "user-123",
+    timezone: "UTC",
+  });
+
+  // Return result - client should use result.conversationHistory for next request
+  return Response.json({
+    message: result.message,
+    conversationHistory: result.conversationHistory,
+  });
+}
+```
+
+#### Client-Side Example
+
+```typescript
+const [conversationHistory, setConversationHistory] = useState<ChatMessage[]>(
+  []
+);
+
+async function sendMessage(message: string) {
+  const response = await fetch("/api/chat", {
+    method: "POST",
+    body: JSON.stringify({ message, conversationHistory }),
+  });
+
+  const result = await response.json();
+
+  // Update local history for the next request
+  setConversationHistory(result.conversationHistory);
+
+  return result.message;
+}
+```
+
+> **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.
+
 ---
 
 ## Exports Summary
@@ -759,6 +997,8 @@ export type {
   UsageUpdateEventData,
   ErrorEventData,
   CompleteEventData,
+  MessageDeltaEventData,
+  ReasoningDeltaEventData,
   AgentEvent,
 } from "./types";
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "concevent-ai-agent-sdk",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Framework-agnostic AI Agent SDK with tool calling, conversation management, and automatic summarization",
   "type": "module",
   "main": "./dist/index.js",