Tutorial Lengkap Griptape: Framework Python untuk Membangun AI Agent dan Pipeline
Griptape adalah framework open-source Python yang dirancang khusus untuk membangun aplikasi AI yang terstruktur, aman, dan siap produksi. Berbeda dengan framework agent lainnya, Griptape menekankan pada predictability dan kontrol melalui arsitektur berbasis struktur yang memisahkan antara logic, tools, memory, dan conversation flow. Dalam tutorial ini, kita akan mempelajari cara menggunakan Griptape mulai dari instalasi hingga membangun AI agent dan pipeline yang kompleks.
Mengapa Griptape?
Banyak framework AI agent yang tersedia saat ini, namun Griptape memiliki beberapa keunggulan yang membuatnya menonjol:
Instalasi
Prasyarat
Pastikan Anda memiliki Python 3.9 atau lebih baru terinstal di sistem Anda.
python --version
Python 3.11.x atau lebih baru direkomendasikan
Instalasi Dasar
Instalasi Griptape cukup sederhana menggunakan pip:
pip install griptape
Instalasi dengan Fitur Tambahan
Untuk menginstal Griptape dengan driver dan tool tambahan:
# Dengan semua driver
pip install "griptape[all]"
Dengan driver spesifik
pip install "griptape[drivers-prompt-openai]"
pip install "griptape[drivers-prompt-anthropic]"
pip install "griptape[drivers-embedding-openai]"
pip install "griptape[drivers-vector-pinecone]"
Konfigurasi API Key
Griptape mendukung berbagai LLM provider. Konfigurasi API key melalui environment variable:
# Untuk OpenAI (default)
export OPENAIAPIKEY="sk-your-api-key-here"
Untuk Anthropic Claude
export ANTHROPICAPIKEY="sk-ant-your-api-key-here"
Untuk AWS Bedrock
export AWSACCESSKEYID="your-access-key"
export AWSSECRETACCESSKEY="your-secret-key"
export AWSDEFAULTREGION="us-east-1"
Penggunaan Dasar
Agent Sederhana
Mari mulai dengan membuat agent sederhana yang bisa menjawab pertanyaan:
from griptape.structures import Agent
from griptape.rules import Rule
agent = Agent(
rules=[
Rule("Kamu adalah asisten AI yang membantu dan ramah"),
Rule("Jawab dalam bahasa Indonesia jika ditanya dalam bahasa Indonesia"),
]
)
agent.run("Apa itu machine learning?")
Output dari agent akan berisi respons yang terstruktur dengan metadata tentang token usage dan processing time.
Agent dengan Tools
Salah satu kekuatan utama Griptape adalah sistem tool-nya. Berikut contoh agent dengan kemampuan kalkulasi dan web search:
from griptape.structures import Agent
from griptape.tools import Calculator, WebScraper, FileManager
from griptape.rules import Rule
agent = Agent(
tools=[
Calculator(),
WebScraper(),
FileManager(),
],
rules=[
Rule("Gunakan tools yang tersedia untuk menjawab pertanyaan"),
Rule("Selalu verifikasi hasil kalkulasi menggunakan Calculator tool"),
]
)
agent.run("Berapa hasil dari 1547 * 893 + 2341?")
Custom Tool
Anda juga bisa membuat tool kustom sesuai kebutuhan:
from griptape.tools import BaseTool
from griptape.artifacts import TextArtifact
from griptape.utils.decorators import activity
from schema import Schema, Literal, Optional
class WeatherTool(BaseTool):
@activity(
config={
"description": "Mendapatkan informasi cuaca untuk kota tertentu",
"schema": Schema({
Literal("city"): str,
Optional(Literal("unit")): str,
}),
}
)
def getweather(self, params: dict) -> TextArtifact:
city = params["values"]["city"]
unit = params["values"].get("unit", "celsius")
# Implementasi API cuaca di sini
return TextArtifact(f"Cuaca di {city}: 28 derajat {unit}, cerah")
agent = Agent(
tools=[WeatherTool()]
)
agent.run("Bagaimana cuaca di Jakarta hari ini?")
Fitur Lanjutan
Pipeline Sekuensial
Pipeline memungkinkan Anda menjalankan serangkaian task secara berurutan, di mana output dari satu task menjadi input untuk task berikutnya:
from griptape.structures import Pipeline
from griptape.tasks import PromptTask, ToolkitTask
from griptape.tools import WebScraper, FileManager
pipeline = Pipeline()
pipeline.addtasks(
PromptTask(
"Buat outline artikel tentang {{ args[0] }}",
id="outlinetask"
),
PromptTask(
"Berdasarkan outline berikut, tulis artikel lengkap:\n"
"{{ parentoutput }}",
id="writingtask"
),
PromptTask(
"Review dan perbaiki artikel berikut untuk kualitas dan akurasi:\n"
"{{ parentoutput }}",
id="reviewtask"
),
)
pipeline.run("Penerapan AI dalam Industri Manufaktur")
Workflow dengan Dependency Graph
Untuk task yang lebih kompleks dengan dependency non-linear, gunakan Workflow:
from griptape.structures import Workflow
from griptape.tasks import PromptTask
workflow = Workflow()
researchtask = PromptTask(
"Lakukan riset tentang {{ args[0] }} dan buat ringkasan",
id="research"
)
analysistask = PromptTask(
"Analisis data dari riset berikut:\n{{ parentoutput }}",
id="analysis",
parentids=["research"]
)
visualizationtask = PromptTask(
"Buat rekomendasi visualisasi untuk data:\n{{ parentoutput }}",
id="visualization",
parentids=["research"]
)
reporttask = PromptTask(
"Gabungkan analisis dan rekomendasi visualisasi menjadi laporan:\n"
"Analisis: {{ parentsoutputtext['analysis'] }}\n"
"Visualisasi: {{ parentsoutputtext['visualization'] }}",
id="report",
parentids=["analysis", "visualization"]
)
workflow.addtasks(researchtask, analysistask, visualizationtask, reporttask)
workflow.run("Tren adopsi AI di Asia Tenggara 2026")
Dalam contoh di atas, analysistask dan visualizationtask berjalan secara paralel setelah researchtask selesai, kemudian hasilnya digabungkan di reporttask.
Memory Management
Griptape menyediakan beberapa jenis memory untuk mengelola konteks percakapan:
from griptape.structures import Agent
from griptape.memory.structure import ConversationMemory
from griptape.drivers import LocalConversationMemoryDriver
agent = Agent(
conversationmemory=ConversationMemory(
driver=LocalConversationMemoryDriver(
filepath="memory.json"
)
)
)
Percakapan pertama
agent.run("Nama saya Budi, saya seorang data scientist")
Agent akan mengingat konteks sebelumnya
agent.run("Apa profesi saya?")
Task Memory (Off-Prompt)
Task Memory adalah fitur unik Griptape yang memungkinkan data besar diproses di luar LLM context window:
from griptape.structures import Agent
from griptape.tools import WebScraper, TaskMemoryClient
agent = Agent(
tools=[
WebScraper(offprompt=True),
TaskMemoryClient(offprompt=False),
]
)
WebScraper akan menyimpan hasil ke Task Memory
tanpa mengirimnya ke LLM langsung
agent.run("Scrape halaman https://example.com dan buat ringkasan")
Menggunakan Berbagai LLM Provider
Griptape mendukung berbagai LLM provider melalui sistem driver:
from griptape.structures import Agent
from griptape.drivers import (
AnthropicPromptDriver,
OpenAiChatPromptDriver,
AmazonBedrockPromptDriver,
)
Menggunakan Claude
agentclaude = Agent(
promptdriver=AnthropicPromptDriver(
model="claude-sonnet-4-20250514",
maxtokens=4096,
)
)
Menggunakan GPT-4
agentgpt = Agent(
promptdriver=OpenAiChatPromptDriver(
model="gpt-4o",
maxtokens=4096,
)
)
Menggunakan AWS Bedrock
agentbedrock = Agent(
promptdriver=AmazonBedrockPromptDriver(
model="anthropic.claude-3-sonnet-20240229-v1:0",
)
)
RAG (Retrieval-Augmented Generation)
Griptape menyediakan dukungan RAG yang kuat melalui RagEngine:
from griptape.structures import Agent
from griptape.tools import RagTool
from griptape.engines.rag import RagEngine
from griptape.engines.rag.modules import (
VectorStoreRetrievalRagModule,
PromptResponseRagModule,
)
from griptape.engines.rag.stages import (
RetrievalRagStage,
ResponseRagStage,
)
from griptape.drivers import (
LocalVectorStoreDriver,
OpenAiEmbeddingDriver,
)
vectorstore = LocalVectorStoreDriver(
embeddingdriver=OpenAiEmbeddingDriver()
)
ragengine = RagEngine(
retrievalstage=RetrievalRagStage(
retrievalmodules=[
VectorStoreRetrievalRagModule(
vectorstoredriver=vectorstore,
queryparams={"topn": 5}
)
]
),
responsestage=ResponseRagStage(
responsemodules=[
PromptResponseRagModule()
]
)
)
agent = Agent(
tools=[
RagTool(
description="Cari informasi dari knowledge base",
ragengine=ragengine,
)
]
)
Event Listeners
Griptape mendukung event system untuk monitoring dan logging:
from griptape.structures import Agent
from griptape.events import (
BaseEvent,
StartTaskEvent,
FinishTaskEvent,
StartPromptEvent,
FinishPromptEvent,
EventListener,
)
def onevent(event: BaseEvent):
if isinstance(event, StartTaskEvent):
print(f"Task dimulai: {event.taskid}")
elif isinstance(event, FinishTaskEvent):
print(f"Task selesai: {event.taskid}")
elif isinstance(event, FinishPromptEvent):
print(f"Token input: {event.inputtokencount}")
print(f"Token output: {event.outputtokencount}")
agent = Agent(
eventlisteners=[
EventListener(onevent)
]
)
agent.run("Jelaskan konsep neural network")
Rulesets untuk Kontrol Behavior
Rulesets memungkinkan Anda mendefinisikan aturan perilaku yang terstruktur:
from griptape.structures import Agent
from griptape.rules import Rule, Ruleset
customerservicerules = Ruleset(
name="Customer Service",
rules=[
Rule("Selalu sapa pelanggan dengan ramah"),
Rule("Jawab dalam bahasa yang sama dengan pertanyaan"),
Rule("Jika tidak tahu jawabannya, katakan dengan jujur"),
Rule("Tawarkan untuk menghubungkan dengan tim support jika diperlukan"),
Rule("Jangan pernah membagikan informasi internal perusahaan"),
]
)
technicalrules = Ruleset(
name="Technical",
rules=[
Rule("Berikan contoh kode jika relevan"),
Rule("Jelaskan langkah-langkah secara bertahap"),
Rule("Sebutkan versi library yang digunakan"),
]
)
agent = Agent(
rulesets=[customerservicerules, technicalrules]
)
agent.run("Bagaimana cara mengintegrasikan API payment gateway?")
Best Practices
1. Gunakan Off-Prompt untuk Data Besar
Selalu gunakan offprompt=True untuk tool yang mengembalikan data dalam jumlah besar. Ini menghemat token dan mencegah context window overflow:
# Baik - data besar diproses di luar prompt
webscraper = WebScraper(offprompt=True)
Kurang optimal - data besar dikirim langsung ke LLM
webscraper = WebScraper(offprompt=False)
2. Struktur Pipeline dengan Jelas
Pisahkan task menjadi unit-unit kecil yang fokus pada satu tugas:
# Baik - task terpisah dan fokus
pipeline.addtasks(
PromptTask("Ekstrak data dari: {{ args[0] }}", id="extract"),
PromptTask("Transformasi data: {{ parentoutput }}", id="transform"),
PromptTask("Generate laporan: {{ parentoutput }}", id="report"),
)
Kurang optimal - satu task besar
pipeline.addtask(
PromptTask("Ekstrak, transformasi, dan buat laporan dari: {{ args[0] }}")
)
3. Implementasi Error Handling
Griptape menyediakan mekanisme error handling yang bisa Anda manfaatkan:
from griptape.structures import Agent
from griptape.events import EventListener, FinishStructureRunEvent
def handlecompletion(event: FinishStructureRunEvent):
if event.structurerun.output:
print(f"Berhasil: {event.structurerun.output.value[:100]}")
else:
print("Task selesai tanpa output")
agent = Agent(
eventlisteners=[
EventListener(handlecompletion, eventtypes=[FinishStructureRunEvent])
]
)
4. Manage API Keys dengan Aman
Jangan pernah hardcode API keys dalam kode. Gunakan environment variables atau secret manager:
import os
from griptape.structures import Agent
from griptape.drivers import OpenAiChatPromptDriver
Baik - menggunakan environment variable
agent = Agent(
promptdriver=OpenAiChatPromptDriver(
model="gpt-4o",
apikey=os.environ.get("OPENAIAPIKEY"),
)
)
5. Gunakan Conversation Memory untuk Chatbot
Untuk aplikasi chatbot, selalu gunakan ConversationMemory agar konteks percakapan terjaga:
from griptape.structures import Agent
from griptape.memory.structure import ConversationMemory
agent = Agent(
conversationmemory=ConversationMemory()
)
Loop percakapan
while True:
userinput = input("You: ")
if userinput.lower() == "quit":
break
response = agent.run(userinput)
print(f"Agent: {response.outputtask.output.value}")
6. Optimasi dengan Chunking untuk Dokumen Besar
Saat bekerja dengan dokumen besar, gunakan chunking untuk memproses data secara efisien:
from griptape.chunkers import TextChunker
from griptape.drivers import OpenAiEmbeddingDriver
chunker = TextChunker(
maxtokens=500,
)
chunks = chunker.chunk("Teks dokumen yang sangat panjang...")
Proses setiap chunk
for chunk in chunks:
# Embed atau proses chunk
pass
Contoh Proyek: AI Research Assistant
Berikut contoh lengkap membangun AI Research Assistant menggunakan Griptape:
from griptape.structures import Agent
from griptape.tools import (
WebScraper,
Calculator,
FileManager,
TaskMemoryClient,
)
from griptape.rules import Rule, Ruleset
from griptape.memory.structure import ConversationMemory
from griptape.drivers import (
AnthropicPromptDriver,
LocalConversationMemoryDriver,
)
researchassistant = Agent(
promptdriver=AnthropicPromptDriver(
model="claude-sonnet-4-20250514",
maxtokens=4096,
),
tools=[
WebScraper(offprompt=True),
Calculator(),
FileManager(),
TaskMemoryClient(offprompt=False),
],
rulesets=[
Ruleset(
name="Research Assistant",
rules=[
Rule("Kamu adalah asisten riset yang teliti dan akurat"),
Rule("Selalu sertakan sumber informasi"),
Rule("Gunakan WebScraper untuk mendapatkan data terbaru"),
Rule("Simpan hasil riset ke file menggunakan FileManager"),
Rule("Berikan analisis kritis, bukan hanya ringkasan"),
]
)
],
conversationmemory=ConversationMemory(
driver=LocalConversationMemoryDriver(
filepath="researchmemory.json"
)
),
)
Mulai sesi riset
researchassistant.run(
"Riset tentang perkembangan terbaru dalam quantum computing "
"dan dampaknya terhadap keamanan kriptografi"
)
Follow-up question (konteks terjaga)
research_assistant.run(
"Berdasarkan riset tadi, apa langkah mitigasi yang bisa "
"dilakukan perusahaan untuk menghadapi ancaman quantum?"
)
Kesimpulan
Griptape adalah framework yang matang dan powerful untuk membangun aplikasi AI berbasis agent. Dengan fitur seperti off-prompt processing, structured pipelines, workflow dengan dependency graph, dan memory management yang fleksibel, Griptape cocok untuk membangun aplikasi AI yang kompleks dan siap produksi.
Beberapa poin penting yang perlu diingat:
- Gunakan off-prompt processing untuk efisiensi token pada data besar
- Manfaatkan Pipeline untuk task sekuensial dan Workflow untuk dependency kompleks
- Implementasikan memory management yang tepat sesuai kebutuhan aplikasi
- Gunakan event listeners untuk monitoring dan debugging
- Selalu kelola API keys dengan aman melalui environment variables
- Pilih LLM provider yang sesuai melalui sistem driver yang fleksibel
Dengan fondasi yang kuat ini, Anda bisa mulai membangun AI agent yang andal dan scalable untuk berbagai kebutuhan bisnis dan teknis. Griptape terus berkembang dengan komunitas yang aktif, menjadikannya pilihan yang solid untuk proyek AI modern.