@rubrion/mastra-cloudflare

Agentes Mastra no Cloudflare Workers, sem código repetitivo. O Worker de agentes do template é construído sobre ela, e você pode usá-la em qualquer Worker.

npm install @rubrion/mastra-cloudflare

Seu wrangler.jsonc precisa de "compatibility_flags": ["nodejs_compat"]. O pacote reexporta Agent, Mastra, createTool, z e RequestContext, então é a única dependência de que você precisa.

Um Worker em 20 linhas

import { env } from 'cloudflare:workers';
import { createAgentServer, createTool, d1Memory, defineAgents, workersAI, z } from '@rubrion/mastra-cloudflare';

const time = createTool({
	id: 'current_time',
	description: 'A data e a hora atuais.',
	inputSchema: z.object({}),
	execute: async () => ({ now: new Date().toISOString() }),
});

const agents = defineAgents(
	[
		{ id: 'writer', name: 'Writer', description: 'Escreve e edita textos.', instructions: 'Escreva o que for pedido, de forma breve.' },
		{ id: 'helper', name: 'Helper', description: 'Perguntas gerais; sabe a hora.', instructions: 'Seja útil.', tools: { current_time: time } },
	],
	{ memory: d1Memory(() => env.MEMORY) },
);

export default createAgentServer({
	agents,
	apiKey: (e: Env) => e.API_KEY,
	defaultModel: (e: Env) => workersAI(e.AI, '@cf/google/gemma-4-26b-a4b-it', { thinking: false }),
});

createAgentServer

createAgentServer({ agents, name?, apiKey?, provider?, defaultModel?, planner?, maxSteps? }) retorna um handler de Worker, { fetch(request, env) }, sem framework HTTP (a tabela de rotas do servidor do próprio Mastra consome a maior parte da CPU de inicialização de um Worker).

Opção
agents	o registro de defineAgents
name	aparece como owned_by em /v1/models e no health check
apiKey(env)	a chave bearer que quem chama precisa enviar; sem ela, o servidor fica aberto
provider(env)	o provedor compatível com OpenAI quando a requisição não traz um
defaultModel(env)	o modelo quando não há provedor algum, por exemplo o Workers AI
planner	false desliga o roteamento auto; { model, rules } o personaliza
maxSteps	rodadas de chamadas de ferramenta por resposta (padrão 5)

Rotas: GET / (health), GET /v1/models, POST /v1/chat/completions (em streaming com stream: true; conteúdo de texto e image_url). Os cabeçalhos por requisição, para um middleware na frente, estão na referência da API.

defineAgents e buildAgent

interface AgentSpec {
	id: string;
	name: string;
	description: string; // o roteador escolhe agentes por ela
	instructions: string | ((args: { requestContext }) => string);
	model?: (requestContext) => Model; // padrão: o provedor da requisição, senão defaultModel
	tools?: Record<string, Tool>;
	maxOutputTokens?: number;
	enabled?: () => boolean; // desligado quando falta a configuração dele
}

defineAgents(specs, { memory }) retorna { list(), find(id), get(id), mastra() }. Os agentes são criados sob demanda, uma vez por isolate, porque bindings e segredos só podem ser lidos dentro de uma requisição. As specs podem ter campos próprios: defineAgents<MySpec>(…). buildAgent(spec, { memory }) cria um Agent sem cache, por exemplo por requisição.

Modelos e memória

openAICompatible({ baseURL, apiKey, model }); // OpenAI, OpenRouter, LiteLLM, vLLM, Ollama, outro servidor de agentes
workersAI(env.AI, model, { thinking }); // Workers AI; `thinking` para modelos de raciocínio (Gemma 4, Qwen 3)
providerModel(requestContext); // o provedor da requisição, senão o defaultModel do servidor
d1Memory(() => env.MEMORY, { lastMessages }); // Memory do Mastra no D1, sem banco vetorial

workersAI com thinking liga ou desliga o raciocínio do modelo pelo template de chat e descarta reasoning_effort: o Mastra envia a opção unificada reasoning do AI SDK, e modelos de raciocínio como o Gemma 4 param de raciocinar sempre que ela está presente.

Código: github.com/rubrion/mastra-cloudflare · Licença: GPL-3.0.