Arquitectura y setup

"Antes de escribir la primera línea, entendé qué estás construyendo. Un chatbot es 20% modelo y 80% lo que vos armás alrededor."

Qué vas a aprender en este capítulo

Cuando chateás con Claude o ChatGPT, se siente como hablar con algo que te recuerda, que tiene personalidad, que a veces busca información o ejecuta acciones. Nada de eso vive dentro del modelo. El modelo es una función: texto entra, texto sale. Todo lo demás — la memoria, la personalidad, las acciones, el conocimiento del negocio — lo construye el programador. O sea, vos.

En este capítulo vas a:

• Ver el plano completo del chatbot que vas a construir para La Esquina (y entender cada caja del diagrama).
• Entender por qué la API es stateless y qué te obliga a hacer.
• Dejar tu entorno listo: venv, SDK, API key segura.
• Escribir tu primer programa con la API de Claude, explicado línea por línea.
• Calcular cuánto cuesta cada mensaje — porque un bot que no sabés cuánto cuesta no está listo para producción.

1.1 Qué es realmente un chatbot moderno

Este es el plano del sistema completo que vas a tener funcionando al final del libro. No te preocupés si todavía no entendés cada caja — para eso están los capítulos:

subgraph APP_INT["Lo que construís VOS"]
    SP["System prompt<br/>(personalidad + reglas)<br/>cap. 2"]
    H["Historial de mensajes<br/>(la 'memoria')<br/>cap. 2"]
    T["Herramientas<br/>consultar_menu, registrar_pedido...<br/>cap. 3"]
    K["Conocimiento (RAG)<br/>políticas + FAQ indexadas<br/>cap. 4"]
end

APP --> SP
APP --> H
APP --> K
APP -->|"request: system + historial<br/>+ tools + contexto"| API["API de Claude<br/>(claude-opus-4-8)"]
API -->|"texto o tool_use"| APP
APP <-->|ejecutar| T
APP -->|respuesta| U

La flecha clave es la del medio: en cada turno, tu aplicación arma un request con TODO (system prompt, historial completo, herramientas disponibles, contexto recuperado) y la API devuelve la siguiente respuesta. La API no guarda nada entre llamadas.

messages = [
    {"role": "user", "content": "¿Tienen pupusas de ayote?"},
    {"role": "assistant", "content": "¡Sí! La de ayote cuesta 0.85..."},
    {"role": "user", "content": "Dame 3 entonces"},   # ← el turno nuevo
]

1.2 El caso de negocio: el bot de La Esquina

Doña Carmen, dueña de La Esquina, tiene tres sucursales en San Miguel y un problema: entre las 11:30 y la 1:00 el teléfono no para, y las muchachas no dan abasto anotando pedidos mientras atienden mesas. Te contrató para construir un bot que atienda el chat del sitio web. Estos son los requisitos, levantados en una reunión con ella:

Fijate en algo: casi ningún requisito se resuelve "con el modelo". El modelo es el mismo en todos. Lo que cambia es lo que construís alrededor. Guardá esta tabla — vamos a volver a ella al final de cada capítulo para marcar qué ya cumplimos.

1.3 Los modelos y sus precios

1.4 Setup del entorno

Vamos a dejar todo listo. Necesitás Python 3.10 o superior (python3 --version para verificar).

Paso 1: carpeta y entorno virtual

mkdir bot-la-esquina
cd bot-la-esquina
python3 -m venv .venv
source .venv/bin/activate        # En Windows: .venv\Scripts\activate

El entorno virtual aísla las dependencias del proyecto. Si el prompt de tu terminal ahora muestra (.venv), vas bien.

Paso 2: instalar dependencias

pip install anthropic python-dotenv

• anthropic: el SDK oficial de Python para la API de Claude.
• python-dotenv: para cargar la API key desde un archivo .env (ahora vas a ver por qué).

Paso 3: obtener y guardar la API key

1. Creá una cuenta en la consola de Anthropic (platform.claude.com).
2. Cargá un mínimo de crédito ($5 alcanza de sobra para todo este libro).
3. Generá una API key. Es un string largo que empieza con sk-ant-.... Tratala como una contraseña: quien la tenga puede gastar tu crédito.

Guardala en un archivo llamado .env en la raíz del proyecto:

# Archivo: .env
ANTHROPIC_API_KEY=sk-ant-tu-key-aqui

Y creá inmediatamente un .gitignore para que jamás llegue a un repositorio:

# Archivo: .gitignore
.env
.venv/
__pycache__/
*.pyc
conversaciones/
pedidos.json

client = anthropic.Anthropic(api_key="sk-ant-abc123...")   # ❌ NUNCA

1.5 Hola, Claude — tu primera llamada, línea por línea

Creá 01_hola_claude.py:

"""Primera llamada a la API de Claude — el 'hola mundo' del libro."""
from dotenv import load_dotenv
import anthropic

load_dotenv()  # carga ANTHROPIC_API_KEY desde .env al entorno

client = anthropic.Anthropic()  # lee la key del entorno; NUNCA la pongas acá

respuesta = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system="Sos el asistente de La Esquina, una pupusería de San Miguel, El Salvador.",
    messages=[
        {"role": "user", "content": "¡Hola! ¿Qué venden ustedes?"},
    ],
)

print(respuesta.content[0].text)

Corrélo:

python 01_hola_claude.py

Vas a recibir algo como: "¡Hola! Bienvenido a La Esquina 😊 Somos una pupusería..." — el modelo ya adoptó el rol, solo con esa línea de system prompt.

1.6 ¿Cuánto costó ese mensaje?

Un bot en producción sin medición de costos es un cheque en blanco. Vamos a construir desde el día uno el hábito de medir. Creá 02_costo.py:

"""Calcular el costo exacto de cada llamada usando response.usage."""
from dotenv import load_dotenv
import anthropic

load_dotenv()
client = anthropic.Anthropic()

# Precios de claude-opus-4-8 por MILLON de tokens (junio 2026)
PRECIO_ENTRADA = 5.00   # USD por 1M tokens de entrada
PRECIO_SALIDA = 25.00   # USD por 1M tokens de salida


def costo_usd(usage) -> float:
    """Convierte el usage de una respuesta en dolares."""
    entrada = usage.input_tokens * PRECIO_ENTRADA / 1_000_000
    salida = usage.output_tokens * PRECIO_SALIDA / 1_000_000
    return entrada + salida


respuesta = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system="Sos el asistente de La Esquina, una pupusería de San Miguel.",
    messages=[
        {"role": "user", "content": "¿Qué es una pupusa? Explicámelo en 2 oraciones."},
    ],
)

print(respuesta.content[0].text)
print("-" * 50)
print(f"stop_reason:    {respuesta.stop_reason}")
print(f"Tokens entrada: {respuesta.usage.input_tokens}")
print(f"Tokens salida:  {respuesta.usage.output_tokens}")
print(f"Costo:          {costo_usd(respuesta.usage):.6f} USD")

Salida típica:

Una pupusa es una tortilla gruesa de maíz rellena de queso, chicharrón o
frijoles, asada en comal. Es el platillo nacional de El Salvador y se sirve
con curtido y salsa de tomate.
--------------------------------------------------
stop_reason:    end_turn
Tokens entrada: 41
Tokens salida:  68
Costo:          0.001905 USD

Menos de un quinto de centavo. Pero ese número va a crecer cuando el historial crezca — y por eso lo medimos siempre.

conteo = client.messages.count_tokens(
    model="claude-opus-4-8",
    system="Sos el asistente de La Esquina, una pupusería de San Miguel.",
    messages=[{"role": "user", "content": "¿Qué es una pupusa?"}],
)
print(conteo.input_tokens)   # p. ej. 38

1.7 Manejo de errores desde el día uno

La red falla, los servidores se saturan, los límites de tasa existen. El SDK trae excepciones tipadas y reintenta automáticamente los errores temporales (429 y 5xx) con backoff exponencial — pero tu código igual debe estar preparado para cuando los reintentos se agotan. Creá 03_errores.py:

"""Llamada con manejo de errores tipado — la plantilla que usaremos siempre."""
from dotenv import load_dotenv
import anthropic

load_dotenv()
client = anthropic.Anthropic()


def preguntar(texto: str) -> str:
    """Hace una pregunta al modelo y devuelve el texto, manejando errores."""
    try:
        respuesta = client.messages.create(
            model="claude-opus-4-8",
            max_tokens=1024,
            system="Sos el asistente de La Esquina, pupusería de San Miguel.",
            messages=[{"role": "user", "content": texto}],
        )
        return respuesta.content[0].text
    except anthropic.RateLimitError:
        # 429: demasiados requests. El SDK ya reintento; si llegamos aca, esperar.
        return "⏳ Estamos recibiendo muchos mensajes. Probá de nuevo en un minuto."
    except anthropic.APIConnectionError:
        # No se pudo conectar: red caida, DNS, timeout.
        return "🔌 No hay conexión con el servidor. Revisá tu internet."
    except anthropic.APIStatusError as e:
        # Cualquier otro error HTTP. 529 = API sobrecargada (temporal).
        if e.status_code == 529:
            return "🔥 El servicio está sobrecargado. Reintentá en unos segundos."
        return f"⚠️ Error del API ({e.status_code}): {e.message}"


if __name__ == "__main__":
    print(preguntar("¿A qué hora abren?"))

El orden de los except importa: de lo más específico (RateLimitError) a lo más general (APIStatusError). Esta plantilla — try, excepciones tipadas, mensajes amables al usuario — la vamos a arrastrar a todos los capítulos.

Resumen visual

Estado del proyecto — requisitos de La Esquina cumplidos: ninguno todavía 😅, pero ya tenés el entorno seguro, sabés llamar a la API, leer la respuesta y medir el costo. La base de todo lo que viene.

Ejercicios

messages=[
    {"role": "user", "content": "¿Tienen pupusas de chicharrón?"},
    {"role": "assistant", "content": "¡Claro! Las de chicharrón son de las más pedidas."},
    {"role": "user", "content": "Dame 2 entonces."},
]

PRECIOS = {  # (entrada, salida) USD por MTok
    "claude-fable-5": (10, 50),
    "claude-opus-4-8": (5, 25),
    "claude-sonnet-4-6": (3, 15),
    "claude-haiku-4-5": (1, 5),
}

def costo(modelo, t_in, t_out):
    e, s = PRECIOS[modelo]
    return t_in * e / 1e6 + t_out * s / 1e6

msgs = 2000 * 8                      # 16,000 mensajes/mes
for m in PRECIOS:
    mensual = msgs * costo(m, 600, 150)
    print(f"{m:20s} ${mensual:8.2f}/mes")

Para profundizar

• Documentación oficial del API — platform.claude.com/docs: la referencia del endpoint Messages, modelos vigentes y precios actualizados. Marcala en favoritos; los precios de este libro caducan, esa página no.
• SDK de Python — github.com/anthropics/anthropic-sdk-python: el README cubre todos los parámetros y las excepciones tipadas.
• Capítulo 6 del libro de IA de esta colección — LLMs y transformers: si querés entender qué pasa dentro del modelo (tokens, atención, entrenamiento), ese es el lugar.
• python-dotenv — pypi.org/project/python-dotenv: patrones para manejar configuración por entorno (dev, staging, producción).