Cómo usar el kit de agentes de IA para CRM (y llevarlo a producción)

Pruébalo sin escribir código

Si no programas (o no quieres abrir una terminal hoy), el kit trae dos vías de valor inmediato. Las dos usan el mismo mini-CRM de ejemplo que el resto del kit.

1. A

   En tu navegador, con Google Colab

   ~5 min

   Los agentes reales del kit (el código Python del ADK, no una simulación) corriendo en los servidores de Google, sin instalar nada en tu ordenador:

   1. Descarga el notebook: PRUEBALO-EN-COLAB.ipynb (también viene dentro del ZIP del kit).
   2. Súbelo a colab.research.google.com (Archivo → Subir notebook) con tu cuenta de Google.
   3. Menú Entorno de ejecución → Ejecutar todo. El propio notebook te guía para conseguir la API key gratuita y se detiene para que la pegues.

   En unos 5 minutos estarás cualificando leads y cazando deals estancados desde el navegador, con la trazabilidad de herramientas a la vista.

2. B

   Copiar y pegar en ChatGPT, Claude o Gemini

   ~2 min

   La carpeta sin-codigo/ del ZIP convierte los 5 agentes en prompts listos para el chat de IA que ya uses: abre un archivo, copia desde la línea indicada, pega en un chat nuevo y conversa. Puedes guardarlos como asistentes reutilizables (GPT personalizado, Claude Project o Gem de Gemini — el README del pack explica cómo).

   Lo mejor: aceptan tus propios datos. Exporta 10–20 leads o deals de tu CRM en CSV, pégalo en la conversación y el agente trabaja sobre ellos. Eso sí: no pegues datos personales reales en cuentas gratuitas — usa una cuenta de empresa o anonimiza antes (el pack incluye el detalle de privacidad).

   Aquí el chat simula las herramientas del agente; las reglas de negocio son las mismas, pero el código real testeado es el de las partes 1 y 2.

De cero a agente funcionando

Todo lo de esta parte funciona contra el CRM simulado que trae el kit — leads, cuentas, deals y contactos de ejemplo ya cargados en datos_demo.py—, así que no necesitas conectar nada real todavía para probarlo.

1. 1

   Prepara el entorno

   2 min

   Necesitas Python 3.10 o superior. Crea un entorno virtual e instala las dependencias del kit:

   cd kit-agentes-ia-crm
   python -m venv .venv
   source .venv/bin/activate        # En Windows: .venv\\Scripts\\activate
   pip install -r requirements.txt

   Esto instala el ADK de Google y LiteLLM (la capa que permite usar cualquier modelo de IA, no solo Gemini — más abajo en el paso 2).

2. 2

   Consigue un modelo de IA

   2 min

   La forma más rápida de empezar es Gemini, gratis y sin tarjeta. No es la única opción: el kit funciona igual con Claude, GPT-4o, Mistral o un modelo local — solo cambia una variable de entorno (documentado con ejemplos concretos dentro del ZIP, en docs/05-elegir-modelo.md).

   1. Entra en aistudio.google.com/apikey con tu cuenta de Google.
   2. Pulsa Create API key y copia la clave.
   3. Copia la plantilla de entorno y pega tu clave:

   cp .env.example agentes/.env
   # Edita agentes/.env y sustituye "pega-aqui-tu-api-key" por tu clave

   ¿Empresa con Google Cloud? El .env.example incluye la opción de Vertex AI: misma API, credenciales gestionadas por tu organización.

3. 3

   Arranca la interfaz de desarrollo

   1 min

   cd agentes
   adk web

   Abre http://localhost:8000. Es la interfaz de desarrollo que trae el propio ADK de Google — no hay que instalar nada aparte. Verás un desplegable con los 5 agentes del kit.

4. 4

   Prueba los 5 agentes

   5 min

   Elige un agente en el desplegable y escribe. Algunos ejemplos que funcionan directamente contra los datos de prueba incluidos:

   coordinador_crm

   ¿Qué leads nuevos tenemos y cuáles merecen una llamada hoy?

   Revisa qué deals llevan parados más de 15 días y dime cuál atacarías primero.

   Busca contactos duplicados y dime cuáles fusionarías.

   cualificador_leads

   Cualifica el lead de laura.gomez@nortex.es y justifica la puntuación.

   seguimiento_deals

   Redáctame un email de reactivación para el deal más estancado.

   Fíjate en la pestaña Events de la interfaz: verás cada llamada a herramienta, sus argumentos y su respuesta. Esa trazabilidad completa es una de las grandes ventajas de trabajar con el ADK en vez de un chatbot genérico.

5. 5

   También desde terminal

   Si prefieres la línea de comandos en vez de la interfaz web:

   cd agentes
   adk run coordinador_crm

6. 6

   Problemas típicos

   • adk: command not found → el entorno virtual no está activado (source .venv/bin/activate).
   • Error de autenticación / 403 → revisa que agentes/.env existe y que la key no tiene espacios. El ADK busca el .env subiendo directorios desde la carpeta del agente.
   • Module not found: cualificador_leads al usar el coordinador → ejecuta adk web desde la carpeta agentes/, no desde la raíz del kit.

Cómo llevarlo a producción con un CRM real

Los agentes funcionan contra datos_demo.py. Para que operen sobre tu CRM real, solo hay que sustituir esa capa de datos: los prompts, la definición del agente y la firma de las herramientas no cambian. Los ejemplos usan HubSpot, pero el patrón es idéntico para Salesforce, Zoho o cualquier CRM con API REST.

1. A

   Crea una app privada en HubSpot

   1. En HubSpot: Ajustes → Integraciones → Apps privadas → Crear app privada.
   2. Dale un nombre (p. ej. agentes-ia-kit) y concede solo los scopes que ese agente necesita. Para cualificador_leads basta con crm.objects.contacts.read y, solo si va a registrar la cualificación, crm.objects.contacts.write.
   3. Copia el token y añádelo a agentes/.env:

   HUBSPOT_PRIVATE_APP_TOKEN=pat-eu1-xxxxxxxx

   Principio de mínimo privilegio: una app privada por agente, con los scopes justos. Si el agente solo lee, no le des escritura.

2. B

   Sustituye la capa de datos

   Ejemplo real para cualificador_leads: crea hubspot_api.py junto a datos_demo.py, con las mismas funciones que este expone:

   """Capa de datos real contra HubSpot. Mismas funciones que datos_demo.py."""
   import os
   import requests
   
   _BASE = "https://api.hubapi.com"
   
   def _headers() -> dict:
       token = os.environ["HUBSPOT_PRIVATE_APP_TOKEN"]
       return {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
   
   def buscar_lead_por_email(email: str) -> dict | None:
       resp = requests.post(
           f"{_BASE}/crm/v3/objects/contacts/search",
           headers=_headers(),
           json={
               "filterGroups": [{"filters": [
                   {"propertyName": "email", "operator": "EQ", "value": email}
               ]}],
               "properties": [
                   "email", "firstname", "lastname", "company",
                   "jobtitle", "hs_lead_status", "num_employees", "message",
               ],
               "limit": 1,
           },
           timeout=15,
       )
       resp.raise_for_status()
       resultados = resp.json().get("results", [])
       return resultados[0]["properties"] if resultados else None

   Y en tools.py, cambia una sola línea:

   # from . import datos_demo as crm      # ← antes
   from . import hubspot_api as crm       # ← después

3. C

   Reglas de oro al dar acceso real

   1. 1Empieza en solo lectura. Deja las tools de escritura apuntando a los mocks hasta que lleves días viendo comportamientos correctos en los logs.
   2. 2Escrituras reversibles primero. Crear una tarea o una nota es reversible; fusionar contactos no. Gradúa el acceso en ese orden.
   3. 3Registra la autoría. Escribe siempre una propiedad tipo origen_actualizacion = "agente-ia" para poder auditar (y revertir) todo lo que hizo el agente.
   4. 4Sandbox si existe. HubSpot ofrece cuentas sandbox: conecta primero ahí.
   5. 5Presupuesto de errores. Define de antemano qué tasa de error toleras y mide contra los evals antes de ampliar scopes.

Checklist antes de dar acceso de escritura a un agente