Blog

Pyspur: Criador de Agentes de IA de Código Aberto

Mark Ponomarev

Mark Ponomarev

17 junho 2025

Pyspur: Criador de Agentes de IA de Código Aberto

O que é Pyspur?

Pyspur é uma plataforma de código aberto projetada para acelerar o desenvolvimento de agentes de IA, fornecendo um ambiente visual baseado em nós. Ele permite que engenheiros construam, depurem e implementem fluxos de trabalho de IA complexos, conectando componentes modulares em um canvas de arrastar e soltar.

O problema central que o Pyspur resolve é a falta de transparência e o ciclo de iteração lento comum no desenvolvimento de IA. Ele aborda o "inferno de prompts" e os "pontos cegos de fluxo de trabalho", permitindo que os desenvolvedores inspecionem as entradas e saídas de cada etapa da lógica de seus agentes em tempo real. A plataforma inclui suporte integrado para padrões avançados como Geração Aumentada por Recuperação (RAG), permite pontos de interrupção com intervenção humana e pode implementar qualquer fluxo de trabalho como uma API pronta para produção com um único clique. Em última análise, o Pyspur ajuda os engenheiros a construir sistemas de IA mais confiáveis e depuráveis mais rapidamente.

💡
Quer uma ótima ferramenta de Teste de API que gera Documentação de API linda?

Quer uma plataforma integrada e Tudo-em-Um para sua Equipe de Desenvolvedores trabalhar em conjunto com máxima produtividade?

Apidog atende a todas as suas demandas e substitui o Postman a um preço muito mais acessível!
botão

Vamos começar!

1. Configuração do Ambiente

Escolha a opção de configuração que melhor se adapta ao seu objetivo. Para desenvolvimento e experimentação local, a instalação via pip é suficiente. Para sistemas escaláveis ou de produção, a configuração baseada em Docker é recomendada, pois fornece um ambiente reproduzível e conteinerizado com uma instância dedicada de PostgreSQL.

Opção A: Instalação Local via pip

Pré-requisitos: Python 3.11+

Instalar do PyPI:

pip install pyspur

Inicializar Diretório do Projeto: Este comando cria um esqueleto de projeto, incluindo um arquivo .env para configuração.

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

Iniciar Servidor: A flag --sqlite direciona o Pyspur para usar um banco de dados SQLite local, removendo a dependência de um servidor de banco de dados separado.

pyspur serve --sqlite

Acessar UI: Navegue para http://localhost:6080 no seu navegador.

Opção B: Configuração com Docker

Pré-requisitos: Docker Engine

Executar Script de Configuração: Este comando baixa e executa um script shell que clona o repositório do Pyspur, configura o arquivo docker-compose.dev.yml e inicia a pilha de aplicativos (frontend, backend, banco de dados).

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

Acessar UI: Navegue para http://localhost:6080.

2. Vamos Construir um Fluxo de Trabalho com Pyspur

Em vez de construir do zero, vamos carregar e analisar um template existente do Pyspur. Esta abordagem fornece uma visão realista de um fluxo de trabalho não trivial.

Carregar o Template:

Análise do Fluxo de Trabalho:
Este fluxo de trabalho foi projetado para gerar uma piada e depois refiná-la. Ele usa um BestOfNNode, um componente avançado que executa um prompt de LLM N vezes, usa outra chamada de LLM para avaliar as N saídas e seleciona a melhor.

Vamos detalhar os nós principais conforme definidos em joke_generator.json:

input_node (InputNode): Este nó define o ponto de entrada do fluxo de trabalho.

JokeDrafter (BestOfNNode): Esta é a primeira etapa da criação da piada.

JokeRefiner (BestOfNNode): Este nó pega a piada rascunhada e a aprimora.

Links: O array links no JSON define o fluxo de dados:
input_node -> JokeDrafter -> JokeRefiner.

Execução e Inspeção:

3. Implementando um Pipeline RAG

Embora não faça parte do gerador de piadas, a Geração Aumentada por Recuperação (RAG) é uma capacidade crítica do Pyspur. Aqui está o processo técnico para adicionar conhecimento a um agente:

  1. Ingestão de Documentos (Collection): Navegue até a seção RAG. Ao criar uma "Document Collection" (Coleção de Documentos) e fazer upload de um arquivo (por exemplo, um PDF), o Pyspur inicia um processo de backend que analisa o documento em texto, o segmenta em pedaços configuráveis com base no comprimento do token e armazena esses pedaços com metadados de origem em seu banco de dados.
  2. Vetorização (Index): A criação de um "Vector Index" (Índice Vetorial) a partir de uma coleção aciona outro processo. O Pyspur itera por cada pedaço de texto, faz uma chamada de API para um modelo de embedding especificado (por exemplo, text-embedding-ada-002 da OpenAI) para obter uma representação vetorial e insere (upserts) esses vetores em um banco de dados vetorial configurado (por exemplo, ChromaDB, PGVector).
  3. Recuperação (Workflow Node): Em um fluxo de trabalho, o Retriever Node (Nó de Recuperação) é configurado para apontar para um Índice Vetorial específico. Em tempo de execução, sua entrada query é incorporada usando o mesmo modelo, e uma busca semântica (vizinho mais próximo aproximado) é realizada contra o banco de dados vetorial para buscar os pedaços de texto mais relevantes. Esses pedaços são então passados como contexto para um LLM downstream.

4. Implementação como uma API de Produção

Quando seu fluxo de trabalho estiver finalizado, você pode expô-lo como um endpoint HTTP seguro.

Iniciar Implementação: Clique no botão "Deploy" (Implementar) na barra de navegação superior.

Selecionar Tipo de Chamada de API:

Integrar com Sua Aplicação:
O modal de implementação gera código cliente. O corpo da requisição POST deve ser um objeto JSON onde a chave initial_inputs contém um objeto cujas chaves correspondem ao title dos seus nós de entrada.

Exemplo de Cliente Python (para o Gerador de Piadas):

import requests
import json
import time

PYSUR_HOST = "http://localhost:6080"
WORKFLOW_ID = "your_workflow_id_here" # Obtenha isto do modal de deploy

# As chaves neste dicionário devem corresponder ao 'output_schema' do input_node
payload = {
    "initial_inputs": {
        "input_node": {
            "topic": "Python decorators",
            "audience": "Senior Software Engineers"
        }
    }
}

# 1. Iniciar a execução não bloqueante
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 iniciado com run_id: {run_id}")

# 2. Consultar o resultado
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"Status atual: {status}")
    if status in ["COMPLETED", "FAILED"]:
        print("Saída Final:")
        print(json.dumps(data.get("outputs"), indent=2))
        break
    time.sleep(2)

Conclusão

Pyspur oferece um ambiente robusto, transparente e tecnicamente fundamentado para o desenvolvimento de agentes de IA. Ao abstrair operações individuais em nós modulares e fornecer um canvas visual, ele permite que os engenheiros se concentrem na lógica de alto nível de seus agentes. O verdadeiro poder da plataforma reside em sua profunda capacidade de inspeção — permitindo rastrear o fluxo de dados e depurar a E/S de cada componente — e sua transição perfeita de protótipo visual para API pronta para produção. A mudança de agentes simples de uma única chamada para fluxos de trabalho complexos de várias etapas utilizando padrões como Best-of-N ou RAG não é apenas possível, mas intuitiva. Ao construir com Pyspur, você não está apenas conectando caixas; você está projetando sistemas de IA confiáveis, depuráveis e escaláveis.

💡
Quer uma ótima ferramenta de Teste de API que gera Documentação de API linda?

Quer uma plataforma integrada e Tudo-em-Um para sua Equipe de Desenvolvedores trabalhar em conjunto com máxima produtividade?

Apidog atende a todas as suas demandas e substitui o Postman a um preço muito mais acessível!
botão

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar