Blog

오픈소스 AI 에이전트 빌더: Pyspur

Mark Ponomarev

Mark Ponomarev

17 June 2025

오픈소스 AI 에이전트 빌더: Pyspur

Pyspur란 무엇인가요?

Pyspur는 시각적인 노드 기반 환경을 제공하여 AI 에이전트 개발 속도를 높이기 위해 설계된 오픈 소스 플랫폼입니다. 엔지니어는 드래그 앤 드롭 캔버스에서 모듈식 구성 요소를 연결하여 복잡한 AI 워크플로우를 구축하고 디버깅하며 배포할 수 있습니다.

Pyspur가 해결하는 핵심 문제는 AI 개발에서 흔히 발생하는 투명성 부족과 느린 반복 주기입니다. 개발자가 에이전트 로직의 모든 단계에서 입력과 출력을 실시간으로 검사할 수 있도록 하여 "프롬프트 지옥(prompt hell)" 및 "워크플로우 사각지대(workflow blindspots)" 문제를 해결합니다. 이 플랫폼에는 검색 증강 생성(RAG)과 같은 고급 패턴에 대한 내장 지원이 포함되어 있으며, 휴먼 인 더 루프(human-in-the-loop) 중단점을 허용하고, 단 한 번의 클릭으로 모든 워크플로우를 프로덕션 준비 API로 배포할 수 있습니다. 궁극적으로 Pyspur는 엔지니어가 보다 안정적이고 디버깅 가능한 AI 시스템을 더 빠르게 구축하도록 돕습니다.

💡
Want a great API Testing tool that generates beautiful API Documentation?

Want an integrated, All-in-One platform for your Developer Team to work together with maximum productivity?

Apidog delivers all your demands, and replaces Postman at a much more affordable price!
button

시작해 보겠습니다!

1. 환경 설정

목표에 가장 적합한 설정 옵션을 선택하세요. 로컬 개발 및 실험에는 pip 설치로 충분합니다. 확장 가능한 또는 프로덕션 시스템에는 전용 PostgreSQL 인스턴스가 포함된 재현 가능한 컨테이너화된 환경을 제공하므로 Docker 기반 설정이 권장됩니다.

옵션 A: 로컬 pip 설치

필수 조건: Python 3.11+

PyPI에서 설치:

pip install pyspur

프로젝트 디렉토리 초기화: 이 명령은 구성을 위한 .env 파일을 포함하여 프로젝트 스캐폴드를 생성합니다.

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

서버 시작: --sqlite 플래그는 Pyspur가 별도의 데이터베이스 서버에 대한 종속성 없이 로컬 SQLite 데이터베이스를 사용하도록 지시합니다.

pyspur serve --sqlite

UI 접근: 브라우저에서 http://localhost:6080으로 이동합니다.

옵션 B: Docker 설정

필수 조건: Docker Engine

설정 스크립트 실행: 이 명령은 Pyspur 저장소를 복제하고 docker-compose.dev.yml 파일을 구성하며 애플리케이션 스택(프론트엔드, 백엔드, 데이터베이스)을 시작하는 셸 스크립트를 다운로드하여 실행합니다.

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

UI 접근: http://localhost:6080으로 이동합니다.

2. Pyspur로 워크플로우 구축하기

처음부터 구축하는 대신 기존 Pyspur 템플릿을 로드하고 분석할 것입니다. 이 접근 방식은 사소하지 않은 워크플로우를 현실적으로 보여줍니다.

템플릿 로드:

워크플로우 분석:
이 워크플로우는 농담을 생성한 다음 이를 개선하도록 설계되었습니다. BestOfNNode를 사용하는데, 이는 LLM 프롬프트를 N번 실행하고 다른 LLM 호출을 사용하여 N개의 출력을 평가하며 가장 좋은 것을 선택하는 고급 구성 요소입니다.

joke_generator.json에 정의된 주요 노드를 살펴보겠습니다.

input_node (InputNode): 이 노드는 워크플로우의 진입점을 정의합니다.

JokeDrafter (BestOfNNode): 이것은 농담 생성의 첫 번째 단계입니다.

JokeRefiner (BestOfNNode): 이 노드는 초안 농담을 가져와 개선합니다.

링크: JSON의 links 배열은 데이터 흐름을 정의합니다.
input_node -> JokeDrafter -> JokeRefiner.

실행 및 검사:

3. RAG 파이프라인 구현

농담 생성기의 일부는 아니지만, 검색 증강 생성(RAG)은 중요한 Pyspur 기능입니다. 에이전트에 지식을 추가하는 기술적 과정은 다음과 같습니다.

  1. 문서 수집 (Collection): RAG 섹션으로 이동합니다. "Document Collection"을 생성하고 파일(예: PDF)을 업로드하면 Pyspur는 문서를 텍스트로 구문 분석하고, 토큰 길이에 따라 구성 가능한 청크로 분할하며, 소스 메타데이터와 함께 데이터베이스에 저장하는 백엔드 프로세스를 시작합니다.
  2. 벡터화 (Index): 컬렉션에서 "Vector Index"를 생성하면 다른 프로세스가 트리거됩니다. Pyspur는 각 텍스트 청크를 반복하고, 지정된 임베딩 모델(예: OpenAI의 text-embedding-ada-002)에 API 호출을 하여 벡터 표현을 가져오고, 구성된 벡터 데이터베이스(예: ChromaDB, PGVector)에 이 벡터를 upsert합니다.
  3. 검색 (Workflow Node): 워크플로우에서 Retriever Node는 특정 Vector Index를 가리키도록 구성됩니다. 런타임 시 입력 query는 동일한 모델을 사용하여 임베딩되고, 가장 관련성이 높은 텍스트 청크를 가져오기 위해 벡터 데이터베이스에 대해 의미론적 검색(근사 최근접 이웃)이 수행됩니다. 이 청크는 다운스트림 LLM에 컨텍스트로 전달됩니다.

4. 프로덕션 API로 배포

워크플로우가 완성되면 보안 HTTP 엔드포인트로 노출할 수 있습니다.

배포 시작: 상단 탐색 모음에서 "Deploy" 버튼을 클릭합니다.

API 호출 유형 선택:

애플리케이션 통합:
배포 모달은 클라이언트 코드를 생성합니다. POST 요청의 본문은 initial_inputs 키가 입력 노드의 title과 일치하는 키를 포함하는 객체를 포함하는 JSON 객체여야 합니다.

예시 Python 클라이언트 (농담 생성기용):

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)

결론

Pyspur는 AI 에이전트 개발을 위한 견고하고 투명하며 기술적으로 기반이 잘 갖춰진 환경을 제공합니다. 개별 작업을 모듈식 노드로 추상화하고 시각적 캔버스를 제공함으로써 엔지니어가 에이전트의 높은 수준 로직에 집중할 수 있도록 합니다. 이 플랫폼의 진정한 힘은 데이터 흐름을 추적하고 각 구성 요소의 I/O를 디버깅할 수 있는 심층적인 검사 가능성 및 시각적 프로토타입에서 프로덕션 준비 API로의 원활한 전환에 있습니다. 단순한 단일 호출 에이전트에서 Best-of-N 또는 RAG와 같은 패턴을 활용하는 복잡하고 다단계적인 워크플로우로의 전환은 가능할 뿐만 아니라 직관적입니다. Pyspur로 구축함으로써 단순히 상자를 연결하는 것이 아니라 안정적이고 디버깅 가능하며 확장 가능한 AI 시스템을 엔지니어링하는 것입니다.

💡
Want a great API Testing tool that generates beautiful API Documentation?

Want an integrated, All-in-One platform for your Developer Team to work together with maximum productivity?

Apidog delivers all your demands, and replaces Postman at a much more affordable price!
button

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드