Clase 03 · Módulo 10
Llamar a Claude desde una función de servidor
Llamar a Claude desde una función de servidor
Qué logras en esta clase
Construyes la función de servidor que recibe un texto de tu app, llama a Claude y devuelve el resultado.
- Creas y despliegas una Edge Function.
- Guardas la clave como secreto y validas al usuario.
- Lees la respuesta y manejas los errores.
- La llamas desde una pantalla.
02
El recorrido completo
El ejemplo de la clase es una función llamada resumir: recibe un texto y devuelve un resumen corto. Cambia el nombre y las instrucciones para tu caso; la estructura es la misma.
03
Lo que necesitas antes de empezar
- Tu proyecto de Supabase con usuarios funcionando (módulos 7 y 8).
- La CLI de Supabase, su herramienta de terminal, enlazada al proyecto (módulo 7).
- Una cuenta en la Console de Anthropic con saldo para la API.
- El identificador del modelo, copiado de la página oficial de modelos.
04
Crea la clave en la Console
- Entra a la Console de Anthropic con tu cuenta.
- Ve a la sección de claves de API.
- Crea una clave con un nombre que diga app y entorno, por ejemplo «taller-produccion».
- Cópiala en ese momento y pégala directo en el paso de secretos.
No la guardes en notas, chats ni archivos del proyecto.
05
Crea la función
En la terminal, dentro de la carpeta del proyecto:
supabase functions new resumirEl comando crea el archivo supabase/functions/resumir/index.ts. Las Edge Functions se escriben en TypeScript y corren sobre Deno, un entorno de ejecución parecido a Node.
Abre el archivo generado: trae una plantilla que ya responde. Según la guía oficial, esa plantilla acepta la clave publicable o la secreta; en esta clase la cambias para exigir un usuario.
06
Guarda la clave como secreto
supabase secrets set ANTHROPIC_API_KEY=pega-aqui-tu-clave
supabase secrets list- El segundo comando lista los secretos del proyecto para confirmar.
- Un nombre de secreto no puede empezar con
SUPABASE_. - Las funciones ya desplegadas toman el secreto nuevo sin volver a desplegar.
- Para pruebas locales, el valor va en
supabase/functions/.env, fuera de Git.
07
De la Console al secreto, sin escalas
La clave pasa de la Console al secreto del servidor. Nunca toca tu repositorio ni tu app.
08
Lee el secreto dentro de la función
const clave = Deno.env.get('ANTHROPIC_API_KEY')Deno.env.get devuelve el valor del secreto mientras la función corre. Si devuelve vacío, el secreto no existe con ese nombre exacto.
09
Validar al usuario: dos capas
| Capa | Qué hace |
|---|---|
| Plataforma | Con verify_jwt = true, el valor por defecto, rechaza pedidos sin un token válido antes de ejecutar tu código |
Envoltorio withSupabase | Con auth: 'user' exige la sesión de un usuario y te entrega sus datos |
El token es el JWT de la sesión, visto en el módulo 8. La app lo envía sola en cada llamada.
10
La forma de la función
import { withSupabase } from 'npm:@supabase/server@1'
export default {
fetch: withSupabase({ auth: 'user' }, async (req, ctx) => {
const usuarioId = ctx.userClaims?.id
// validar texto, revisar cuota, llamar a Claude
return Response.json({ resumen: '...' })
}),
}ctx.userClaims trae la identidad sacada del token y ctx.supabase es un cliente que respeta RLS como ese usuario. Compara esta forma con tu plantilla: puede variar entre versiones.
11
La identidad sale del token
El identificador del usuario se lee del token verificado, nunca de un campo que mande la app.
12
Valida lo que llega
Antes de gastar un solo token, la función revisa el cuerpo del pedido:
- Que el texto exista y sea texto.
- Que no supere un largo máximo que tú fijas.
- Que no venga vacío.
Si algo falla, responde con un error 400, sin llamar a Claude.
13
Las piezas del pedido a Claude
El pedido es un POST a https://api.anthropic.com/v1/messages con este cuerpo:
| Campo | Para qué |
|---|---|
model | Identificador del modelo, copiado de la página de modelos |
max_tokens | Tope de tokens que puede escribir la respuesta |
system | Tus instrucciones fijas: tarea, tono, formato |
messages | La conversación; aquí va el texto del usuario |
14
El pedido en código
const r = await fetch('https://api.anthropic.com/v1/messages', {
method: 'POST',
headers: {
'x-api-key': clave,
'anthropic-version': VERSION_API,
'content-type': 'application/json',
},
body: JSON.stringify({
model: MODELO,
max_tokens: 300,
system: INSTRUCCIONES,
messages: [{ role: 'user', content: texto }],
}),
})MODELO y VERSION_API son constantes tuyas. Copia sus valores de la referencia oficial el día que construyas: cambian con el tiempo.
15
Fetch directo o SDK oficial
| Opción | Cuándo conviene |
|---|---|
fetch directo | Un pedido simple; ves exactamente qué se envía |
| SDK oficial de Anthropic para TypeScript | Streaming, herramientas o varios pedidos distintos |
Para una primera función, fetch alcanza y tiene menos piezas que mantener. Si pasas al SDK, pide a Claude Code que siga la documentación vigente y no ejemplos de memoria.
16
Leer la respuesta
La API devuelve un objeto con tres partes que te importan:
content: lista de bloques; el texto viene en los bloques de tipotext.stop_reason: por qué dejó de escribir.usage: cuántos tokens entraron (input_tokens) y salieron (output_tokens).
Guarda usage junto al identificador del usuario. Es la base del cálculo de costos de la clase 4 y de la cuota de la clase 5.
17
Qué te dice stop_reason
| Valor | Significa | Qué haces |
|---|---|---|
end_turn | Terminó normalmente | Devuelves el texto |
max_tokens | Se cortó por el tope | Avisas que quedó incompleto o subes el tope |
refusal | El modelo se negó a responder | Muestras un mensaje neutro, sin texto generado |
Existen más valores; estos tres son los que una función simple debe manejar.
18
Devuelve solo lo necesario
La función responde a la app con el texto final y nada más. Los detalles internos se quedan en el servidor.
19
Errores que tu función debe traducir
| Situación | Código hacia la app |
|---|---|
| Sin sesión válida | 401 |
| Texto vacío o demasiado largo | 400 |
| Claude responde 429 por exceso de pedidos | 429, con «intenta en unos segundos» |
| Claude falla o no contesta | 502, con un mensaje genérico |
Cuando Claude responde 429 puede incluir la cabecera retry-after con los segundos de espera. No reenvíes a la app el error crudo de la API.
20
Probar en tu computador
supabase start
supabase functions serve resumirEl primero levanta el entorno local de Supabase y el segundo sirve tu función en http://127.0.0.1:54321/functions/v1/resumir. Los secretos locales se leen de supabase/functions/.env.
21
Tres pruebas que debe pasar
- Sin sesión: la llamada es rechazada con 401.
- Texto de más: un texto sobre el máximo recibe 400 y no se llama a Claude.
- Caso normal: con sesión y texto válido llega el resumen.
Pide a Claude Code que ejecute las tres y te muestre la respuesta de cada una. Si la primera no falla, tu función está abierta.
22
Desplegar
supabase login
supabase link --project-ref TU_PROYECTO
supabase functions deploy resumirLos dos primeros se hacen una vez por computador y proyecto; si ya enlazaste en el módulo 7, sáltalos. El tercero publica la función y se repite cada vez que cambias su código. No pasa por las tiendas: el cambio vale para todas las versiones instaladas de tu app.
23
Llamarla desde la app
const { data, error } = await supabase.functions.invoke('resumir', {
body: { texto },
})El cliente de Supabase que configuraste en el módulo 7 agrega la sesión del usuario a la llamada. Si no hay sesión iniciada, la función responde con error: muestra la pantalla de ingreso en vez de un fallo.
24
Los estados de la pantalla
- Cargando: indicador visible y botón deshabilitado para no enviar dos veces.
- Listo: el resultado aparece en un campo editable.
- Error: mensaje claro y botón para reintentar.
- Sin sesión: se invita a ingresar.
Es una escritura hacia el servidor: trátala como las mutaciones de TanStack Query del módulo 6.
25
Límites de tiempo de la función
| Límite (al 18-11-2026) | Valor |
|---|---|
| Duración máxima, plan Free | 150 segundos |
| Tiempo de CPU por pedido | 2 segundos |
| Espera máxima sin responder | 150 segundos; después la app recibe un 504 |
Esperar a Claude no consume CPU, así que un resumen corto cabe de sobra. Para textos largos, considera responder por partes (streaming). Comprueba las cifras en la página de límites antes de diseñar.
26
Cómo pedírselo a Claude Code
Describe el resultado y las condiciones, no solo «hazme la función»:
- Qué recibe y qué devuelve.
- Que exija usuario con sesión.
- Largo máximo del texto y tope de
max_tokens. - Que nunca registre la clave ni el texto del usuario.
- Que traduzca los errores a códigos claros.
27
Dos errores frecuentes
El segundo: dejar max_tokens alto «por si acaso». Ese número es el tope de lo que pagas por respuesta. Ajústalo al largo real que necesita tu función y revísalo cuando veas respuestas cortadas.
28
Lo que te llevas
- La función se crea con
supabase functions newy se publica consupabase functions deploy. - La clave vive en
supabase secretsy se lee conDeno.env.get. - El usuario se identifica por su token, validado antes de tu lógica.
- Validas el texto, fijas
max_tokensy traduces los errores. - Guardas
usagede cada respuesta para medir costos.
29
Hazlo ahora
En 15 minutos:
- Crea una función con
supabase functions newy lee la plantilla con Claude Code. - Cámbiala para que exija usuario con
auth: 'user'y devuelva un texto fijo. - Guarda un secreto de prueba y confirma con
supabase secrets list. - Despliégala y llámala con
functions.invoke, con y sin sesión iniciada.
Si sin sesión es rechazada, la validación funciona y puedes conectar a Claude.
Clase terminada
Sigue con la próxima.
Fuentes · revisadas el 18 de noviembre de 2026
- Supabase: primeros pasos con Edge Functionssupabase.com ↗
- Supabase: secretos de Edge Functionssupabase.com ↗
- Supabase: autenticación en Edge Functionssupabase.com ↗
- Supabase: límites de Edge Functionssupabase.com ↗
- Claude Platform: referencia de la API de mensajesplatform.claude.com ↗
- Claude Platform: resumen de modelosplatform.claude.com ↗
- Claude Platform: límites de usoplatform.claude.com ↗