Construindo Agentes de IA em Tempo Real com Astro e Cloudflare

PADRÃO CENTRALIZADO:
Usuário ---> Servidor da Aplicação (US-East) ---> API da OpenAI (West) ---> Servidor App ---> Usuário
RTT Total: 800ms - 1500ms

PADRÃO DE INFRAESTRUTURA EDGE:
Usuário ---> Servidor Cloudflare Edge (Data Center mais próximo) ---> Workers AI (GPU no mesmo Data Center) ---> Usuário
RTT Total: 150ms - 300ms

{
  "name": "astro-ai-agent",
  "compatibility_date": "2026-06-01",
  "main": "dist/server/entry.mjs",
  "ai": {
    "binding": "AI"
  }
}

// src/actions/index.ts
import { defineAction } from "astro:actions";
import { z } from "astro:schema";

export const server = {
  askAgent: defineAction({
    input: z.object({
      prompt: z.string().min(1, "O prompt não pode estar vazio"),
      systemPrompt: z.string().optional(),
    }),
    handler: async ({ prompt, systemPrompt }, context) => {
      // 1. Localizar o binding do Cloudflare Workers AI
      const env = context.locals.runtime?.env;
      if (!env || !env.AI) {
        throw new Error(
          "O binding do Cloudflare Workers AI não foi encontrado.",
        );
      }

      const ai = env.AI;

      // 2. Configurar limites de segurança e padrões do modelo
      const systemMessage = systemPrompt || "Você é um assistente útil.";

      try {
        // 3. Invocar a execução do modelo em GPUs próximas ao usuário
        const response = await ai.run("@cf/meta/llama-3-8b-instruct", {
          messages: [
            { role: "system", content: systemMessage },
            { role: "user", content: prompt },
          ],
          stream: true,
        });

        // 4. Retornar o ReadableStream bruto diretamente para o cliente
        return response;
      } catch (error) {
        console.error("Erro de inferência no Workers AI:", error);
        throw new Error(
          "Falha ao processar a requisição através do modelo de IA no edge.",
        );
      }
    },
  }),
};

<!-- src/components/AgentChat.astro -->
<div class="chat-container mx-auto max-w-xl rounded-lg border bg-black/20 p-4">
  <div id="chat-output" class="mb-4 h-64 overflow-y-auto border-b p-2"></div>
  <form id="chat-form" class="flex gap-2">
    <input
      type="text"
      id="chat-input"
      placeholder="Pergunte ao seu agente..."
      class="flex-1 rounded-full border border-zinc-700 bg-zinc-800 px-4 py-2 text-white"
    />
    <button
      type="submit"
      class="rounded-full bg-purple-600 px-6 py-2 hover:bg-purple-700"
    >
      Enviar
    </button>
  </form>
</div>

<script>
  import { actions } from "astro:actions";

  const form = document.getElementById("chat-form") as HTMLFormElement;
  const input = document.getElementById("chat-input") as HTMLInputElement;
  const output = document.getElementById("chat-output") as HTMLDivElement;

  form?.addEventListener("submit", async (e) => {
    e.preventDefault();
    if (!input || !output || !input.value.trim()) return;

    const userPrompt = input.value;
    input.value = "";

    // Adicionar entrada do usuário à UI
    output.innerHTML += `<div class="user-message mb-2 text-right"><strong>Você:</strong> ${userPrompt}</div>`;

    // Adicionar placeholder para a resposta em streaming da IA
    const aiMessageContainer = document.createElement("div");
    aiMessageContainer.className = "ai-message mb-2 text-left";
    aiMessageContainer.innerHTML = `<strong>Agente:</strong> <span class="content">Pensando...</span>`;
    output.appendChild(aiMessageContainer);
    const contentSpan = aiMessageContainer.querySelector(".content") as HTMLSpanElement;

    try {
      // Invocar a action do Astro
      const { data, error } = await actions.askAgent({ prompt: userPrompt });
      if (error || !data) {
        contentSpan.innerText = "Erro: " + (error?.message || "Falha na inferência");
        return;
      }

      // Ler o stream de resposta
      const reader = (data as ReadableStream).getReader();
      const decoder = new TextDecoder();
      contentSpan.innerText = ""; // Limpar placeholder "Pensando..."

      while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        const chunkText = decoder.decode(value, { stream: true });
        contentSpan.innerText += chunkText;
        output.scrollTop = output.scrollHeight;
      }
    } catch (err) {
      console.error(err);
      contentSpan.innerText = "Falha ao se comunicar com o agente.";
    }
  });
</script>

+--------+            +----------------------------+            +-------------+
|        |            |       Servidor Astro       |            |             |
|        | --(POST)-->| (Astro Action: askAgent)   |            |             |
|        |            |  +----------------------+  |            |             |
|        |            |  | 1. Consultar Hist D1 |<------------->| Cloudflare  |
| Cliente|            |  +----------------------+  |            | Banco D1    |
| (UI)   |            |  +----------------------+  |            |             |
|        |            |  | 2. Buscar Cache KV   |<------------->| Cloudflare  |
|        |            |  +----------------------+  |            | KV Store    |
|        |            |  +----------------------+  |            |             |
|        |            |  | 3. Executar Inferên. |<------------->| Workers AI  |
|        |<-(Stream)--|  +----------------------+  |            | Nodo GPU    |
|        |            |  +----------------------+  |            |             |
|        |            |  | 4. Salvar no D1 / KV |  |            |             |
+--------+            +----------------------------+            +-------------+

-- db/schema.sql
CREATE TABLE IF NOT EXISTS chat_history (
  id TEXT PRIMARY KEY,
  session_id TEXT NOT NULL,
  role TEXT CHECK(role IN ('system', 'user', 'assistant')) NOT NULL,
  content TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX IF NOT EXISTS idx_sessions ON chat_history(session_id);

{
  "name": "astro-ai-agent",
  "compatibility_date": "2026-06-01",
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "astro-agent-db",
      "database_id": "SEU_DATABASE_UUID_AQUI"
    }
  ]
}

// src/actions/index.ts (Estendido com persistência D1)
import { defineAction } from "astro:actions";
import { z } from "astro:schema";

export const server = {
  askStatefulAgent: defineAction({
    input: z.object({
      sessionId: z.string().uuid("Identificador de sessão inválido"),
      prompt: z.string().min(1, "O prompt não pode estar vazio"),
    }),
    handler: async ({ sessionId, prompt }, context) => {
      const env = context.locals.runtime?.env;
      if (!env || !env.AI || !env.DB) {
        throw new Error(
          "Bindings do runtime Cloudflare ausentes (AI ou Banco D1).",
        );
      }

      const ai = env.AI;
      const db = env.DB;

      try {
        // 1. Buscar as últimas 10 mensagens do D1 para evitar inchaço da janela de contexto
        const { results } = await db
          .prepare(
            "SELECT role, content FROM chat_history WHERE session_id = ? ORDER BY created_at ASC LIMIT 10",
          )
          .bind(sessionId)
          .all<{ role: string; content: string }>();

        // 2. Formatar o histórico para o motor Llama 3
        const conversationHistory = results.map((row) => ({
          role: row.role as "system" | "user" | "assistant",
          content: row.content,
        }));

        // 3. Anexar a consulta atual do usuário
        const currentMessages = [
          {
            role: "system" as const,
            content: "Você é um agente de IA com estado rodando no edge.",
          },
          ...conversationHistory,
          { role: "user" as const, content: prompt },
        ];

        // 4. Salvar o prompt do usuário imediatamente no D1
        const userMessageId = crypto.randomUUID();
        await db
          .prepare(
            "INSERT INTO chat_history (id, session_id, role, content) VALUES (?, ?, 'user', ?)",
          )
          .bind(userMessageId, sessionId, prompt)
          .run();

        // 5. Consultar o Workers AI com stream ativado
        const responseStream = (await ai.run("@cf/meta/llama-3-8b-instruct", {
          messages: currentMessages,
          stream: true,
        })) as ReadableStream;

        // 6. Configurar um stream duplo: transmitir de volta ao usuário enquanto acumula a resposta completa para o D1
        const [clientStream, serverStream] = responseStream.tee();

        // Escrevemos no D1 de forma assíncrona sem bloquear o stream do cliente
        (async () => {
          const reader = serverStream.getReader();
          const decoder = new TextDecoder();
          let completeResponse = "";

          while (true) {
            const { done, value } = await reader.read();
            if (done) break;
            completeResponse += decoder.decode(value, { stream: true });
          }

          const assistantMessageId = crypto.randomUUID();
          await db
            .prepare(
              "INSERT INTO chat_history (id, session_id, role, content) VALUES (?, ?, 'assistant', ?)",
            )
            .bind(assistantMessageId, sessionId, completeResponse)
            .run();
        })().catch((err) =>
          console.error("Falha ao persistir a resposta do assistente:", err),
        );

        return clientStream;
      } catch (error) {
        console.error("Falha na execução com estado no edge:", error);
        throw new Error(
          "Incapaz de completar o processamento do agente com estado.",
        );
      }
    },
  }),
};

// Snippet de demonstração de cache
const promptHash = await crypto.subtle.digest(
  "SHA-256",
  new TextEncoder().encode(prompt),
);
const cacheKey = `agent-cache:${Array.from(new Uint8Array(promptHash))
  .map((b) => b.toString(16).padStart(2, "0"))
  .join("")}`;

// Verificar KV
const cachedResponse = await env.KV_STORE.get(cacheKey);
if (cachedResponse) {
  // Transmitir diretamente o valor do cache ou retornar imediatamente
  return new ReadableStream({
    start(controller) {
      controller.enqueue(new TextEncoder().encode(cachedResponse));
      controller.close();
    },
  });
}