Skip to content
Cloudflare Docs
非官方翻译 - 此文档为非官方中文翻译版本，仅供参考。如有疑问请以 英文官方文档 为准。

HTTP 和服务器发送事件

Agents SDK 允许您处理 HTTP 请求，并原生支持服务器发送事件 ↗（SSE）。这允许您构建可以将数据推送到客户端并避免缓冲的应用程序。

处理 HTTP 请求

Agents 可以使用 onRequest 方法处理 HTTP 请求，该方法在 Agent 实例接收到 HTTP 请求时被调用。该方法将 Request 对象作为参数并返回 Response 对象。

class MyAgent extends Agent {
  // 处理来到此 Agent 实例的 HTTP 请求
  // 返回 Response 对象
  async onRequest(request) {
    return new Response("来自 Agent 的问候！");
  }


  async callAIModel(prompt) {
    // 在这里实现 AI 模型调用
  }
}

查看 Agents API 参考了解更多关于 Agent 类及其方法的信息。

实现服务器发送事件

Agents SDK 直接支持服务器发送事件：您可以使用 SSE 通过长时间运行的连接将数据流式传输回客户端。这避免了缓冲大型响应，这既可能使您的 Agent 感觉缓慢，又迫使您在内存中缓冲整个响应。

当 Agent 部署到 Cloudflare Workers 时，对于将响应流式传输回去的总时间没有有效限制：需要几分钟推理然后响应的大型 AI 模型响应不会被过早终止。

请注意，这并不意味着客户端在流式传输过程中不能潜在地断开连接：您可以通过写入 Agent 的有状态存储和/或使用 WebSockets来解决这个问题。因为您总是可以路由到同一个 Agent，所以您不需要使用集中式会话存储来在客户端断开连接时从中断的地方继续。

以下示例使用 AI SDK 生成文本并将其流式传输回客户端。它将在模型生成时自动将响应流式传输回客户端：

import {
  Agent,
  AgentNamespace,
  getAgentByName,
  routeAgentRequest,
} from "agents";
import { streamText } from "ai";
import { createOpenAI, openai } from "@ai-sdk/openai";


export class MyAgent extends Agent {
  async onRequest(request) {
    // 通过以下方式测试：
    // curl -d '{"prompt": "为我写一个 Cloudflare Worker"}' <url>
    let data = await request.json();
    let stream = await this.callAIModel(data.prompt);
    // 这使用服务器发送事件（SSE）
    return stream.toTextStreamResponse({
      headers: {
        "Content-Type": "text/x-unknown",
        "content-encoding": "identity",
        "transfer-encoding": "chunked",
      },
    });
  }


  async callAIModel(prompt) {
    const openai = createOpenAI({
      apiKey: this.env.OPENAI_API_KEY,
    });


    return streamText({
      model: openai("gpt-4o"),
      prompt: prompt,
    });
  }
}


export default {
  async fetch(request, env) {
    let agentId = new URL(request.url).searchParams.get("agent-id") || "";
    const agent = await getAgentByName(env.MyAgent, agentId);
    return agent.fetch(request);
  },
};

WebSockets 与服务器发送事件

WebSockets 和服务器发送事件（SSE）都能够在客户端和 Agents 之间进行实时通信。基于 Agents SDK 构建的 Agents 可以直接公开 WebSocket 和 SSE 端点。

  • WebSockets 提供全双工通信，允许数据同时在两个方向流动。SSE 仅支持服务器到客户端的通信，如果客户端需要向服务器发送数据，需要额外的 HTTP 请求。
  • WebSockets 建立一个在会话期间保持开放的单一持久连接。基于 HTTP 构建的 SSE 可能由于重新连接尝试和每次重新连接时的头部传输而经历更多开销，特别是当有大量客户端-服务器通信时。
  • 虽然 SSE 对于简单的流式传输场景效果很好，但 WebSockets 更适合需要几分钟或几小时连接时间的应用程序，因为它们通过内置的 ping/pong 机制维护更稳定的连接以保持连接活跃。
  • WebSockets 使用自己的协议（ws:// 或 wss://），在初始握手后与 HTTP 分离。这种分离允许 WebSockets 更好地处理二进制数据传输并为专门用例实现自定义子协议。

如果您不确定哪种更适合您的用例，我们推荐 WebSockets。WebSockets API 文档提供了有关如何在 Agents SDK 中使用 WebSockets 的详细信息。

下一步