Executando o SDK da Anthropic em Runtimes de Edge

O pacote oficial @anthropic-ai/sdk é construído sobre fetch, então ele roda sem modificações em runtimes de edge como Vercel Edge Functions, Cloudflare Workers e Deno Deploy, não apenas em Node.js. Esta página cobre como configurar o cliente e transmitir respostas corretamente em cada plataforma.

Resumo

Runtimes de edge são ambientes JavaScript leves que rodam próximos à requisição, muitas vezes sem a superfície completa da API do Node.js. Eles não têm fs, net, ou muitos outros built-ins do Node disponíveis.

O @anthropic-ai/sdk evita esse problema porque seu caminho de requisição é construído sobre a API padrão fetch, ReadableStream e AbortController, todos disponíveis em qualquer runtime de edge moderno.

As principais diferenças entre deployments de edge e Node.js são como você lê a chave de API (o acesso a variáveis de ambiente difere por plataforma) e como você retorna uma resposta em stream (handlers de edge tipicamente retornam um objeto Response diretamente em vez de escrever em um http.ServerResponse do Node.js).

Esta página percorre uma Vercel Edge Function (via um Next.js route handler), uma Cloudflare Worker e notas sobre Deno Deploy, cada uma configurando o cliente e transmitindo uma resposta de volta para o chamador.

Timeouts e cancelamento funcionam da mesma forma em edge como em Node.js: passe um AbortSignal para a requisição, ou confie na própria configuração de timeout do SDK, mas lembre-se que a plataforma também impõe seu próprio limite de tempo de execução em cima de qualquer coisa que você configure.

Receita

Cartão de receita de referência rápida, pronto para copiar e colar.

// Funciona identicamente em Node.js, Vercel Edge, Cloudflare Workers e Deno Deploy
import Anthropic from "@anthropic-ai/sdk";
 
const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});
 
const message = await anthropic.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Explique runtimes de edge em um parágrafo." }],
});
 
console.log(message.content);

Quando usar isso:

• Servir respostas Claude de baixa latência de um local próximo ao usuário (Vercel Edge, Cloudflare Workers rodam na edge da rede).
• Fazer deploy em uma plataforma que não suporta o runtime completo do Node.js (Cloudflare Workers, Deno Deploy).
• Transmitir uma resposta de chat diretamente de volta para o navegador sem bufferizar a resposta completa primeiro.
• Manter o tempo de cold-start de uma função serverless baixo; runtimes de edge geralmente iniciam mais rápido que funções Node.js.

Exemplo Funcional

Vercel Edge Function (Next.js route handler)

// app/api/chat/route.ts
import Anthropic from "@anthropic-ai/sdk";
 
export const runtime = "edge";
 
const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});
 
export async function POST(req: Request) {
  const { prompt } = await req.json();
 
  const stream = await anthropic.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: prompt }],
    stream: true,
  });
 
  const encoder = new TextEncoder();
 
  const body = new ReadableStream({
    async start(controller) {
      for await (const event of stream) {
        if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
          controller.enqueue(encoder.encode(event.delta.text));
        }
      }
      controller.close();
    },
  });
 
  return new Response(body, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}

O que isso demonstra:

• Definir export const runtime = "edge" opta o Next.js route handler para o runtime Vercel Edge.
• A chave de API é lida de process.env.ANTHROPIC_API_KEY, que a Vercel injeta em edge functions da mesma forma que faz para funções Node.js, desde que a variável de ambiente esteja definida nas configurações do projeto.
• O iterador assíncrono do SDK (for await (const event of stream)) é encapsulado em um ReadableStream para que o handler possa retornar uma Response em stream em vez de esperar pela mensagem completa.
• Apenas deltas de bloco de conteúdo text_delta são encaminhados para o cliente; outros tipos de evento (message start, content block start/stop, message stop) são ignorados para este caso simples de streaming de texto.

Cloudflare Worker

// src/worker.ts
import Anthropic from "@anthropic-ai/sdk";
 
export interface Env {
  ANTHROPIC_API_KEY: string;
}
 
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method !== "POST") {
      return new Response("Use POST", { status: 405 });
    }
 
    const anthropic = new Anthropic({
      apiKey: env.ANTHROPIC_API_KEY,
    });
 
    const { prompt } = await request.json<{ prompt: string }>();
 
    const stream = await anthropic.messages.create({
      model: "claude-sonnet-5",
      max_tokens: 1024,
      messages: [{ role: "user", content: prompt }],
      stream: true,
    });
 
    const encoder = new TextEncoder();
 
    const body = new ReadableStream({
      async start(controller) {
        for await (const event of stream) {
          if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
            controller.enqueue(encoder.encode(event.delta.text));
          }
        }
        controller.close();
      },
    });
 
    return new Response(body, {
      headers: { "Content-Type": "text/plain; charset=utf-8" },
    });
  },
};

O que isso demonstra:

• Cloudflare Workers passa configurações e segredos através de um objeto env tipado passado para fetch, não através de process.env. O ANTHROPIC_API_KEY é declarado em uma interface Env e lido como env.ANTHROPIC_API_KEY.
• O segredo em si é definido fora do código, com wrangler secret put ANTHROPIC_API_KEY, então ele nunca vive no repositório ou no arquivo wrangler.toml.
• O cliente é instanciado dentro do handler fetch (não no escopo do módulo) para que ele sempre pegue os bindings env para a requisição atual.
• O padrão de streaming é idêntico ao exemplo Vercel Edge porque ambas as plataformas implementam os mesmos padrões web ReadableStream e Response.

Cancelando a Chamada Upstream na Desconexão do Cliente

Ambos os exemplos acima podem encaminhar o AbortSignal da requisição de entrada para a chamada do SDK, então uma desconexão do cliente cancela a requisição upstream para Claude em vez de deixá-la completar:

const message = await anthropic.messages.create(
  {
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: prompt }],
  },
  { signal: request.signal },
);

• Conectar AbortController ao signal da requisição de entrada significa que cancelar o cliente (fechar a aba do navegador, navegar para longe) também cancela a chamada upstream para Claude, em vez de deixá-la completar e gastar tokens para uma resposta que ninguém lerá.
• request.signal está disponível no objeto Request tanto em Vercel Edge Functions quanto em Cloudflare Workers porque ambas implementam a API padrão Fetch.

Mergulho Profundo

Como Funciona

• O @anthropic-ai/sdk envia requisições com a função global fetch em vez de um cliente HTTP específico do Node, então ele não tem dependência de built-ins do Node como http, https, ou net para seu caminho de requisição principal.
• Respostas em stream da API de Mensagens chegam como server-sent events, que o SDK parseia e expõe como um iterador assíncrono de eventos de mensagem tipados (for await (const event of stream)).
• Runtimes de edge executam seu handler em um sandbox leve, frequentemente baseado em isolados V8, não em um processo Node.js completo, que é por que APIs exclusivas do Node (fs, child_process, módulos nativos) não estão disponíveis e por que um SDK baseado em fetch é o fator decisivo para compatibilidade.
• Como o ciclo de requisição/resposta em um handler de edge é construído sobre os mesmos primitivos Request/Response/ReadableStream que o SDK usa internamente, você pode canalizar o stream do SDK diretamente para o valor de retorno da função sem uma camada de adaptador.

Tratamento da Chave de API por Plataforma

Notas sobre Deno Deploy

// main.ts (Deno Deploy)
import Anthropic from "npm:@anthropic-ai/sdk";
 
const anthropic = new Anthropic({
  apiKey: Deno.env.get("ANTHROPIC_API_KEY"),
});
 
Deno.serve(async (request: Request) => {
  const { prompt } = await request.json();
 
  const message = await anthropic.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: prompt }],
  });
 
  return Response.json(message);
});

• Deno Deploy importa pacotes npm com o especificador npm:, então import Anthropic from "npm:@anthropic-ai/sdk" funciona sem um package.json ou etapa de build.
• Segredos são lidos com Deno.env.get(...), não process.env; Deno expõe um shim process para compatibilidade, mas Deno.env é o caminho nativo e recomendado.
• Deno.serve é o ponto de entrada HTTP embutido no Deno Deploy e, como as outras duas plataformas, aceita e retorna objetos Request/Response padrão.

Notas sobre TypeScript

// Estreita a união de eventos de streaming antes de ler delta.text
for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    // event.delta.text é tipado com segurança como string aqui
    process.stdout.write(event.delta.text);
  }
}

• O SDK envia seus próprios tipos TypeScript, então message.content, eventos de streaming e classes de erro são todos tipados sem pacotes @types extras.
• Eventos de streaming são uma união discriminada em event.type; estreitar com uma verificação if (como acima) é o que permite ao TypeScript saber que event.delta.text existe, em vez de recorrer a uma asserção de tipo.
• Evite casts as any na opção apiKey do cliente. Se process.env.ANTHROPIC_API_KEY (ou env.ANTHROPIC_API_KEY) for undefined em tempo de execução porque a variável não foi definida, deixe o SDK lançar seu erro de autenticação normal em vez de silenciar o verificador de tipo.

Parâmetros e Valores de Retorno

Armadilhas

• Ler process.env em Cloudflare Workers. Cloudflare Workers não preenchem process.env com segredos por padrão; eles passam configurações através do argumento env no handler fetch. Correção: leia env.ANTHROPIC_API_KEY dentro do handler, não process.env.ANTHROPIC_API_KEY no escopo do módulo.
• Instanciar o cliente no escopo do módulo em Cloudflare Workers. Se você construir o cliente Anthropic fora da função fetch, env não estará disponível ainda quando o módulo carregar. Correção: construa o cliente dentro da função handler onde env é passado como argumento.
• Assumir que runtimes de edge não têm timeout. Vercel Edge Functions, Cloudflare Workers e Deno Deploy cada um impõe seu próprio tempo máximo de execução ou tempo de CPU por requisição, além de qualquer coisa que você configure no cliente SDK. Correção: verifique os limites atuais para seu plano em cada plataforma e projete gerações de longa duração em torno de streaming (retorne saída parcial conforme ela chega) em vez de esperar por uma única resposta grande não-streamed.
• Esquecer de definir stream: true e depois tentar iterar o resultado. Chamar anthropic.messages.create() sem stream: true retorna um único objeto Message resolvido, não um iterador assíncrono; tentar um loop for await sobre ele falha. Correção: passe stream: true nos parâmetros da requisição sempre que você pretende consumir a resposta como um stream.
• Não estreitar a união de eventos de streaming antes de ler delta.text. Eventos de streaming incluem vários tipos (message_start, content_block_start, content_block_delta, content_block_stop, message_stop, e mais), e apenas eventos content_block_delta com delta.type === "text_delta" carregam .text. Correção: verifique ambos event.type e event.delta.type antes de ler event.delta.text.
• Deixar a chave de API em código do lado do cliente. Como edge functions rodam no lado do servidor, é tentador pensar que qualquer código no mesmo repositório é seguro, mas uma chave codificada em um route handler que também envia um bundle cliente (ou copiada para uma Cloudflare Worker commitada no controle de versão) pode vazar. Correção: sempre carregue a chave de uma variável de ambiente ou loja de segredos, nunca a codifique, e adicione arquivos .env* ao .gitignore.
• Assumir que AbortController precisa de um import específico do Node. AbortController e AbortSignal são globais no Node.js 18+, todos os principais navegadores, e todos os runtimes de edge cobertos aqui, então nenhum import ou polyfill é necessário. Correção: apenas use o AbortController global, ou encaminhe request.signal de um Request de entrada quando você quiser que desconexões do cliente cancelem a chamada upstream para Claude.

Alternativas

FAQs

Relacionados

• Noções Básicas do SDK TypeScript/JavaScript - instalando o SDK e enviando sua primeira chamada tipada à API de Mensagens.
• Iteradores Assíncronos para Streaming no SDK TypeScript - um olhar mais atento ao consumo de deltas de mensagem transmitidos.
• Padrões de Retry, Timeout e AbortController no SDK TypeScript - ajustando backoff e cancelamento com mais detalhes.
• Construindo um Endpoint de Chat em Stream com Next.js e o SDK TypeScript - um endpoint de chat completo construído no padrão de streaming mostrado aqui.
• O Modelo Mental do SDK TypeScript da Anthropic - como o modelo de requisição/resposta e streaming do SDK se encaixa.

Versões da Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial @anthropic-ai/sdk TypeScript (última versão). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.