ACME Shop — Agente de atención al cliente (ADK)

Sistema multiagente de atención al cliente para ACME Shop, una tienda de tecnología (audífonos, teclados, monitores y accesorios), construido con Google Agent Development Kit (ADK) 2.5.

Esta es la implementación base construida durante el curso: un agente raíz que enruta la conversación a cuatro agentes especializados, cada uno con prompts simples e instrucciones directas. Sirve como punto de partida funcional del patrón router + sub-agentes de ADK, antes de aplicarle prácticas de prompt engineering de nivel producción.

Para una versión con prompts endurecidos (contratos de herramienta, resistencia a inyección, reglas de precedencia, políticas compartidas, etc.) ver la rama main-production-grade.

Arquitectura

                     ┌───────────────┐
        cliente ───▶ │  root_agent   │  gemini-3.5-flash
                     │  (router)     │  tools: conocimiento_empresa_rag,
                     └───────┬───────┘         preload_memory_tool
                             │ transfer_to_agent
        ┌────────────┬───────┼───────┬────────────┐
        ▼            ▼               ▼            ▼
   ┌─────────┐  ┌───────────┐  ┌───────────┐ ┌──────────────────┐
   │ pedidos │  │devoluciones│  │escalamiento│ │ recomendaciones  │
   │ grok-4.1│  │gemini-3.1- │  │gemini-3.1- │ │ gemini-3.5-flash │
   │ -fast-  │  │pro-preview │  │pro-preview │ │ tool:            │
   │reasoning│  │            │  │            │ │obtener_recomend. │
   └─────────┘  └───────────┘  └───────────┘ └──────────────────┘

root_agent no resuelve consultas de pedidos, devoluciones ni recomendaciones por sí mismo: su instrucción es identificar la intención del cliente y transferir con transfer_to_agent (mecanismo nativo de ADK que se construye automáticamente a partir de sub_agents) al especialista correspondiente.

Agente	Modelo	Responsabilidad	Herramientas
root_agent	gemini-3.5-flash	Recibe al cliente y enruta al especialista correcto	conocimiento_empresa_rag, preload_memory_tool
pedidos	grok-4.1-fast-reasoning (vía LiteLlm/Vertex)	Estado de envío y fecha de entrega a partir de un número de pedido	—
devoluciones	gemini-3.1-pro-preview	Elegibilidad de devolución y reembolsos según la política	—
recomendaciones	gemini-3.5-flash	Sugerencia de productos según uso y presupuesto	obtener_recomendaciones
escalamiento	gemini-3.1-pro-preview	Apertura de ticket simulado y derivación a soporte humano	—

Los pedidos que reconoce pedidos/devoluciones son datos de ejemplo escritos directamente en el prompt (no una base de datos real), y el catálogo de recomendaciones viene de una API pública de prueba (api.escuelajs.co), usada aquí solo para ilustrar el flujo de la herramienta.

Estructura del proyecto

app/
├── agent.py                    # Define root_agent y su árbol de sub_agents
├── agents/
│   ├── pedidos.py               # Agent + instrucción con datos de pedidos de ejemplo
│   ├── devoluciones.py          # Agent + instrucción con política de devoluciones
│   ├── recomendaciones.py       # Agent + instrucción + tool de recomendaciones
│   └── escalamiento.py          # Agent + instrucción de escalamiento a soporte humano
├── tools/
│   ├── RAG.py                    # conocimiento_empresa_rag (Vertex RAG corpus)
│   └── recomendaciones.py        # obtener_recomendaciones (catálogo vía API pública)
├── requirements.txt
└── .env                          # Config de proyecto/ubicación de Google Cloud (no versionar credenciales reales)

Cada agente se define como un Agent(...) de ADK con su instruction escrita directamente como string en el mismo archivo, siguiendo el patrón más simple de organización: un archivo por agente, sin capa de prompts compartida.

Requisitos

• Python 3.11+
• Una cuenta de Google Cloud con Vertex AI habilitado (proyecto y ubicación configurados en app/.env)
• Acceso al RAG Corpus referenciado en app/tools/RAG.py
• Credenciales de Application Default Credentials (gcloud auth application-default login) o el mecanismo de autenticación que use tu entorno

Instalación

python -m venv .venv
source .venv/bin/activate
pip install -r app/requirements.txt

Configura app/.env con tu proyecto y ubicación de Google Cloud:

GOOGLE_GENAI_USE_ENTERPRISE=1
GOOGLE_CLOUD_PROJECT=<tu-proyecto>
GOOGLE_CLOUD_LOCATION=<tu-ubicación>

Ejecución

Con el ADK CLI:

adk web

Esto levanta la UI de desarrollo de ADK, donde puedes conversar con root_agent y observar en vivo las transferencias (transfer_to_agent) entre agentes, las llamadas a herramientas y el estado de la sesión.

También puede ejecutarse en modo consola:

adk run app

Datos de ejemplo (pedidos)

Los agentes pedidos y devoluciones reconocen tres pedidos simulados, escritos directamente en sus prompts:

Pedido	Producto	Estado
PS-1001	Audífonos inalámbricos	Entregado el 15 de julio
PS-1002	Teclado mecánico	En tránsito, llega el 24 de julio
PS-1003	Monitor 27"	Preparando envío

Úsalos para probar el flujo end-to-end, por ejemplo: "¿dónde está mi pedido PS-1002?" o "quiero devolver el PS-1001".

Alcance y siguientes pasos

Esta versión prioriza que el patrón multiagente funcione de punta a punta con el mínimo de código posible. Cosas explícitamente fuera de alcance aquí:

• Los prompts son instrucciones simples sin capa de resistencia a inyección, contratos formales de uso de herramientas, ni política de marca/tono centralizada entre agentes.
• Los datos de pedidos son estáticos y viven en el prompt, no en una base de datos.
• El número de ticket de escalamiento lo genera el modelo como texto libre, no un sistema real de tickets.

Para la versión con estas prácticas resueltas, ver la rama main-production-grade.