Plugins :: Arquitectura Desacoplada, Contratos y Ciclo de Vida del SDK (jg_agente_sdk)

"Un runtime de inteligencia artificial monolítico, donde cada nueva herramienta o integración de negocio requiere recompilar el grafo cognitivo o desplegar una nueva versión del core, está condenado al estancamiento y a la fragilidad operativa. La extensibilidad real exige contratos inmutables, aislamiento de procesos y herramientas de desarrollo soberanas."

Repositorio oficial e índice público de empaquetado:
📦 PyPI: pypi.org/project/jg-agente-sdk
🔗 GitLab: gitlab.com/javiergalvez-ia/jg_agente_sdk

1. El Concepto de Plugin en la Plataforma jg-ia

En la plataforma javiergalvez-ia, un Plugin no es un script arbitrario ni un middleware acoplado al runtime. Es un paquete autónomo y versionado que implementa capacidades funcionales y de dominio (tools, motores de observación o verificadores) consumidas por el agente cognitivo a través de contratos estrictos de tipo.

Principios Fundamentales del Modelo de Plugins:

1. Desacoplamiento Absoluto del Core: El desarrollador de un plugin nunca toca el grafo de 10 nodos de LangGraph, los checkpointers de base de datos (DualPostgresSaver) ni los controladores de FastAPI.
2. Cero Dependencias Pesadas: El SDK no arrastra librerías de inferencia pesadas, PyTorch ni drivers nativos de base de datos. Depende exclusivamente de pydantic >= 2.5.0, httpx >= 0.25.0 y Python >= 3.11.
3. Seguridad y Tipado Estricto: Toda herramienta expone esquemas validados en tiempo de diseño con Pydantic v2, previniendo inyecciones de parámetros y garantizando metadatos claros para el function calling del modelo de lenguaje.
4. Ciclo de Vida Simétrico y Compensable: Cada mutación crítica puede declarar funciones de compensación reversibles (rollback_func), integrándose de forma natural con el orquestador de transacciones Saga del runtime.

2. Contratos Canónicos del SDK con Pydantic v2

El paquete jg_agente_sdk actúa como la Fuente Única de Verdad (Single Source of Truth - SSOT) del sistema. Define las estructuras que gobiernan la interoperabilidad entre planos.

2.1 Definición Declarativa de Herramientas (AgentTool)

Toda capacidad ejecutable se encapsula en una instancia inmutable de AgentTool (jg_sdk.contracts):

from typing import Any, Callable
from pydantic import BaseModel, Field
from jg_sdk.contracts import AgentTool, RiskLevel, ToolType, ToolResult

class NetworkDiagnosticsArgs(BaseModel):
    target_host: str = Field(description="Dirección IP o FQDN del servidor destino")
    port: int = Field(default=443, ge=1, le=65535, description="Puerto TCP a verificar")

def ping_host(target_host: str, port: int = 443) -> ToolResult:
    # Lógica de verificación...
    return ToolResult(
        success=True, 
        output={"status": "reachable", "latency_ms": 14.2}
    )

network_tool = AgentTool(
    name="network_ping",
    description="Comprueba la conectividad TCP y latencia contra un host remoto.",
    category="networking",
    version="1.0.0",
    args_schema=NetworkDiagnosticsArgs,
    func=ping_host,
    risk_level=RiskLevel.LOW,
    tool_type=ToolType.OBSERVER,
    read_only=True,
    reversible=False,
    timeout_sec=10.0,
)

2.2 Validación Estricta de Reversibilidad y Patrón Saga

El contrato AgentTool incluye validadores de modelo en tiempo de carga: si una herramienta declara reversible = True, el SDK exige de manera obligatoria una función no nula en rollback_func. En caso contrario, la carga del plugin falla de forma inmediata en el arranque (fail-fast):

def deploy_service(service_name: str) -> ToolResult:
    # Despliegue mutacional...
    return ToolResult(
        success=True,
        output="Servicio desplegado",
        rollback_context={"container_id": "c-98712", "service": service_name}
    )

def rollback_deploy(context: dict) -> ToolResult:
    # Compensación Saga garantizada...
    container_id = context.get("container_id")
    # Terminar y limpiar contenedor...
    return ToolResult(success=True, output=f"Contenedor {container_id} destruido")

deploy_tool = AgentTool(
    name="deploy_container",
    description="Despliega una nueva réplica del microservicio.",
    args_schema=DeployArgs,
    func=deploy_service,
    risk_level=RiskLevel.HIGH,
    tool_type=ToolType.ACTUATOR,
    read_only=False,
    reversible=True,
    rollback_func=rollback_deploy,  # Obligatorio por contrato
)

3. Instalación del SDK desde PyPI

El SDK oficial se distribuye en el índice global de paquetes Python (PyPI):

# Instalación estándar
pip install jg-agente-sdk

# O mediante gestor de paquetes moderno (uv / poetry)
uv add jg-agente-sdk

Una vez instalado, el entorno dispone de dos comandos de consola equivalentes: jg y jg-sdk.

4. Scaffolding Determinista con la CLI (jg init)

Para evitar errores de estructura o boilerplate manual, la utilidad de consola permite generar el andamiaje completo de un nuevo plugin con un único comando:

# Inicializar un nuevo plugin con plantilla estándar
jg init mi_plugin --template standard --author "Mi Empresa" --description "Plugin de métricas"

# O mediante el subcomando explícito
jg plugin init mi_plugin --template full

Plantillas Disponibles:

• minimal: Estructura ligera con una sola herramienta de lectura y archivo de manifiesto.
• standard (por defecto): Incluye jerarquía de paquetes, modelos de argumentos Pydantic v2, configuración de empaquetado (pyproject.toml) y suite de tests con pytest.
• full: Estructura empresarial con soporte para herramientas reversibles, funciones de compensación, motores de observación (ObserverEngine), validación de contratos y entorno Docker Compose preconfigurado.

Estructura Generada:

jg_plugin_mi_plugin/
├── pyproject.toml              # Metadatos del paquete y dependencias
├── README.md                   # Documentación funcional
├── docker-compose.yml          # Stack de emulación local
├── jg_plugin_mi_plugin/
│   ├── __init__.py
│   ├── plugin.py               # Clase principal que registra herramientas
│   ├── contracts.py            # Esquemas de entrada/salida Pydantic v2
│   └── tools/                  # Funciones invocables individuales
└── tests/
    ├── __init__.py
    └── test_plugin.py          # Batería de pruebas de contrato

5. Testing Aislado sin Infraestructura (MockPluginRunner)

Una de las ventajas competitivas de jg_agente_sdk es que no requiere levantar PostgreSQL, Docker ni FastAPI para probar exhaustivamente las herramientas.

El harness MockPluginRunner emula el ciclo de vida de invocación del agente directamente en memoria:

# tests/test_plugin.py
import pytest
from jg_sdk.testing import MockPluginRunner
from jg_plugin_mi_plugin.plugin import MiPlugin

@pytest.mark.asyncio
async def test_herramienta_ping():
    plugin = MiPlugin()
    async with MockPluginRunner(plugin) as runner:
        tool = runner.get_tool("network_ping")
        result = tool.run(target_host="1.1.1.1", port=53)
        
        assert result.success is True
        assert result.output["status"] == "reachable"

Para ejecutar las pruebas en el entorno virtual local:

# Ejecutar tests directamente mediante la CLI
jg test

# O ejecutar dentro del virtualenv gestionado
jg dev pytest

6. Emulación en Tiempo Real con Docker (jg run)

Cuando el plugin está programado y los tests unitarios pasan con éxito, la CLI permite desplegar un entorno de pruebas completo, idéntico a producción, en un solo paso mediante Docker Compose:

# Levantar el stack completo autónomo
jg run

# O alternativamente:
jg plugin run

¿Qué ocurre al ejecutar jg run?

1. Aprovisionamiento Automático: Se descarga y arranca una imagen del agente (:8881), una base de datos PostgreSQL dedicada y el Dashboard Web HITL (:8880).
2. Migraciones Troncales Deterministas: El script de entrada (entrypoint.sh) ejecuta automáticamente alembic upgrade head, creando las tablas maestras core_executions y core_audit_records antes de exponer los endpoints de FastAPI.
3. Inspección en Tiempo Real: Puedes abrir el navegador en http://localhost:8880 para emitir prompts al agente, observar el árbol cognitivo y validar cómo el modelo de lenguaje decide invocar las herramientas de tu nuevo plugin.
4. Recarga en Caliente (jg reload): Si modificas el código de tus herramientas, puedes forzar la recarga del plugin en el contenedor sin reiniciar la base de datos:

   jg reload
   

5. Parada y Limpieza:

   jg run --down
   

7. Vinculación a Agentes de Producción (jg link)

Si tienes una instancia del agente troncal (jg_agente) ejecutándose en tu máquina o clúster, puedes vincular el plugin mediante enlaces simbólicos portables con salvaguardas perimetrales:

# Enlazar plugin en desarrollo a la instancia del agente
jg link jg_plugin_mi_plugin -t /ruta/a/jg_agente/plugins

# Desvincular de forma limpia
jg unlink jg_plugin_mi_plugin -t /ruta/a/jg_agente/plugins

Políticas de Mínimo Privilegio: Si un plugin con capacidades de red pública abierta intenta enlazarse junto a herramientas con privilegios de sistema crítico (ej. proxy de socket Docker), el CLI bloquea la vinculación por defecto alertando al operador sobre una posible brecha de confianza.

8. ¿Necesitas un Plugin a Medida?

Si tu organización requiere conectar un sistema empresarial propietario (SAP, Salesforce, ERP legado, pipelines industriales o bases de datos vectoriales) al ecosistema javiergalvez-ia, disponemos de servicio de ingeniería especializada y desarrollo llave en mano:

• Auditoría de Seguridad y SSRF: Diseño de herramientas de red con socket pinning determinista.
• Transacciones Reversibles: Implementación de patrones Saga con compensación obligatoria.
• Soporte HITL: Integración con flujos de aprobación humana y auditoría criptográfica.

💡 Solicitar Desarrollo de Plugin a Medida o explorar nuestros Casos de Uso en Producción.