Blog

Pyspur: Constructor de Agentes de IA de Código Abierto

Mark Ponomarev

Mark Ponomarev

17 June 2025

Pyspur: Constructor de Agentes de IA de Código Abierto

¿Qué es Pyspur?

Pyspur es una plataforma de código abierto diseñada para acelerar el desarrollo de agentes de IA al proporcionar un entorno visual basado en nodos. Permite a los ingenieros construir, depurar e implementar flujos de trabajo de IA complejos conectando componentes modulares en un lienzo de arrastrar y soltar.

El problema principal que resuelve Pyspur es la falta de transparencia y el ciclo de iteración lento común en el desarrollo de IA. Aborda el "infierno de prompts" y los "puntos ciegos del flujo de trabajo" permitiendo a los desarrolladores inspeccionar las entradas y salidas de cada paso en la lógica de su agente en tiempo real. La plataforma incluye soporte integrado para patrones avanzados como la Generación Aumentada por Recuperación (RAG), permite puntos de interrupción con intervención humana y puede implementar cualquier flujo de trabajo como una API lista para producción con un solo clic. En última instancia, Pyspur ayuda a los ingenieros a construir sistemas de IA más fiables y depurables más rápido.

💡
¿Quieres una excelente herramienta de Pruebas de API que genere documentación de API hermosa?

¿Quieres una plataforma integrada, Todo en Uno, para que tu Equipo de Desarrolladores trabaje con máxima productividad?

¡Apidog satisface todas tus demandas y reemplaza a Postman a un precio mucho más asequible!
button

¡Comencemos!

1. Configuración del Entorno

Elige la opción de configuración que mejor se adapte a tu objetivo. Para desarrollo local y experimentación, la instalación con pip es suficiente. Para sistemas escalables o de producción, se recomienda la configuración basada en Docker, ya que proporciona un entorno reproducible y en contenedores con una instancia dedicada de PostgreSQL.

Opción A: Instalación Local con pip

Requisitos previos: Python 3.11+

Instalar desde PyPI:

pip install pyspur

Inicializar Directorio del Proyecto: Este comando crea la estructura básica de un proyecto, incluyendo un archivo .env para la configuración.

pyspur init my-pyspur-project && cd my-pyspur-project

Iniciar Servidor: La bandera --sqlite indica a Pyspur que use una base de datos SQLite local, eliminando la dependencia de un servidor de base de datos separado.

pyspur serve --sqlite

Acceder a la Interfaz de Usuario: Navega a http://localhost:6080 en tu navegador.

Opción B: Configuración con Docker

Requisitos previos: Docker Engine

Ejecutar Script de Configuración: Este comando descarga y ejecuta un script de shell que clona el repositorio de Pyspur, configura el archivo docker-compose.dev.yml e inicia la pila de la aplicación (frontend, backend, base de datos).

curl -fsSL https://raw.githubusercontent.com/PySpur-com/pyspur/main/start_pyspur_docker.sh | bash -s pyspur-project

Acceder a la Interfaz de Usuario: Navega a http://localhost:6080.

2. Construyamos un Flujo de Trabajo con Pyspur

En lugar de construir desde cero, cargaremos y analizaremos una plantilla existente de Pyspur. Este enfoque proporciona una visión realista de un flujo de trabajo no trivial.

Cargar la Plantilla:

Análisis del Flujo de Trabajo:
Este flujo de trabajo está diseñado para generar un chiste y luego refinarlo. Utiliza un BestOfNNode, un componente avanzado que ejecuta un prompt de LLM N veces, utiliza otra llamada a LLM para calificar las N salidas y selecciona la mejor.

Analicemos los nodos clave definidos en joke_generator.json:

input_node (InputNode): Este nodo define el punto de entrada del flujo de trabajo.

JokeDrafter (BestOfNNode): Esta es la primera etapa de la creación del chiste.

JokeRefiner (BestOfNNode): Este nodo toma el borrador del chiste y lo mejora.

Enlaces: El array links en el JSON define el flujo de datos:
input_node -> JokeDrafter -> JokeRefiner.

Ejecución e Inspección:

3. Implementando un Pipeline RAG

Aunque no forma parte del generador de chistes, la Generación Aumentada por Recuperación (RAG) es una capacidad crítica de Pyspur. Aquí está el proceso técnico para añadir conocimiento a un agente:

  1. Ingestión de Documentos (Colección): Navega a la sección RAG. Cuando creas una "Colección de Documentos" y subes un archivo (por ejemplo, un PDF), Pyspur inicia un proceso en el backend que analiza el documento en texto, lo segmenta en fragmentos configurables basados en la longitud de tokens, y almacena estos fragmentos con metadatos de origen en su base de datos.
  2. Vectorización (Índice): Crear un "Índice Vectorial" a partir de una colección desencadena otro proceso. Pyspur itera a través de cada fragmento de texto, realiza una llamada a la API a un modelo de embedding especificado (por ejemplo, text-embedding-ada-002 de OpenAI) para obtener una representación vectorial, e inserta/actualiza estos vectores en una base de datos vectorial configurada (por ejemplo, ChromaDB, PGVector).
  3. Recuperación (Nodo de Flujo de Trabajo): En un flujo de trabajo, el Nodo Retriever está configurado para apuntar a un Índice Vectorial específico. En tiempo de ejecución, su entrada query se embebe utilizando el mismo modelo, y se realiza una búsqueda semántica (vecino más cercano aproximado) contra la base de datos vectorial para obtener los fragmentos de texto más relevantes. Estos fragmentos se pasan luego como contexto a un LLM posterior.

4. Implementación como API de Producción

Cuando tu flujo de trabajo esté finalizado, puedes exponerlo como un endpoint HTTP seguro.

Iniciar Implementación: Haz clic en el botón "Deploy" (Implementar) en la barra de navegación superior.

Seleccionar Tipo de Llamada a la API:

Integrar con Tu Aplicación:
La ventana modal de implementación genera código cliente. El cuerpo de la solicitud POST debe ser un objeto JSON donde la clave initial_inputs contenga un objeto cuyas claves coincidan con el title de tus nodos de entrada.

Ejemplo de Cliente Python (para el Generador de Chistes):

import requests
import json
import time

PYSUR_HOST = "http://localhost:6080"
WORKFLOW_ID = "your_workflow_id_here" # Get this from the deploy modal

# The keys in this dict must match the 'output_schema' of the input_node
payload = {
    "initial_inputs": {
        "input_node": {
            "topic": "Python decorators",
            "audience": "Senior Software Engineers"
        }
    }
}

# 1. Start the non-blocking run
start_url = f"{PYSUR_HOST}/api/wf/{WORKFLOW_ID}/start_run/?run_type=non_blocking"
start_resp = requests.post(start_url, json=payload)
run_id = start_resp.json()['id']
print(f"Workflow started with run_id: {run_id}")

# 2. Poll for the result
status_url = f"{PYSUR_HOST}/api/runs/{run_id}/status/"
while True:
    status_resp = requests.get(status_url)
    data = status_resp.json()
    status = data.get("status")
    print(f"Current status: {status}")
    if status in ["COMPLETED", "FAILED"]:
        print("Final Output:")
        print(json.dumps(data.get("outputs"), indent=2))
        break
    time.sleep(2)

Conclusión

Pyspur proporciona un entorno robusto, transparente y técnicamente sólido para el desarrollo de agentes de IA. Al abstraer operaciones individuales en nodos modulares y proporcionar un lienzo visual, permite a los ingenieros centrarse en la lógica de alto nivel de sus agentes. El verdadero poder de la plataforma reside en su profunda capacidad de inspección —permitiéndote rastrear el flujo de datos y depurar la entrada/salida de cada componente— y su transición fluida de prototipo visual a API lista para producción. El paso de agentes simples de una sola llamada a flujos de trabajo complejos de múltiples etapas que utilizan patrones como Best-of-N o RAG no solo es posible, sino intuitivo. Al construir con Pyspur, no solo estás conectando cajas; estás diseñando sistemas de IA fiables, depurables y escalables.

💡
¿Quieres una excelente herramienta de Pruebas de API que genere documentación de API hermosa?

¿Quieres una plataforma integrada, Todo en Uno, para que tu Equipo de Desarrolladores trabaje con máxima productividad?

¡Apidog satisface todas tus demandas y reemplaza a Postman a un precio mucho más asequible!
button

Practica el diseño de API en Apidog

Descubre una forma más fácil de construir y usar APIs

Registrarse gratisDescargar