agents 0.0.0-d40512c → 0.0.0-d72c6a2

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.
 
@@ -166,7 +166,7 @@ export class DialogueAgent extends Agent {
 }
 ```
 
-#### Client Communion
+#### Client Communication
 
 For direct connection to your agent:
 
@@ -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:
@@ -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,112 @@ 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.tool(
+      "add",
+      "Add to the counter, stored in the MCP",
+      { 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 +646,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,15 +1,19 @@
-import { Message, StreamTextOnFinishCallback, ToolSet } from "ai";
-import { A as Agent, a as AgentContext } from "./index-CITGJflw.js";
+import { UIMessage, StreamTextOnFinishCallback, ToolSet } from "ai";
+import { Agent, AgentContext } from "./index.js";
 import { Connection, WSMessage } from "partyserver";
+import "cloudflare:workers";
 import "@modelcontextprotocol/sdk/client/index.js";
 import "@modelcontextprotocol/sdk/types.js";
-import "./mcp/client.js";
+import "./client-CvaJdLQA.js";
 import "zod";
-import "@modelcontextprotocol/sdk/client/sse.js";
 import "@modelcontextprotocol/sdk/shared/protocol.js";
+import "@modelcontextprotocol/sdk/client/sse.js";
+import "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import "./mcp/do-oauth-client-provider.js";
 import "@modelcontextprotocol/sdk/client/auth.js";
 import "@modelcontextprotocol/sdk/shared/auth.js";
+import "./observability/index.js";
+import "./ai-types.js";
 
 /**
  * Extension of Agent with built-in chat capabilities
@@ -25,7 +29,7 @@ declare class AIChatAgent<Env = unknown, State = unknown> extends Agent<
    */
   private _chatMessageAbortControllers;
   /** Array of chat messages for the current conversation */
-  messages: Message[];
+  messages: UIMessage[];
   constructor(ctx: AgentContext, env: Env);
   private _broadcastChatMessage;
   onMessage(connection: Connection, message: WSMessage): Promise<void>;
@@ -44,15 +48,14 @@ 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 _messagesNotAlreadyInAgent;
   private _reply;
   /**
    * For the given message id, look up its associated AbortController

package/dist/ai-chat-agent.js

@@ -1,12 +1,15 @@
+import {
+  autoTransformMessages
+} from "./chunk-UJVEAURM.js";
 import {
   Agent
-} from "./chunk-LU2RSO54.js";
-import "./chunk-4RBEYCWK.js";
-import "./chunk-PVQZBKN7.js";
-import "./chunk-KUH345EY.js";
+} from "./chunk-YDUDMOL6.js";
+import "./chunk-MH46VMM4.js";
+import "./chunk-LL2AFX7V.js";
+import "./chunk-QEVM4BVL.js";
+import "./chunk-AVYJQSLW.js";
 
 // src/ai-chat-agent.ts
-import { appendResponseMessages } from "ai";
 var decoder = new TextDecoder();
 var AIChatAgent = class extends Agent {
   constructor(ctx, env) {
@@ -16,9 +19,10 @@ var AIChatAgent = class extends Agent {
       message text not null,
       created_at datetime default current_timestamp
     )`;
-    this.messages = (this.sql`select * from cf_ai_chat_agent_messages` || []).map((row) => {
+    const rawMessages = (this.sql`select * from cf_ai_chat_agent_messages` || []).map((row) => {
       return JSON.parse(row.message);
     });
+    this.messages = autoTransformMessages(rawMessages);
     this._chatMessageAbortControllers = /* @__PURE__ */ new Map();
   }
   _broadcastChatMessage(message, exclude) {
@@ -32,7 +36,7 @@ var AIChatAgent = class extends Agent {
       } catch (_error) {
         return;
       }
-      if (data.type === "cf_agent_use_chat_request" && data.init.method === "POST") {
+      if (data.type === "cf_agent_use_chat_request" /* CF_AGENT_USE_CHAT_REQUEST */ && data.init.method === "POST") {
         const {
           // method,
           // keepalive,
@@ -45,22 +49,20 @@ var AIChatAgent = class extends Agent {
           // duplex
         } = data.init;
         const { messages } = JSON.parse(body);
+        const transformedMessages = autoTransformMessages(messages);
         this._broadcastChatMessage(
           {
-            messages,
-            type: "cf_agent_chat_messages"
+            messages: transformedMessages,
+            type: "cf_agent_chat_messages" /* CF_AGENT_CHAT_MESSAGES */
           },
           [connection.id]
         );
-        const incomingMessages = this._messagesNotAlreadyInAgent(messages);
-        await this.persistMessages(messages, [connection.id]);
+        await this.persistMessages(transformedMessages, [connection.id]);
         this.observability?.emit(
           {
             displayMessage: "Chat message request",
             id: data.id,
-            payload: {
-              message: incomingMessages
-            },
+            payload: {},
             timestamp: Date.now(),
             type: "message:request"
           },
@@ -70,21 +72,13 @@ var AIChatAgent = class extends Agent {
         const abortSignal = this._getAbortSignal(chatMessageId);
         return this._tryCatchChat(async () => {
           const response = await this.onChatMessage(
-            async ({ response: response2 }) => {
-              const finalMessages = appendResponseMessages({
-                messages,
-                responseMessages: response2.messages
-              });
-              const outgoingMessages = this._messagesNotAlreadyInAgent(finalMessages);
-              await this.persistMessages(finalMessages, [connection.id]);
+            async (_finishResult) => {
               this._removeAbortController(chatMessageId);
               this.observability?.emit(
                 {
                   displayMessage: "Chat message response",
                   id: data.id,
-                  payload: {
-                    message: outgoingMessages
-                  },
+                  payload: {},
                   timestamp: Date.now(),
                   type: "message:response"
                 },
@@ -104,26 +98,27 @@ var AIChatAgent = class extends Agent {
                 body: "No response was generated by the agent.",
                 done: true,
                 id: data.id,
-                type: "cf_agent_use_chat_response"
+                type: "cf_agent_use_chat_response" /* CF_AGENT_USE_CHAT_RESPONSE */
               },
               [connection.id]
             );
           }
         });
       }
-      if (data.type === "cf_agent_chat_clear") {
+      if (data.type === "cf_agent_chat_clear" /* CF_AGENT_CHAT_CLEAR */) {
         this._destroyAbortControllers();
         this.sql`delete from cf_ai_chat_agent_messages`;
         this.messages = [];
         this._broadcastChatMessage(
           {
-            type: "cf_agent_chat_clear"
+            type: "cf_agent_chat_clear" /* CF_AGENT_CHAT_CLEAR */
           },
           [connection.id]
         );
-      } else if (data.type === "cf_agent_chat_messages") {
-        await this.persistMessages(data.messages, [connection.id]);
-      } else if (data.type === "cf_agent_chat_request_cancel") {
+      } else if (data.type === "cf_agent_chat_messages" /* CF_AGENT_CHAT_MESSAGES */) {
+        const transformedMessages = autoTransformMessages(data.messages);
+        await this.persistMessages(transformedMessages, [connection.id]);
+      } else if (data.type === "cf_agent_chat_request_cancel" /* CF_AGENT_CHAT_REQUEST_CANCEL */) {
         this._cancelChatRequest(data.id);
       }
     }
@@ -159,24 +154,11 @@ var AIChatAgent = class extends Agent {
     );
   }
   /**
-   * Save messages on the server side and trigger AI response
+   * Save messages on the server side
    * @param messages Chat messages to save
    */
   async saveMessages(messages) {
     await this.persistMessages(messages);
-    const response = await this.onChatMessage(async ({ response: response2 }) => {
-      const finalMessages = appendResponseMessages({
-        messages,
-        responseMessages: response2.messages
-      });
-      await this.persistMessages(finalMessages, []);
-    });
-    if (response) {
-      for await (const chunk of response.body) {
-        decoder.decode(chunk);
-      }
-      response.body?.cancel();
-    }
   }
   async persistMessages(messages, excludeBroadcastIds = []) {
     this.sql`delete from cf_ai_chat_agent_messages`;
@@ -187,32 +169,141 @@ var AIChatAgent = class extends Agent {
     this._broadcastChatMessage(
       {
         messages,
-        type: "cf_agent_chat_messages"
+        type: "cf_agent_chat_messages" /* CF_AGENT_CHAT_MESSAGES */
       },
       excludeBroadcastIds
     );
   }
-  _messagesNotAlreadyInAgent(messages) {
-    const existingIds = new Set(this.messages.map((message) => message.id));
-    return messages.filter((message) => !existingIds.has(message.id));
-  }
   async _reply(id, response) {
     return this._tryCatchChat(async () => {
-      for await (const chunk of response.body) {
-        const body = decoder.decode(chunk);
+      if (!response.body) {
         this._broadcastChatMessage({
-          body,
-          done: false,
+          body: "",
+          done: true,
           id,
-          type: "cf_agent_use_chat_response"
+          type: "cf_agent_use_chat_response" /* CF_AGENT_USE_CHAT_RESPONSE */
         });
+        return;
       }
-      this._broadcastChatMessage({
-        body: "",
-        done: true,
-        id,
-        type: "cf_agent_use_chat_response"
+      const reader = response.body.getReader();
+      let fullResponseText = "";
+      let fullReasoningText = "";
+      const toolCalls = /* @__PURE__ */ new Map();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) {
+            this._broadcastChatMessage({
+              body: "",
+              done: true,
+              id,
+              type: "cf_agent_use_chat_response" /* CF_AGENT_USE_CHAT_RESPONSE */
+            });
+            break;
+          }
+          const chunk = decoder.decode(value);
+          const contentType = response.headers.get("content-type") || "";
+          const isSSE = contentType.includes("text/event-stream");
+          if (isSSE) {
+            const lines = chunk.split("\n");
+            for (const line of lines) {
+              if (line.startsWith("data: ") && line !== "data: [DONE]") {
+                try {
+                  const data = JSON.parse(line.slice(6));
+                  switch (data.type) {
+                    // SSE event signaling the tool input is ready. We track by
+                    // `toolCallId` so we can persist it as a tool part in the message.
+                    case "tool-input-available": {
+                      const { toolCallId, toolName, input } = data;
+                      toolCalls.set(toolCallId, {
+                        toolCallId,
+                        toolName,
+                        input,
+                        type: toolName ? `tool-${toolName}` : "dynamic-tool",
+                        state: "input-available"
+                      });
+                      break;
+                    }
+                    // SSE event signaling the tool output is ready. We should've
+                    // already received the input in a previous event so an entry
+                    // with `toolCallId` should already be present
+                    case "tool-output-available": {
+                      const { toolCallId, output, isError, errorText } = data;
+                      const toolPart = toolCalls.get(toolCallId);
+                      if (toolPart)
+                        toolCalls.set(toolCallId, {
+                          ...toolPart,
+                          output,
+                          isError,
+                          errorText,
+                          state: "output-available"
+                        });
+                      break;
+                    }
+                    case "error": {
+                      this._broadcastChatMessage({
+                        error: true,
+                        body: data.errorText ?? JSON.stringify(data),
+                        done: false,
+                        id,
+                        type: "cf_agent_use_chat_response" /* CF_AGENT_USE_CHAT_RESPONSE */
+                      });
+                      return;
+                    }
+                    case "reasoning-delta": {
+                      if (data.delta) fullReasoningText += data.delta;
+                      break;
+                    }
+                    case "text-delta": {
+                      if (data.delta) fullResponseText += data.delta;
+                      break;
+                    }
+                  }
+                  this._broadcastChatMessage({
+                    body: JSON.stringify(data),
+                    done: false,
+                    id,
+                    type: "cf_agent_use_chat_response" /* CF_AGENT_USE_CHAT_RESPONSE */
+                  });
+                } catch (_e) {
+                }
+              }
+            }
+          } else {
+            if (chunk.length > 0) {
+              fullResponseText += chunk;
+              this._broadcastChatMessage({
+                body: JSON.stringify({ type: "text-delta", delta: chunk }),
+                done: false,
+                id,
+                type: "cf_agent_use_chat_response" /* CF_AGENT_USE_CHAT_RESPONSE */
+              });
+            }
+          }
+        }
+      } finally {
+        reader.releaseLock();
+      }
+      const messageParts = [];
+      Array.from(toolCalls.values()).forEach((t) => {
+        messageParts.push(t);
       });
+      if (fullReasoningText.trim()) {
+        messageParts.push({ type: "reasoning", text: fullReasoningText });
+      }
+      if (fullResponseText.trim()) {
+        messageParts.push({ type: "text", text: fullResponseText });
+      }
+      if (messageParts.length > 0) {
+        await this.persistMessages([
+          ...this.messages,
+          {
+            id: `assistant_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`,
+            role: "assistant",
+            parts: messageParts
+          }
+        ]);
+      }
     });
   }
   /**