agents 0.0.0-f59e6a2 → 0.0.0-f5ccde3

package/README.md

@@ -1,6 +1,6 @@
 ### 🧠 `agents` - A Framework for Digital Intelligence
 
-![agents-header](https://github.com/user-attachments/assets/f6d99eeb-1803-4495-9c5e-3cf07a37b402)
+![npm install agents](../../assets/npm-install-agents.svg)
 
 Welcome to a new chapter in software development, where AI agents persist, think, and act with purpose. The `agents` framework creates an environment where artificial intelligence can flourish - maintaining state, engaging in meaningful interactions, and evolving over time.
 
@@ -66,13 +66,13 @@ export class AIAgent extends Agent {
   async onRequest(request) {
     // Connect with AI capabilities
     const ai = new OpenAI({
-      apiKey: this.env.OPENAI_API_KEY,
+      apiKey: this.env.OPENAI_API_KEY
     });
 
     // Process and understand
     const response = await ai.chat.completions.create({
       model: "gpt-4",
-      messages: [{ role: "user", content: await request.text() }],
+      messages: [{ role: "user", content: await request.text() }]
     });
 
     return new Response(response.choices[0].message.content);
@@ -96,17 +96,17 @@ Define your agent's domain:
     "bindings": [
       {
         "name": "AIAgent",
-        "class_name": "AIAgent",
-      },
-    ],
+        "class_name": "AIAgent"
+      }
+    ]
   },
   "migrations": [
     {
       "tag": "v1",
       // Mandatory for the Agent to store state
-      "new_sqlite_classes": ["AIAgent"],
-    },
-  ],
+      "new_sqlite_classes": ["AIAgent"]
+    }
+  ]
 }
 ```
 
@@ -123,7 +123,7 @@ const agent = env.AIAgent.get(id);
 await agent.processTask({
   type: "analysis",
   context: "incoming_data",
-  parameters: initialConfig,
+  parameters: initialConfig
 });
 
 // Or reconnect with an existing one
@@ -143,7 +143,7 @@ export class APIAgent extends Agent {
 
     return Response.json({
       insight: await this.process(data),
-      moment: Date.now(),
+      moment: Date.now()
     });
   }
 }
@@ -166,7 +166,7 @@ export class DialogueAgent extends Agent {
 }
 ```
 
-#### Client Communion
+#### Client Communication
 
 For direct connection to your agent:
 
@@ -175,7 +175,7 @@ import { AgentClient } from "agents/client";
 
 const connection = new AgentClient({
   agent: "dialogue-agent",
-  name: "insight-seeker",
+  name: "insight-seeker"
 });
 
 connection.addEventListener("message", (event) => {
@@ -185,7 +185,7 @@ connection.addEventListener("message", (event) => {
 connection.send(
   JSON.stringify({
     type: "inquiry",
-    content: "What patterns do you see?",
+    content: "What patterns do you see?"
   })
 );
 ```
@@ -205,14 +205,14 @@ function AgentInterface() {
       console.log("Understanding received:", message.data);
     },
     onOpen: () => console.log("Connection established"),
-    onClose: () => console.log("Connection closed"),
+    onClose: () => console.log("Connection closed")
   });
 
   const inquire = () => {
     connection.send(
       JSON.stringify({
         type: "inquiry",
-        content: "What insights have you gathered?",
+        content: "What insights have you gathered?"
       })
     );
   };
@@ -235,14 +235,14 @@ export class ThinkingAgent extends Agent {
     this.setState({
       ...this.state,
       insights: [...(this.state.insights || []), newInsight],
-      understanding: this.state.understanding + 1,
+      understanding: this.state.understanding + 1
     });
   }
 
   onStateUpdate(state, source) {
     console.log("Understanding deepened:", {
       newState: state,
-      origin: source,
+      origin: source
     });
   }
 }
@@ -259,7 +259,7 @@ function StateInterface() {
 
   const agent = useAgent({
     agent: "thinking-agent",
-    onStateUpdate: (newState) => setState(newState),
+    onStateUpdate: (newState) => setState(newState)
   });
 
   const increment = () => {
@@ -289,7 +289,7 @@ export class TimeAwareAgent extends Agent {
 
     // Daily synthesis
     this.schedule("0 0 * * *", "dailySynthesis", {
-      depth: "comprehensive",
+      depth: "comprehensive"
     });
 
     // Milestone review
@@ -317,24 +317,139 @@ Create meaningful conversations with intelligence:
 ```ts
 import { AIChatAgent } from "agents/ai-chat-agent";
 import { openai } from "@ai-sdk/openai";
+import { streamText, generateText, createDataStreamResponse } from "ai";
 
 export class DialogueAgent extends AIChatAgent {
   async onChatMessage(onFinish) {
+    // Option 1: Streaming responses (recommended for real-time interaction)
     return createDataStreamResponse({
       execute: async (dataStream) => {
         const stream = streamText({
           model: openai("gpt-4o"),
           messages: this.messages,
-          onFinish, // call onFinish so that messages get saved
+          // Optional: onFinish is invoked by the AI SDK when generation completes.
+          // Persistence is handled automatically by AIChatAgent after streaming completes.
+          onFinish
         });
 
         stream.mergeIntoDataStream(dataStream);
-      },
+      }
+    });
+
+    // Option 2: Non-streaming responses (simpler, but no real-time updates)
+    // const result = await generateText({
+    //   model: openai("gpt-4o"),
+    //   messages: this.messages,
+    // });
+    //
+    // // For non-streaming with metadata, use toUIMessage:
+    // const message = result.toUIMessage({
+    //   metadata: {
+    //     model: 'gpt-4o',
+    //     totalTokens: result.usage?.totalTokens,
+    //   }
+    // });
+    //
+    // return new Response(JSON.stringify(message), {
+    //   headers: { 'Content-Type': 'application/json' }
+    // });
+  }
+}
+```
+
+#### Metadata Support
+
+The AI SDK provides native support for message metadata through the `messageMetadata` callback. This allows you to attach custom information to messages at the message level.
+
+##### AIChatAgent Integration
+
+In the context of `AIChatAgent`, you can use metadata like this:
+
+```typescript
+import { AIChatAgent } from "agents/ai-chat-agent";
+import { streamText } from "ai";
+import { openai } from "@ai-sdk/openai";
+
+export class MyAgent extends AIChatAgent<Env> {
+  async onChatMessage(onFinish) {
+    const startTime = Date.now();
+
+    const result = streamText({
+      model: openai("gpt-4o"),
+      messages: this.messages,
+      onFinish
+    });
+
+    return result.toUIMessageStreamResponse({
+      messageMetadata: ({ part }) => {
+        if (part.type === "start") {
+          return {
+            model: "gpt-4o",
+            createdAt: Date.now(),
+            messageCount: this.messages.length
+          };
+        }
+        if (part.type === "finish") {
+          return {
+            responseTime: Date.now() - startTime,
+            totalTokens: part.totalUsage?.totalTokens
+          };
+        }
+      }
     });
   }
 }
 ```
 
+##### Accessing Metadata on the Client
+
+Access metadata through the `message.metadata` property:
+
+```typescript
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+import type { MyUIMessage } from '@/types';
+
+export default function Chat() {
+  const { messages } = useChat<MyUIMessage>({
+    transport: new DefaultChatTransport({
+      api: '/api/chat',
+    }),
+  });
+
+  return (
+    <div>
+      {messages.map(message => (
+        <div key={message.id}>
+          <div>
+            {message.role === 'user' ? 'User: ' : 'AI: '}
+            {message.metadata?.createdAt && (
+              <span className="text-sm text-gray-500">
+                {new Date(message.metadata.createdAt).toLocaleTimeString()}
+              </span>
+            )}
+          </div>
+          {/* Render message content */}
+          {message.parts.map((part, index) =>
+            part.type === 'text' ? <div key={index}>{part.text}</div> : null,
+          )}
+          {/* Display additional metadata */}
+          {message.metadata?.totalTokens && (
+            <div className="text-xs text-gray-400">
+              {message.metadata.totalTokens} tokens
+            </div>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+For more details, see the [AI SDK Message Metadata documentation](https://ai-sdk.dev/docs/ai-sdk-ui/message-metadata).
+
 #### Creating the Interface
 
 Connect with your agent through a React interface:
@@ -346,14 +461,14 @@ import { useAgentChat } from "agents/ai-react";
 function ChatInterface() {
   // Connect to the agent
   const agent = useAgent({
-    agent: "dialogue-agent",
+    agent: "dialogue-agent"
   });
 
   // Set up the chat interaction
   const { messages, input, handleInputChange, handleSubmit, clearHistory } =
     useAgentChat({
       agent,
-      maxSteps: 5,
+      maxSteps: 5
     });
 
   return (
@@ -363,7 +478,14 @@ function ChatInterface() {
         {messages.map((message) => (
           <div key={message.id} className="message">
             <div className="role">{message.role}</div>
-            <div className="content">{message.content}</div>
+            <div className="content">
+              {message.parts.map((part, i) => {
+                if (part.type === "text")
+                  return <span key={i}>{part.text}</span>;
+                // Render other part types (e.g., files, tool calls) as desired
+                return null;
+              })}
+            </div>
           </div>
         ))}
       </div>
@@ -393,6 +515,114 @@ This creates:
 - Intuitive input handling
 - Easy conversation reset
 
+### 🔗 MCP (Model Context Protocol) Integration
+
+Agents can seamlessly integrate with the Model Context Protocol, allowing them to act as both MCP servers (providing tools to AI assistants) and MCP clients (using tools from other services).
+
+#### Creating an MCP Server
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpAgent } from "agents/mcp";
+import { z } from "zod";
+
+type Env = {
+  MyMCP: DurableObjectNamespace<MyMCP>;
+};
+
+type State = { counter: number };
+
+export class MyMCP extends McpAgent<Env, State, {}> {
+  server = new McpServer({
+    name: "Demo",
+    version: "1.0.0"
+  });
+
+  initialState: State = {
+    counter: 1
+  };
+
+  async init() {
+    this.server.resource("counter", "mcp://resource/counter", (uri) => {
+      return {
+        contents: [{ text: String(this.state.counter), uri: uri.href }]
+      };
+    });
+
+    this.server.registerTool(
+      "add",
+      {
+        description: "Add to the counter, stored in the MCP",
+        inputSchema: { a: z.number() }
+      },
+      async ({ a }) => {
+        this.setState({ ...this.state, counter: this.state.counter + a });
+
+        return {
+          content: [
+            {
+              text: String(`Added ${a}, total is now ${this.state.counter}`),
+              type: "text"
+            }
+          ]
+        };
+      }
+    );
+  }
+
+  onStateUpdate(state: State) {
+    console.log({ stateUpdate: state });
+  }
+}
+
+// HTTP Streamable transport (recommended)
+export default MyMCP.serve("/mcp", {
+  binding: "MyMCP"
+});
+
+// Or SSE transport for legacy compatibility
+// export default MyMCP.serveSSE("/mcp", { binding: "MyMCP" });
+```
+
+#### Using MCP Tools
+
+```typescript
+import { MCPClientManager } from "agents/mcp";
+
+const client = new MCPClientManager("my-app", "1.0.0");
+
+// Connect to an MCP server
+await client.connect("https://weather-service.com/mcp", {
+  transport: { type: "streamable-http" }
+});
+
+// Use tools from the server
+const weather = await client.callTool({
+  serverId: "weather-service",
+  name: "getWeather",
+  arguments: { location: "San Francisco" }
+});
+```
+
+#### AI SDK Integration
+
+```typescript
+import { generateText } from "ai";
+
+// Convert MCP tools for AI use
+const result = await generateText({
+  model: openai("gpt-4"),
+  tools: client.getAITools(),
+  prompt: "What's the weather in Tokyo?"
+});
+```
+
+**Transport Options:**
+
+- **Auto**: Automatically determine the correct transport
+- **HTTP Streamable**: Best performance, batch requests, session management
+- **SSE**: Simple setup, legacy compatibility
+
 ### 💬 The Path Forward
 
 We're developing new dimensions of agent capability:
@@ -418,8 +648,8 @@ Welcome to the future of intelligent agents. Create something meaningful. 🌟
 Contributions are welcome, but are especially welcome when:
 
 - You have opened an issue as a Request for Comment (RFC) to discuss your proposal, show your thinking, and iterate together.
-- Is not "AI slop": LLMs are powerful tools, but contributions entirely authored by vibe coding are unlikely to meet the quality bar, and will be rejected.
-- You're willing to accept feedback and make sure the changes fit the goals of the `agents` sdk. Not everything will, and that's OK.
+- Not "AI slop": LLMs are powerful tools, but contributions entirely authored by vibe coding are unlikely to meet the quality bar, and will be rejected.
+- You're willing to accept feedback and make sure the changes fit the goals of the `agents` SDK. Not everything will, and that's OK.
 
 Small fixes, type bugs, and documentation improvements can be raised directly as PRs.
 

package/dist/ai-chat-agent.d.ts

@@ -1,17 +1,12 @@
-import { Agent, AgentContext } from "./index.js";
-import { Message, StreamTextOnFinishCallback, ToolSet } from "ai";
-import { Connection, WSMessage } from "partyserver";
-import "node:async_hooks";
-import "./mcp/client.js";
-import "zod";
-import "@modelcontextprotocol/sdk/types.js";
-import "@modelcontextprotocol/sdk/client/index.js";
-import "@modelcontextprotocol/sdk/client/sse.js";
-import "./mcp/do-oauth-client-provider.js";
-import "@modelcontextprotocol/sdk/client/auth.js";
-import "@modelcontextprotocol/sdk/shared/auth.js";
-import "@modelcontextprotocol/sdk/shared/protocol.js";
+import "./client-CsaP9Irq.js";
+import "./mcp-BwPscEiF.js";
+import "./do-oauth-client-provider-C2CHH5x-.js";
+import "./index-BUle9RiP.js";
+import "./ai-types-81H_-Uxh.js";
+import { n as AgentContext, t as Agent } from "./index-Bx5KK3VJ.js";
+import { StreamTextOnFinishCallback, ToolSet, UIMessage } from "ai";
 
+//#region src/ai-chat-agent.d.ts
 /**
  * Extension of Agent with built-in chat capabilities
  * @template Env Environment type containing bindings
@@ -20,12 +15,92 @@ declare class AIChatAgent<Env = unknown, State = unknown> extends Agent<
   Env,
   State
 > {
-  #private;
+  /**
+   * Map of message `id`s to `AbortController`s
+   * useful to propagate request cancellation signals for any external calls made by the agent
+   */
+  private _chatMessageAbortControllers;
+  /**
+   * Currently active stream ID for resumable streaming.
+   * Stored in memory for quick access; persisted in stream_metadata table.
+   */
+  private _activeStreamId;
+  /**
+   * Request ID associated with the active stream.
+   */
+  private _activeRequestId;
+  /**
+   * Current chunk index for the active stream
+   */
+  private _streamChunkIndex;
+  /**
+   * Buffer for stream chunks pending write to SQLite.
+   * Chunks are batched and flushed when buffer reaches CHUNK_BUFFER_SIZE.
+   */
+  private _chunkBuffer;
+  /**
+   * Lock to prevent concurrent flush operations
+   */
+  private _isFlushingChunks;
+  /**
+   * Timestamp of the last cleanup operation for old streams
+   */
+  private _lastCleanupTime;
   /** Array of chat messages for the current conversation */
-  messages: Message[];
+  messages: UIMessage[];
   constructor(ctx: AgentContext, env: Env);
-  onMessage(connection: Connection, message: WSMessage): Promise<void>;
+  /**
+   * Restore active stream state if the agent was restarted during streaming.
+   * Called during construction to recover any interrupted streams.
+   * Validates stream freshness to avoid sending stale resume notifications.
+   */
+  private _restoreActiveStream;
+  /**
+   * Notify a connection about an active stream that can be resumed.
+   * The client should respond with CF_AGENT_STREAM_RESUME_ACK to receive chunks.
+   * Uses in-memory state for request ID - no extra DB lookup needed.
+   * @param connection - The WebSocket connection to notify
+   */
+  private _notifyStreamResuming;
+  /**
+   * Send stream chunks to a connection after receiving ACK.
+   * @param connection - The WebSocket connection
+   * @param streamId - The stream to replay
+   * @param requestId - The original request ID
+   */
+  private _sendStreamChunks;
+  /**
+   * Buffer a stream chunk for batch write to SQLite.
+   * @param streamId - The stream this chunk belongs to
+   * @param body - The serialized chunk body
+   */
+  private _storeStreamChunk;
+  /**
+   * Flush buffered chunks to SQLite in a single batch.
+   * Uses a lock to prevent concurrent flush operations.
+   */
+  private _flushChunkBuffer;
+  /**
+   * Start tracking a new stream for resumable streaming.
+   * Creates metadata entry in SQLite and sets up tracking state.
+   * @param requestId - The unique ID of the chat request
+   * @returns The generated stream ID
+   */
+  private _startStream;
+  /**
+   * Mark a stream as completed and flush any pending chunks.
+   * @param streamId - The stream to mark as completed
+   */
+  private _completeStream;
+  /**
+   * Clean up old completed streams if enough time has passed since last cleanup.
+   * This prevents database growth while avoiding cleanup overhead on every stream completion.
+   */
+  private _maybeCleanupOldStreams;
+  private _broadcastChatMessage;
+  private _loadMessagesFromDb;
   onRequest(request: Request): Promise<Response>;
+  private _tryCatchChat;
   /**
    * Handle incoming chat messages and generate a response
    * @param onFinish Callback to be called when the response is finished
@@ -39,18 +114,44 @@ declare class AIChatAgent<Env = unknown, State = unknown> extends Agent<
     }
   ): Promise<Response | undefined>;
   /**
-   * Save messages on the server side and trigger AI response
+   * Save messages on the server side
    * @param messages Chat messages to save
    */
-  saveMessages(messages: Message[]): Promise<void>;
+  saveMessages(messages: UIMessage[]): Promise<void>;
   persistMessages(
-    messages: Message[],
+    messages: UIMessage[],
     excludeBroadcastIds?: string[]
   ): Promise<void>;
+  private _reply;
+  /**
+   * Mark a stream as errored and clean up state.
+   * @param streamId - The stream to mark as errored
+   */
+  private _markStreamError;
+  /**
+   * For the given message id, look up its associated AbortController
+   * If the AbortController does not exist, create and store one in memory
+   *
+   * returns the AbortSignal associated with the AbortController
+   */
+  private _getAbortSignal;
+  /**
+   * Remove an abort controller from the cache of pending message responses
+   */
+  private _removeAbortController;
   /**
-   * When the DO is destroyed, cancel all pending requests
+   * Propagate an abort signal for any requests associated with the given message id
+   */
+  private _cancelChatRequest;
+  /**
+   * Abort all pending requests and clear the cache of AbortControllers
+   */
+  private _destroyAbortControllers;
+  /**
+   * When the DO is destroyed, cancel all pending requests and clean up resources
    */
   destroy(): Promise<void>;
 }
-
+//#endregion
 export { AIChatAgent };
+//# sourceMappingURL=ai-chat-agent.d.ts.map