agents 0.0.0-07086ea

package/README.md

@@ -0,0 +1,428 @@
+### 🧠 `agents` - A Framework for Digital Intelligence
+
+![agents-header](https://github.com/user-attachments/assets/f6d99eeb-1803-4495-9c5e-3cf07a37b402)
+
+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.
+
+_This project is in active development. Join us in shaping the future of intelligent agents._
+
+#### The Nature of Agents
+
+An AI agent transcends traditional software boundaries. It's an entity that:
+
+- **Persistence**: Maintains its state and knowledge across time
+- **Agency**: Acts autonomously within its defined purpose
+- **Connection**: Communicates through multiple channels with both humans and other agents
+- **Growth**: Learns and adapts through its interactions
+
+Built on Cloudflare's global network, this framework provides agents with a reliable, distributed foundation where they can operate continuously and effectively.
+
+#### 💫 Core Principles
+
+1. **Stateful Existence**: Each agent maintains its own persistent reality
+2. **Long-lived Presence**: Agents can run for extended periods, resting when idle
+3. **Natural Communication**: Interact through HTTP, WebSockets, or direct calls
+4. **Global Distribution**: Leverage Cloudflare's network for worldwide presence
+5. **Resource Harmony**: Efficient hibernation and awakening as needed
+
+---
+
+### 🌱 Beginning the Journey
+
+Start with a complete environment:
+
+```sh
+# Create a new project
+npm create cloudflare@latest -- --template cloudflare/agents-starter
+
+# Or enhance an existing one
+npm install agents
+```
+
+### 📝 Your First Agent
+
+Create an agent that bridges thought and action:
+
+```ts
+import { Agent } from "agents";
+
+export class IntelligentAgent extends Agent {
+  async onRequest(request) {
+    // Transform intention into response
+    return new Response("Ready to assist.");
+  }
+}
+```
+
+### 🎭 Patterns of Intelligence
+
+Agents can manifest various forms of understanding:
+
+```ts
+import { Agent } from "agents";
+import { OpenAI } from "openai";
+
+export class AIAgent extends Agent {
+  async onRequest(request) {
+    // Connect with AI capabilities
+    const ai = new OpenAI({
+      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() }],
+    });
+
+    return new Response(response.choices[0].message.content);
+  }
+
+  async processTask(task) {
+    await this.understand(task);
+    await this.act();
+    await this.reflect();
+  }
+}
+```
+
+### 🏰 Creating Space
+
+Define your agent's domain:
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "AIAgent",
+        "class_name": "AIAgent",
+      },
+    ],
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      // Mandatory for the Agent to store state
+      "new_sqlite_classes": ["AIAgent"],
+    },
+  ],
+}
+```
+
+### 🌐 Lifecycle
+
+Bring your agent into being:
+
+```ts
+// Create a new instance
+const id = env.AIAgent.newUniqueId();
+const agent = env.AIAgent.get(id);
+
+// Initialize with purpose
+await agent.processTask({
+  type: "analysis",
+  context: "incoming_data",
+  parameters: initialConfig,
+});
+
+// Or reconnect with an existing one
+const existingAgent = await getAgentByName(env.AIAgent, "data-analyzer");
+```
+
+### 🔄 Paths of Communication
+
+#### HTTP Understanding
+
+Process and respond to direct requests:
+
+```ts
+export class APIAgent extends Agent {
+  async onRequest(request) {
+    const data = await request.json();
+
+    return Response.json({
+      insight: await this.process(data),
+      moment: Date.now(),
+    });
+  }
+}
+```
+
+#### Persistent Connections
+
+Maintain ongoing dialogues through WebSocket:
+
+```ts
+export class DialogueAgent extends Agent {
+  async onConnect(connection) {
+    await this.initiate(connection);
+  }
+
+  async onMessage(connection, message) {
+    const understanding = await this.comprehend(message);
+    await this.respond(connection, understanding);
+  }
+}
+```
+
+#### Client Communion
+
+For direct connection to your agent:
+
+```ts
+import { AgentClient } from "agents/client";
+
+const connection = new AgentClient({
+  agent: "dialogue-agent",
+  name: "insight-seeker",
+});
+
+connection.addEventListener("message", (event) => {
+  console.log("Received:", event.data);
+});
+
+connection.send(
+  JSON.stringify({
+    type: "inquiry",
+    content: "What patterns do you see?",
+  })
+);
+```
+
+#### React Integration
+
+For harmonious integration with React:
+
+```tsx
+import { useAgent } from "agents/react";
+
+function AgentInterface() {
+  const connection = useAgent({
+    agent: "dialogue-agent",
+    name: "insight-seeker",
+    onMessage: (message) => {
+      console.log("Understanding received:", message.data);
+    },
+    onOpen: () => console.log("Connection established"),
+    onClose: () => console.log("Connection closed"),
+  });
+
+  const inquire = () => {
+    connection.send(
+      JSON.stringify({
+        type: "inquiry",
+        content: "What insights have you gathered?",
+      })
+    );
+  };
+
+  return (
+    <div className="agent-interface">
+      <button onClick={inquire}>Seek Understanding</button>
+    </div>
+  );
+}
+```
+
+### 🌊 Flow of State
+
+Maintain and evolve your agent's understanding:
+
+```ts
+export class ThinkingAgent extends Agent {
+  async evolve(newInsight) {
+    this.setState({
+      ...this.state,
+      insights: [...(this.state.insights || []), newInsight],
+      understanding: this.state.understanding + 1,
+    });
+  }
+
+  onStateUpdate(state, source) {
+    console.log("Understanding deepened:", {
+      newState: state,
+      origin: source,
+    });
+  }
+}
+```
+
+Connect to your agent's state from React:
+
+```tsx
+import { useState } from "react";
+import { useAgent } from "agents/react";
+
+function StateInterface() {
+  const [state, setState] = useState({ counter: 0 });
+
+  const agent = useAgent({
+    agent: "thinking-agent",
+    onStateUpdate: (newState) => setState(newState),
+  });
+
+  const increment = () => {
+    agent.setState({ counter: state.counter + 1 });
+  };
+
+  return (
+    <div>
+      <div>Count: {state.counter}</div>
+      <button onClick={increment}>Increment</button>
+    </div>
+  );
+}
+```
+
+This creates a synchronized state that automatically updates across all connected clients.
+
+### ⏳ Temporal Patterns
+
+Schedule moments of action and reflection:
+
+```ts
+export class TimeAwareAgent extends Agent {
+  async initialize() {
+    // Quick reflection
+    this.schedule(10, "quickInsight", { focus: "patterns" });
+
+    // Daily synthesis
+    this.schedule("0 0 * * *", "dailySynthesis", {
+      depth: "comprehensive",
+    });
+
+    // Milestone review
+    this.schedule(new Date("2024-12-31"), "yearlyAnalysis");
+  }
+
+  async quickInsight(data) {
+    await this.analyze(data.focus);
+  }
+
+  async dailySynthesis(data) {
+    await this.synthesize(data.depth);
+  }
+
+  async yearlyAnalysis() {
+    await this.analyze();
+  }
+}
+```
+
+### 💬 AI Dialogue
+
+Create meaningful conversations with intelligence:
+
+```ts
+import { AIChatAgent } from "agents/ai-chat-agent";
+import { openai } from "@ai-sdk/openai";
+
+export class DialogueAgent extends AIChatAgent {
+  async onChatMessage(onFinish) {
+    return createDataStreamResponse({
+      execute: async (dataStream) => {
+        const stream = streamText({
+          model: openai("gpt-4o"),
+          messages: this.messages,
+          onFinish, // call onFinish so that messages get saved
+        });
+
+        stream.mergeIntoDataStream(dataStream);
+      },
+    });
+  }
+}
+```
+
+#### Creating the Interface
+
+Connect with your agent through a React interface:
+
+```tsx
+import { useAgent } from "agents/react";
+import { useAgentChat } from "agents/ai-react";
+
+function ChatInterface() {
+  // Connect to the agent
+  const agent = useAgent({
+    agent: "dialogue-agent",
+  });
+
+  // Set up the chat interaction
+  const { messages, input, handleInputChange, handleSubmit, clearHistory } =
+    useAgentChat({
+      agent,
+      maxSteps: 5,
+    });
+
+  return (
+    <div className="chat-interface">
+      {/* Message History */}
+      <div className="message-flow">
+        {messages.map((message) => (
+          <div key={message.id} className="message">
+            <div className="role">{message.role}</div>
+            <div className="content">{message.content}</div>
+          </div>
+        ))}
+      </div>
+
+      {/* Input Area */}
+      <form onSubmit={handleSubmit} className="input-area">
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Type your message..."
+          className="message-input"
+        />
+      </form>
+
+      <button onClick={clearHistory} className="clear-button">
+        Clear Chat
+      </button>
+    </div>
+  );
+}
+```
+
+This creates:
+
+- Real-time message streaming
+- Simple message history
+- Intuitive input handling
+- Easy conversation reset
+
+### 💬 The Path Forward
+
+We're developing new dimensions of agent capability:
+
+#### Enhanced Understanding
+
+- **WebRTC Perception**: Audio and video communication channels
+- **Email Discourse**: Automated email interaction and response
+- **Deep Memory**: Long-term context and relationship understanding
+
+#### Development Insights
+
+- **Evaluation Framework**: Understanding agent effectiveness
+- **Clear Sight**: Deep visibility into agent processes
+- **Private Realms**: Complete self-hosting guide
+
+These capabilities will expand your agents' potential while maintaining their reliability and purpose.
+
+Welcome to the future of intelligent agents. Create something meaningful. 🌟
+
+### Contributing
+
+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.
+
+Small fixes, type bugs, and documentation improvements can be raised directly as PRs.
+
+### License
+
+MIT licensed. See the LICENSE file at the root of this repository for details.

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

@@ -0,0 +1,56 @@
+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";
+
+/**
+ * Extension of Agent with built-in chat capabilities
+ * @template Env Environment type containing bindings
+ */
+declare class AIChatAgent<Env = unknown, State = unknown> extends Agent<
+  Env,
+  State
+> {
+  #private;
+  /** Array of chat messages for the current conversation */
+  messages: Message[];
+  constructor(ctx: AgentContext, env: Env);
+  onMessage(connection: Connection, message: WSMessage): Promise<void>;
+  onRequest(request: Request): Promise<Response>;
+  /**
+   * Handle incoming chat messages and generate a response
+   * @param onFinish Callback to be called when the response is finished
+   * @param options.signal A signal to pass to any child requests which can be used to cancel them
+   * @returns Response to send to the client or undefined
+   */
+  onChatMessage(
+    onFinish: StreamTextOnFinishCallback<ToolSet>,
+    options?: {
+      abortSignal: AbortSignal | undefined;
+    }
+  ): Promise<Response | undefined>;
+  /**
+   * Save messages on the server side and trigger AI response
+   * @param messages Chat messages to save
+   */
+  saveMessages(messages: Message[]): Promise<void>;
+  persistMessages(
+    messages: Message[],
+    excludeBroadcastIds?: string[]
+  ): Promise<void>;
+  /**
+   * When the DO is destroyed, cancel all pending requests
+   */
+  destroy(): Promise<void>;
+}
+
+export { AIChatAgent };

package/dist/ai-chat-agent.js

@@ -0,0 +1,234 @@
+import {
+  Agent
+} from "./chunk-ZRZEISHY.js";
+import "./chunk-WNICV3OI.js";
+import {
+  __privateAdd,
+  __privateGet,
+  __privateMethod,
+  __privateSet
+} from "./chunk-HMLY7DHA.js";
+
+// src/ai-chat-agent.ts
+import { appendResponseMessages } from "ai";
+var decoder = new TextDecoder();
+var _chatMessageAbortControllers, _AIChatAgent_instances, broadcastChatMessage_fn, tryCatch_fn, reply_fn, getAbortSignal_fn, removeAbortController_fn, cancelChatRequest_fn, destroyAbortControllers_fn;
+var AIChatAgent = class extends Agent {
+  constructor(ctx, env) {
+    super(ctx, env);
+    __privateAdd(this, _AIChatAgent_instances);
+    /**
+     * Map of message `id`s to `AbortController`s
+     * useful to propagate request cancellation signals for any external calls made by the agent
+     */
+    __privateAdd(this, _chatMessageAbortControllers);
+    this.sql`create table if not exists cf_ai_chat_agent_messages (
+      id text primary key,
+      message text not null,
+      created_at datetime default current_timestamp
+    )`;
+    this.messages = (this.sql`select * from cf_ai_chat_agent_messages` || []).map((row) => {
+      return JSON.parse(row.message);
+    });
+    __privateSet(this, _chatMessageAbortControllers, /* @__PURE__ */ new Map());
+  }
+  async onMessage(connection, message) {
+    if (typeof message === "string") {
+      let data;
+      try {
+        data = JSON.parse(message);
+      } catch (error) {
+        return;
+      }
+      if (data.type === "cf_agent_use_chat_request" && data.init.method === "POST") {
+        const {
+          method,
+          keepalive,
+          headers,
+          body,
+          // we're reading this
+          redirect,
+          integrity,
+          credentials,
+          mode,
+          referrer,
+          referrerPolicy,
+          window
+          // dispatcher,
+          // duplex
+        } = data.init;
+        const { messages } = JSON.parse(body);
+        __privateMethod(this, _AIChatAgent_instances, broadcastChatMessage_fn).call(this, {
+          type: "cf_agent_chat_messages",
+          messages
+        }, [connection.id]);
+        await this.persistMessages(messages, [connection.id]);
+        const chatMessageId = data.id;
+        const abortSignal = __privateMethod(this, _AIChatAgent_instances, getAbortSignal_fn).call(this, chatMessageId);
+        return __privateMethod(this, _AIChatAgent_instances, tryCatch_fn).call(this, async () => {
+          const response = await this.onChatMessage(
+            async ({ response: response2 }) => {
+              const finalMessages = appendResponseMessages({
+                messages,
+                responseMessages: response2.messages
+              });
+              await this.persistMessages(finalMessages, [connection.id]);
+              __privateMethod(this, _AIChatAgent_instances, removeAbortController_fn).call(this, chatMessageId);
+            },
+            abortSignal ? { abortSignal } : void 0
+          );
+          if (response) {
+            await __privateMethod(this, _AIChatAgent_instances, reply_fn).call(this, data.id, response);
+          }
+        });
+      }
+      if (data.type === "cf_agent_chat_clear") {
+        __privateMethod(this, _AIChatAgent_instances, destroyAbortControllers_fn).call(this);
+        this.sql`delete from cf_ai_chat_agent_messages`;
+        this.messages = [];
+        __privateMethod(this, _AIChatAgent_instances, broadcastChatMessage_fn).call(this, {
+          type: "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") {
+        __privateMethod(this, _AIChatAgent_instances, cancelChatRequest_fn).call(this, data.id);
+      }
+    }
+  }
+  async onRequest(request) {
+    return __privateMethod(this, _AIChatAgent_instances, tryCatch_fn).call(this, () => {
+      const url = new URL(request.url);
+      if (url.pathname.endsWith("/get-messages")) {
+        const messages = (this.sql`select * from cf_ai_chat_agent_messages` || []).map((row) => {
+          return JSON.parse(row.message);
+        });
+        return Response.json(messages);
+      }
+      return super.onRequest(request);
+    });
+  }
+  /**
+   * Handle incoming chat messages and generate a response
+   * @param onFinish Callback to be called when the response is finished
+   * @param options.signal A signal to pass to any child requests which can be used to cancel them
+   * @returns Response to send to the client or undefined
+   */
+  async onChatMessage(onFinish, options) {
+    throw new Error(
+      "recieved a chat message, override onChatMessage and return a Response to send to the client"
+    );
+  }
+  /**
+   * Save messages on the server side and trigger AI response
+   * @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`;
+    for (const message of messages) {
+      this.sql`insert into cf_ai_chat_agent_messages (id, message) values (${message.id},${JSON.stringify(message)})`;
+    }
+    this.messages = messages;
+    __privateMethod(this, _AIChatAgent_instances, broadcastChatMessage_fn).call(this, {
+      type: "cf_agent_chat_messages",
+      messages
+    }, excludeBroadcastIds);
+  }
+  /**
+   * When the DO is destroyed, cancel all pending requests
+   */
+  async destroy() {
+    __privateMethod(this, _AIChatAgent_instances, destroyAbortControllers_fn).call(this);
+    await super.destroy();
+  }
+};
+_chatMessageAbortControllers = new WeakMap();
+_AIChatAgent_instances = new WeakSet();
+broadcastChatMessage_fn = function(message, exclude) {
+  this.broadcast(JSON.stringify(message), exclude);
+};
+tryCatch_fn = async function(fn) {
+  try {
+    return await fn();
+  } catch (e) {
+    throw this.onError(e);
+  }
+};
+reply_fn = async function(id, response) {
+  return __privateMethod(this, _AIChatAgent_instances, tryCatch_fn).call(this, async () => {
+    for await (const chunk of response.body) {
+      const body = decoder.decode(chunk);
+      __privateMethod(this, _AIChatAgent_instances, broadcastChatMessage_fn).call(this, {
+        id,
+        type: "cf_agent_use_chat_response",
+        body,
+        done: false
+      });
+    }
+    __privateMethod(this, _AIChatAgent_instances, broadcastChatMessage_fn).call(this, {
+      id,
+      type: "cf_agent_use_chat_response",
+      body: "",
+      done: true
+    });
+  });
+};
+/**
+ * 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
+ */
+getAbortSignal_fn = function(id) {
+  if (typeof id !== "string") {
+    return void 0;
+  }
+  if (!__privateGet(this, _chatMessageAbortControllers).has(id)) {
+    __privateGet(this, _chatMessageAbortControllers).set(id, new AbortController());
+  }
+  return __privateGet(this, _chatMessageAbortControllers).get(id)?.signal;
+};
+/**
+ * Remove an abort controller from the cache of pending message responses
+ */
+removeAbortController_fn = function(id) {
+  __privateGet(this, _chatMessageAbortControllers).delete(id);
+};
+/**
+ * Propagate an abort signal for any requests associated with the given message id
+ */
+cancelChatRequest_fn = function(id) {
+  if (__privateGet(this, _chatMessageAbortControllers).has(id)) {
+    const abortController = __privateGet(this, _chatMessageAbortControllers).get(id);
+    abortController?.abort();
+  }
+};
+/**
+ * Abort all pending requests and clear the cache of AbortControllers
+ */
+destroyAbortControllers_fn = function() {
+  for (const controller of __privateGet(this, _chatMessageAbortControllers).values()) {
+    controller?.abort();
+  }
+  __privateGet(this, _chatMessageAbortControllers).clear();
+};
+export {
+  AIChatAgent
+};
+//# sourceMappingURL=ai-chat-agent.js.map