Pyspur: Pembuat Agen AI Open Source

Apa itu Pyspur?

Pyspur adalah platform sumber terbuka yang dirancang untuk mempercepat pengembangan agen AI dengan menyediakan lingkungan berbasis node yang visual. Ini memungkinkan insinyur untuk membangun, men-debug, dan menerapkan alur kerja AI yang kompleks dengan menghubungkan komponen modular pada kanvas drag-and-drop.

Drag & Drop to build AI Agents.

And deploy to API in one click with Nocode.

100% Opensource. pic.twitter.com/iPEJEzIHVI

— Shubham Saboo (@Saboo_Shubham_) December 19, 2024

Masalah inti yang dipecahkan Pyspur adalah kurangnya transparansi dan siklus iterasi yang lambat yang umum dalam pengembangan AI. Ini mengatasi "prompt hell" dan "workflow blindspots" dengan memungkinkan pengembang untuk memeriksa input dan output dari setiap langkah dalam logika agen mereka secara real-time. Platform ini mencakup dukungan bawaan untuk pola-pola canggih seperti Retrieval-Augmented Generation (RAG), memungkinkan titik henti (breakpoints) human-in-the-loop, dan dapat menerapkan alur kerja apa pun sebagai API siap produksi dengan satu klik. Pada akhirnya, Pyspur membantu insinyur membangun sistem AI yang lebih andal dan mudah di-debug dengan lebih cepat.

We’re thrilled to share that MCP support is coming soon to Apidog! 🚀

Apidog MCP Server lets you feed API docs directly to Agentic AI, supercharging your vibe coding experience! Whether you're using Cursor, Cline, or Windsurf - it'll make your dev process faster and smoother.… pic.twitter.com/ew8U38mU0K

— Apidog (@ApidogHQ) March 19, 2025

Mari kita mulai!

1. Pengaturan Lingkungan

Pilih opsi pengaturan yang paling sesuai dengan tujuan Anda. Untuk pengembangan dan eksperimen lokal, instalasi pip sudah cukup. Untuk sistem yang dapat diskalakan atau produksi, pengaturan berbasis Docker direkomendasikan karena menyediakan lingkungan yang dapat direproduksi dan terkontainerisasi dengan instance PostgreSQL khusus.

Opsi A: Instalasi pip Lokal

Prasyarat: Python 3.11+

Instal dari PyPI:

pip install pyspur

Inisialisasi Direktori Proyek: Perintah ini membuat kerangka proyek, termasuk file .env untuk konfigurasi.

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

Luncurkan Server: Flag --sqlite mengarahkan Pyspur untuk menggunakan database SQLite lokal, menghilangkan ketergantungan pada server database terpisah.

pyspur serve --sqlite

Akses UI: Navigasikan ke http://localhost:6080 di browser Anda.

Opsi B: Pengaturan Docker

Prasyarat: Docker Engine

Jalankan Skrip Pengaturan: Perintah ini mengunduh dan menjalankan skrip shell yang mengkloning repositori Pyspur, mengonfigurasi file docker-compose.dev.yml, dan meluncurkan tumpukan aplikasi (frontend, backend, database).

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

Akses UI: Navigasikan ke http://localhost:6080.

2. Mari Bangun Alur Kerja dengan Pyspur

Alih-alih membangun dari awal, kita akan memuat dan menganalisis template Pyspur yang sudah ada. Pendekatan ini memberikan gambaran realistis tentang alur kerja yang tidak sepele.

Muat Template:

• Di dasbor Pyspur, klik "New Spur".
• Di modal yang muncul, pilih tab "Templates".
• Pilih template "Joke Generator". Kanvas akan terisi dengan alur kerja yang sudah dibangun sebelumnya.

Analisis Alur Kerja:
Alur kerja ini dirancang untuk menghasilkan lelucon dan kemudian memperbaikinya. Ini menggunakan BestOfNNode, komponen canggih yang menjalankan prompt LLM sebanyak N kali, menggunakan panggilan LLM lain untuk menilai N output, dan memilih yang terbaik.

Mari kita bedah node-node kunci seperti yang didefinisikan dalam joke_generator.json:

input_node (InputNode): Node ini mendefinisikan titik masuk alur kerja.

• config.output_schema: { "topic": "string", "audience": "string" }
• Ini menentukan bahwa alur kerja memerlukan dua input string: topic (topik) lelucon dan audience (audiens) yang dituju.

JokeDrafter (BestOfNNode): Ini adalah tahap pertama pembuatan lelucon.

• config.system_message: "You are a stand-up comedian who uses dark humor like Ricky Gervais or Jimmy Carr..."
• config.user_message: "Your audience is: {{input_node.audience}}\nThe topic should be about {{input_node.topic}}"
• Template Jinja2 ini secara dinamis menyisipkan data dari input_node.
• config.samples: 10
• Ini menginstruksikan node untuk menghasilkan 10 draf lelucon.
• config.rating_prompt: "Rate the following joke on a scale from 0 to 10..."
• Setelah menghasilkan 10 lelucon, prompt ini digunakan agar LLM menilai masing-masing lelucon. Node kemudian memilih lelucon dengan peringkat tertinggi.
• config.output_schema: { "initial_joke": "string" }
• Output node adalah satu string: lelucon terbaik dari 10 sampel.

JokeRefiner (BestOfNNode): Node ini mengambil draf lelucon dan memperbaikinya.

• config.system_message: "Your goal is to refine a joke to make it more vulgar and concise..."
• config.user_message: {{JokeDrafter.initial_joke}}
• Yang penting, input node ini adalah output dari node JokeDrafter.
• config.samples: 3
• Ini menghasilkan 3 versi lelucon awal yang diperbaiki.
• Ini juga menggunakan prompt penilaian untuk memilih yang terbaik dari tiga perbaikan tersebut.
• config.output_schema: { "final_joke": "string" }

Links: Array links dalam JSON mendefinisikan aliran data:
input_node -> JokeDrafter -> JokeRefiner.

Eksekusi dan Inspeksi:

• Di panel pengujian di sebelah kanan, gunakan input pengujian yang sudah terisi atau buat sendiri (misalnya, Topik: "Asisten AI", Audiens: "Pengembang").
• Klik Run.
• Saat alur kerja dieksekusi, klik node JokeDrafter. Anda dapat memeriksa run_data-nya, yang akan menampilkan semua 10 sampel yang dihasilkan dan peringkat yang sesuai, memberi Anda pandangan transparan ke dalam "proses berpikir" agen.
• Lelucon akhir yang sudah diperbaiki akan tersedia di output node JokeRefiner.

3. Mengimplementasikan Pipeline RAG

Meskipun bukan bagian dari generator lelucon, Retrieval-Augmented Generation (RAG) adalah kemampuan penting Pyspur. Berikut adalah proses teknis untuk menambahkan pengetahuan ke agen:

1. Penyerapan Dokumen (Collection): Navigasikan ke bagian RAG. Saat Anda membuat "Document Collection" dan mengunggah file (misalnya, PDF), Pyspur memulai proses backend yang mengurai dokumen menjadi teks, membaginya menjadi potongan-potongan yang dapat dikonfigurasi berdasarkan panjang token, dan menyimpan potongan-potongan ini dengan metadata sumber di databasenya.
2. Vektorisasi (Index): Membuat "Vector Index" dari sebuah koleksi memicu proses lain. Pyspur mengiterasi setiap potongan teks, melakukan panggilan API ke model embedding yang ditentukan (misalnya, text-embedding-ada-002 dari OpenAI) untuk mendapatkan representasi vektor, dan memasukkan (upsert) vektor-vektor ini ke dalam database vektor yang dikonfigurasi (misalnya, ChromaDB, PGVector).
3. Retrieval (Workflow Node): Dalam alur kerja, Retriever Node dikonfigurasi untuk menunjuk ke Vector Index tertentu. Saat runtime, input query-nya di-embed menggunakan model yang sama, dan pencarian semantik (tetangga terdekat perkiraan) dilakukan terhadap database vektor untuk mengambil potongan teks yang paling relevan. Potongan-potongan ini kemudian diteruskan sebagai konteks ke LLM hilir.

4. Penerapan sebagai API Produksi

Setelah alur kerja Anda selesai, Anda dapat mengeksposnya sebagai endpoint HTTP yang aman.

Mulai Penerapan: Klik tombol "Deploy" di bilah navigasi atas.

Pilih Jenis Panggilan API:

• Blocking (Sinkron): Untuk alur kerja yang berjalan cepat. Klien menerima hasil dalam respons HTTP yang sama.
• Endpoint: POST /api/wf/{workflow_id}/run/?run_type=blocking
• Non-Blocking (Asinkron): Untuk alur kerja yang berjalan lama (seperti generator lelucon kita dengan 10+ panggilan LLM). Klien segera menerima run_id dan harus melakukan polling endpoint terpisah untuk hasilnya. Ini mencegah timeout klien.
• Start Endpoint: POST /api/wf/{workflow_id}/start_run/?run_type=non_blocking
• Status Endpoint: GET /api/runs/{run_id}/status/

Integrasikan dengan Aplikasi Anda:
Modal penerapan menghasilkan kode klien. Body permintaan POST harus berupa objek JSON di mana kunci initial_inputs berisi objek yang kuncinya cocok dengan title node input Anda.

Contoh Klien Python (untuk Generator Lelucon):

import requests
import json
import time

PYSUR_HOST = "http://localhost:6080"
WORKFLOW_ID = "your_workflow_id_here" # Dapatkan ini dari modal deploy

# Kunci dalam dict ini harus cocok dengan 'output_schema' dari input_node
payload = {
    "initial_inputs": {
        "input_node": {
            "topic": "Python decorators",
            "audience": "Senior Software Engineers"
        }
    }
}

# 1. Mulai eksekusi non-blocking
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"Alur kerja dimulai dengan run_id: {run_id}")

# 2. Lakukan polling untuk hasilnya
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 saat ini: {status}")
    if status in ["COMPLETED", "FAILED"]:
        print("Output Akhir:")
        print(json.dumps(data.get("outputs"), indent=2))
        break
    time.sleep(2)

Kesimpulan

Pyspur menyediakan lingkungan yang kuat, transparan, dan berbasis teknis untuk pengembangan agen AI. Dengan mengabstraksi operasi individu menjadi node modular dan menyediakan kanvas visual, ini memungkinkan insinyur untuk fokus pada logika tingkat tinggi agen mereka. Kekuatan sejati platform ini terletak pada kemampuan inspeksi mendalamnya—memungkinkan Anda melacak aliran data dan men-debug I/O setiap komponen—dan transisinya yang mulus dari prototipe visual ke API siap produksi. Pergeseran dari agen panggilan tunggal sederhana ke alur kerja multi-tahap yang kompleks menggunakan pola seperti Best-of-N atau RAG tidak hanya mungkin, tetapi juga intuitif. Dengan membangun menggunakan Pyspur, Anda tidak hanya menghubungkan kotak; Anda sedang merekayasa sistem AI yang andal, mudah di-debug, dan dapat diskalakan.