Agents From Scratch - Guía para la Construcción de Agentes de IA desde Cero

Resumen del Proyecto

Este repositorio es una guía para construir agentes inteligentes (agents) desde cero. Construye paso a paso un agente "consciente del entorno" capaz de gestionar tus correos electrónicos a través de la API de Gmail. El proyecto ha sido desarrollado por el equipo de LangChain AI y es un excelente recurso para aprender y practicar el desarrollo de agentes de IA.

Estructura del Proyecto

Componentes Principales

El proyecto se divide en 4 partes principales, cada una con un Jupyter notebook y la implementación de código correspondiente:

1. Fundamentos del Agente - Construcción de funcionalidades básicas del agente
2. Evaluación del Agente - Implementación de mecanismos de evaluación del rendimiento del agente
3. Colaboración Humano-Máquina - Integración de procesos de intervención y revisión humana
4. Sistema de Memoria - Adición de memoria a largo plazo y capacidad de aprendizaje

Estructura de Directorios

• notebooks/ - Contiene los Jupyter notebooks para la enseñanza
• src/email_assistant/ - Código de implementación principal del asistente de correo electrónico
• eval/ - Conjuntos de datos y herramientas relacionados con la evaluación
• tests/ - Suite de pruebas automatizadas

Requisitos Técnicos

Requisitos del Entorno

• Versión de Python: 3.11 o superior (para una compatibilidad óptima con LangGraph)
• Dependencias Principales: LangGraph, OpenAI API, LangSmith

Configuración de Claves API

Se requiere configurar las siguientes claves API:

• Clave API de OpenAI (para llamadas al modelo de lenguaje)
• Clave API de LangSmith (para seguimiento y evaluación)

Configuración del Entorno

# Comprobar la versión de Python
python3 --version

# Crear un entorno virtual
python3 -m venv .venv
source .venv/bin/activate

# Actualizar pip
python3 -m pip install --upgrade pip

# Instalar el proyecto (modo editable)
pip install -e .

Configuración de Variables de Entorno

# Copiar la plantilla de variables de entorno
cp .env.example .env

Configurar en el archivo .env:

LANGSMITH_API_KEY=tu_clave_api_de_langsmith
LANGSMITH_TRACING=true
LANGSMITH_PROJECT="interrupt-workshop"
OPENAI_API_KEY=tu_clave_api_de_openai

Módulos de Funcionalidad Detallados

1. Introducción a los Fundamentos de LangGraph

• Archivo: notebooks/langgraph_101.ipynb
• Contenido: Introducción a los conceptos básicos de LangGraph, incluyendo modelos de chat, llamadas a herramientas, la diferencia entre agentes y flujos de trabajo, nodos/aristas/sistema de memoria de LangGraph, y el uso de LangGraph Studio.

2. Construcción del Asistente de Correo Electrónico

• Notebook: notebooks/agent.ipynb
• Código: src/email_assistant/email_assistant.py
• Funcionalidad:
  • Combinación de pasos de clasificación de correo electrónico con el procesamiento de respuestas del agente
  • Implementación de un flujo de trabajo completo de procesamiento de correo electrónico
  • Proporciona funcionalidad de respuesta automática de correo electrónico

3. Sistema de Evaluación del Agente

• Notebook: notebooks/evaluation.ipynb
• Conjunto de Datos: eval/email_dataset.py
• Funcionalidad:
  • Utilización de Pytest y la API de evaluación de LangSmith para la evaluación
  • Implementación de LLM como mecanismo de evaluación
  • Evaluación de la precisión de las llamadas a herramientas y las decisiones de clasificación

4. Colaboración Humano-Máquina (HITL)

• Notebook: notebooks/hitl.ipynb
• Código: src/email_assistant/email_assistant_hitl.py
• Funcionalidad:
  • Integración de mecanismos de revisión humana
  • Soporte para la confirmación humana de llamadas a herramientas específicas (como enviar correos electrónicos, programar reuniones)
  • Utilización de Agent Inbox como interfaz de interacción humano-máquina

5. Sistema de Memoria

• Código: src/email_assistant/email_assistant_hitl_memory.py
• Funcionalidad:
  • Aprender y adaptarse a partir de la retroalimentación del usuario
  • Utilización de LangGraph Store para la persistencia de la memoria
  • Soporte para la configuración de preferencias personalizadas

6. Integración con Gmail

• Código: src/email_assistant/email_assistant_hitl_memory_gmail.py
• Funcionalidad:
  • Conexión real a la API de Gmail
  • Funcionalidad completa de gestión de correo electrónico
  • Soporte para la implementación en la plataforma LangGraph

Sistema de Pruebas

Suite de Pruebas Automatizadas

El proyecto incluye un sistema completo de pruebas automatizadas para verificar la corrección de la implementación del asistente de correo electrónico:

# Ejecutar pruebas de la implementación predeterminada
python tests/run_all_tests.py

# Ejecutar pruebas de una implementación específica
python tests/run_all_tests.py --implementation email_assistant_hitl

# Ejecutar pruebas de todas las implementaciones
python tests/run_all_tests.py --all

# Especificar un nombre de experimento para el seguimiento de LangSmith
python tests/run_all_tests.py --experiment-name "Custom Test Run"

Versiones de Implementación Testeables

• email_assistant - Asistente de correo electrónico básico
• email_assistant_hitl - Versión de colaboración humano-máquina
• email_assistant_hitl_memory - Versión HITL con funcionalidad de memoria
• email_assistant_hitl_memory_gmail - Versión de integración con Gmail

Métricas de Evaluación

• Inspección visual del seguimiento del agente
• Métricas de evaluación detalladas
• Análisis comparativo de diferentes implementaciones de agentes

Instrucciones de Implementación

Implementación en la Plataforma LangGraph

El proyecto soporta la implementación en la plataforma LangGraph, permitiendo la creación de servicios de agentes en un entorno de producción.

Configuración de la Herramienta Gmail

Es necesario configurar las credenciales de la API de Google siguiendo las instrucciones en src/email_assistant/tools/gmail/README.md.

Sugerencias de Ruta de Aprendizaje

1. Principiantes: Comiencen con el notebook LangGraph 101 para comprender los conceptos básicos
2. Practicantes: Completen los cuatro notebooks principales en orden, construyendo gradualmente la funcionalidad completa
3. Desarrolladores: Estudien el código de implementación en el directorio src para comprender la práctica de la ingeniería
4. Implementadores: Configuren la API de Gmail e implementen en un entorno de producción

Características Técnicas

• Aprendizaje Progresivo: De lo básico a lo avanzado, paso a paso
• Aplicación Práctica: Escenario real de procesamiento de correo electrónico
• Ingeniería Completa: Incluye pruebas, evaluación y una solución completa de implementación
• Escalabilidad: Los principios se pueden aplicar a otras tareas de agentes