Tutorial Lengkap AgentOps: Monitoring dan Observability untuk AI Agent
Membangun AI agent yang berjalan di production tanpa monitoring ibarat menerbangkan pesawat tanpa instrumen. Anda tidak tahu kapan agent gagal, berapa biaya yang terpakai, atau di mana bottleneck terjadi. AgentOps hadir sebagai solusi observability yang dirancang khusus untuk AI agent, memberikan visibilitas penuh terhadap setiap langkah yang dilakukan agent Anda.
Dalam tutorial ini, kita akan membahas cara menggunakan AgentOps mulai dari instalasi, integrasi dasar dengan OpenAI dan LangChain, hingga fitur lanjutan seperti custom event tracking, multi-agent monitoring, dan cost analysis. Semua contoh kode bisa langsung Anda jalankan di project Anda.
Apa Itu AgentOps?
AgentOps adalah platform observability open-source yang dirancang khusus untuk memantau AI agent di production. Berbeda dengan logging tradisional yang hanya menangkap teks, AgentOps merekam seluruh lifecycle agent secara terstruktur, termasuk LLM calls, tool usage, error traces, biaya token, dan latency.
Fitur utama AgentOps:
- Session Tracking: Merekam setiap sesi agent dari awal hingga akhir
- LLM Call Monitoring: Melacak setiap panggilan ke LLM termasuk prompt, response, token usage, dan cost
- Tool Tracking: Memantau penggunaan tools oleh agent
- Error Detection: Mendeteksi dan melaporkan error secara real-time
- Cost Analysis: Menghitung biaya penggunaan LLM secara akurat
- Session Replay: Memutar ulang seluruh alur kerja agent untuk debugging
- Multi-Agent Support: Mendukung monitoring untuk sistem multi-agent
- Dashboard: Visualisasi metrik agent melalui web dashboard
Instalasi
Prasyarat
- Python 3.9 atau lebih baru
- Akun AgentOps (gratis untuk tier developer)
- API key dari provider LLM (OpenAI, Anthropic, dll.)
Setup Environment
pip install agentops
Untuk integrasi dengan framework tertentu, install dependency tambahan:
# Untuk integrasi OpenAI
pip install agentops openai
Untuk integrasi LangChain
pip install agentops langchain langchain-openai
Untuk integrasi CrewAI
pip install agentops crewai
Untuk integrasi AutoGen
pip install agentops autogen
Mendapatkan API Key
export AGENTOPSAPIKEY="your-api-key-here"
export OPENAIAPIKEY="your-openai-key-here"
Atau buat file .env:
AGENTOPSAPIKEY=your-api-key-here
OPENAIAPIKEY=your-openai-key-here
Basic Usage: Monitoring LLM Calls
Inisialisasi AgentOps
Cara paling sederhana menggunakan AgentOps adalah dengan menambahkan dua baris kode. AgentOps secara otomatis melakukan patching terhadap library LLM yang terdeteksi.
import agentops
import openai
Inisialisasi AgentOps - otomatis patch OpenAI
agentops.init()
client = openai.OpenAI()
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "Kamu adalah asisten yang membantu."},
{"role": "user", "content": "Jelaskan apa itu machine learning dalam 3 kalimat."}
]
)
print(response.choices[0].message.content)
Akhiri sesi dan kirim data ke dashboard
agentops.endsession("Success")
Setelah menjalankan kode di atas, buka dashboard AgentOps untuk melihat:
- Detail LLM call (model, prompt, response)
- Token usage (input tokens, output tokens)
- Estimasi biaya
- Latency
Menggunakan API Key Secara Eksplisit
import agentops
agentops.init(apikey="your-api-key-here")
Session Tags untuk Organisasi
Tags membantu Anda mengkategorikan dan memfilter sesi di dashboard:
agentops.init(
tags=["production", "customer-support", "v2.1"]
)
Tracking Multiple LLM Calls
AgentOps secara otomatis merekam setiap panggilan LLM dalam satu sesi. Ini sangat berguna ketika agent Anda melakukan beberapa langkah reasoning.
import agentops
import openai
agentops.init(tags=["multi-step-reasoning"])
client = openai.OpenAI()
Step 1: Analisis pertanyaan
analysis = client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "Analisis pertanyaan berikut dan identifikasi topik utamanya."},
{"role": "user", "content": "Bagaimana cara mengoptimasi query database PostgreSQL yang lambat?"}
]
)
topic = analysis.choices[0].message.content
print(f"Topik teridentifikasi: {topic}")
Step 2: Generate jawaban detail
answer = client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "Berikan jawaban teknis yang detail berdasarkan analisis topik."},
{"role": "user", "content": f"Berdasarkan topik: {topic}\n\nBerikan panduan optimasi yang lengkap."}
]
)
print(f"Jawaban: {answer.choices[0].message.content}")
Step 3: Buat ringkasan
summary = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "Buat ringkasan dalam 3 poin utama."},
{"role": "user", "content": answer.choices[0].message.content}
]
)
print(f"Ringkasan: {summary.choices[0].message.content}")
agentops.endsession("Success")
Di dashboard, Anda akan melihat ketiga LLM calls secara berurutan dalam satu sesi, lengkap dengan timeline dan total cost.
Decorator untuk Agent Class
AgentOps menyediakan decorator @trackagent untuk melacak agent sebagai entitas terpisah dalam sesi:
import agentops
from agentops import trackagent
agentops.init(tags=["agent-class-demo"])
@trackagent(name="research-agent")
class ResearchAgent:
def init(self):
self.client = openai.OpenAI()
self.findings = []
def research(self, topic: str) -> str:
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "Kamu adalah peneliti AI yang teliti."},
{"role": "user", "content": f"Lakukan riset mendalam tentang: {topic}"}
]
)
result = response.choices[0].message.content
self.findings.append(result)
return result
def summarize(self) -> str:
allfindings = "\n\n".join(self.findings)
response = self.client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "Rangkum semua temuan riset berikut."},
{"role": "user", "content": allfindings}
]
)
return response.choices[0].message.content
agent = ResearchAgent()
agent.research("Transformer architecture untuk NLP")
agent.research("Teknik fine-tuning LLM yang efisien")
summary = agent.summarize()
print(summary)
agentops.endsession("Success")
Custom Event Tracking
Selain LLM calls yang otomatis tercatat, Anda bisa merekam event kustom untuk melacak logika bisnis:
import agentops
from agentops import ActionEvent, ErrorEvent
agentops.init(tags=["custom-events"])
Rekam action kustom
agentops.record(ActionEvent(
actiontype="databasequery",
params={"query": "SELECT FROM users WHERE active = true", "database": "production"},
returns={"rowcount": 1523}
))
Rekam error jika terjadi
try:
result = processdata(rawdata)
except Exception as e:
agentops.record(ErrorEvent(
errortype=type(e).name,
details=str(e)
))
agentops.endsession("Fail")
raise
agentops.endsession("Success")
Tool Event Tracking
Ketika agent menggunakan tools, rekam hasilnya:
from agentops import ToolEvent
def searchdatabase(query: str) -> dict:
toolevent = ToolEvent(name="databasesearch")
toolevent.params = {"query": query}
try:
results = db.search(query)
toolevent.returns = {"count": len(results), "status": "success"}
toolevent.endtimestamp = agentops.gettimestamp()
agentops.record(toolevent)
return results
except Exception as e:
toolevent.returns = {"error": str(e), "status": "failed"}
agentops.record(toolevent)
raise
Integrasi dengan LangChain
AgentOps memiliki integrasi bawaan dengan LangChain yang memungkinkan pelacakan otomatis seluruh chain dan agent runs:
import agentops
from langchainopenai import ChatOpenAI
from langchain.agents import AgentExecutor, createopenaitoolsagent
from langchain.tools import tool
from langchaincore.prompts import ChatPromptTemplate, MessagesPlaceholder
agentops.init(tags=["langchain-agent"])
@tool
def calculate(expression: str) -> str:
"""Menghitung ekspresi matematika."""
try:
result = eval(expression)
return f"Hasil: {result}"
except Exception as e:
return f"Error: {str(e)}"
@tool
def getweather(city: str) -> str:
"""Mendapatkan informasi cuaca untuk kota tertentu."""
weatherdata = {
"Jakarta": "Cerah, 32°C, Kelembaban 75%",
"Bandung": "Berawan, 24°C, Kelembaban 80%",
"Surabaya": "Panas, 35°C, Kelembaban 65%"
}
return weatherdata.get(city, f"Data cuaca untuk {city} tidak tersedia.")
llm = ChatOpenAI(model="gpt-4o", temperature=0)
prompt = ChatPromptTemplate.frommessages([
("system", "Kamu adalah asisten cerdas yang bisa menghitung dan mengecek cuaca."),
MessagesPlaceholder(variablename="chathistory", optional=True),
("human", "{input}"),
MessagesPlaceholder(variablename="agentscratchpad"),
])
tools = [calculate, getweather]
agent = createopenaitoolsagent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
result = executor.invoke({
"input": "Berapa suhu rata-rata jika Jakarta 32 derajat dan Bandung 24 derajat? Cek juga cuaca Surabaya."
})
print(result["output"])
agentops.endsession("Success")
Di dashboard AgentOps, Anda akan melihat:
- Setiap LLM call dalam chain
- Tool calls yang dilakukan agent (calculate, getweather)
- Input dan output setiap langkah
- Total token usage dan biaya
Integrasi dengan CrewAI
AgentOps juga terintegrasi dengan CrewAI untuk monitoring tim multi-agent:
import agentops
from crewai import Agent, Task, Crew
agentops.init(tags=["crewai-demo"])
researcher = Agent(
role="Peneliti Teknologi",
goal="Mengumpulkan informasi terkini tentang teknologi AI",
backstory="Kamu adalah peneliti senior dengan 10 tahun pengalaman di bidang AI.",
verbose=True
)
writer = Agent(
role="Penulis Konten",
goal="Menulis artikel yang informatif dan mudah dipahami",
backstory="Kamu adalah penulis teknologi berpengalaman yang ahli menjelaskan konsep kompleks.",
verbose=True
)
researchtask = Task(
description="Riset perkembangan terbaru Large Language Model di tahun 2026.",
expectedoutput="Laporan riset dengan minimal 5 poin perkembangan penting.",
agent=researcher
)
writingtask = Task(
description="Tulis artikel blog berdasarkan hasil riset tentang perkembangan LLM.",
expectedoutput="Artikel blog 500 kata yang informatif dan engaging.",
agent=writer
)
crew = Crew(
agents=[researcher, writer],
tasks=[researchtask, writingtask],
verbose=True
)
result = crew.kickoff()
print(result)
agentops.endsession("Success")
Advanced: Session Management
Multiple Sessions
Anda bisa menjalankan beberapa sesi secara bersamaan, berguna untuk membandingkan strategi agent yang berbeda:
import agentops
Session untuk strategi A
sessiona = agentops.startsession(tags=["strategy-a", "experiment"])
Session untuk strategi B
sessionb = agentops.startsession(tags=["strategy-b", "experiment"])
Gunakan session tertentu
clienta = openai.OpenAI()
clientb = openai.OpenAI()
responsea = clienta.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Jelaskan quantum computing."}]
)
responseb = clientb.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Jelaskan quantum computing."}]
)
sessiona.endsession("Success")
sessionb.endsession("Success")
Session dengan Context Manager
import agentops
with agentops.Session(tags=["context-manager"]) as session:
client = openai.OpenAI()
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
Session otomatis diakhiri saat keluar context
Advanced: Cost Tracking dan Analytics
Memantau Biaya Per Session
AgentOps secara otomatis menghitung biaya berdasarkan model dan token usage:
import agentops
agentops.init(tags=["cost-tracking"])
client = openai.OpenAI()
Beberapa panggilan dengan model berbeda
for i in range(5):
client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": f"Query kompleks #{i+1}"}]
)
for i in range(10):
client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": f"Query sederhana #{i+1}"}]
)
agentops.endsession("Success")
Dashboard akan menampilkan breakdown biaya per model
Monitoring di Production
Untuk production, tambahkan error handling yang robust:
import agentops
import logging
logger = logging.getLogger(name)
def runagenttask(userinput: str) -> str:
session = agentops.startsession(
tags=["production", "customer-facing"]
)
try:
client = openai.OpenAI()
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "Kamu adalah customer support agent."},
{"role": "user", "content": userinput}
],
timeout=30
)
result = response.choices[0].message.content
session.endsession("Success")
return result
except openai.APITimeoutError:
logger.error("LLM call timeout")
agentops.record(ErrorEvent(
errortype="APITimeoutError",
details="LLM call exceeded 30s timeout"
))
session.endsession("Fail")
return "Maaf, sistem sedang sibuk. Silakan coba lagi."
except Exception as e:
logger.error(f"Agent error: {e}")
agentops.record(ErrorEvent(
errortype=type(e).name,
details=str(e)
))
session.endsession("Fail")
raise
Advanced: Callback dan Webhook
Konfigurasi Webhook
AgentOps mendukung webhook untuk notifikasi real-time:
agentops.init(
tags=["webhook-enabled"],
)
Konfigurasi webhook dilakukan melalui dashboard AgentOps di menu Settings > Webhooks. Anda bisa mengirim notifikasi ke Slack, Discord, atau endpoint kustom saat:
- Session gagal
- Biaya melebihi threshold
- Latency melebihi batas
Best Practices
1. Selalu Akhiri Session
Pastikan setiap session diakhiri dengan status yang tepat. Session yang tidak diakhiri akan muncul sebagai "Indeterminate" di dashboard.
# Gunakan try-finally untuk memastikan session selalu diakhiri
agentops.init()
try:
result = runagent()
agentops.endsession("Success")
except Exception:
agentops.endsession("Fail")
2. Gunakan Tags yang Deskriptif
agentops.init(tags=[
"production", # Environment
"v2.3", # Versi agent
"customer-support", # Use case
"gpt-4o" # Model utama
])
3. Pisahkan Environment
import os
env = os.getenv("ENVIRONMENT", "development")
agentops.init(tags=[env, "my-agent"])
4. Monitor Token Usage
Pantau token usage untuk mengoptimasi biaya:
# Gunakan model yang lebih kecil untuk tugas sederhana
simpleresponse = client.chat.completions.create(
model="gpt-4o-mini", # Lebih murah untuk klasifikasi
messages=[{"role": "user", "content": "Klasifikasi: apakah ini pertanyaan teknis? 'Cara install Python'"}]
)
Gunakan model yang lebih besar untuk tugas kompleks
complexresponse = client.chat.completions.create(
model="gpt-4o", # Lebih akurat untuk analisis
messages=[{"role": "user", "content": "Analisis arsitektur microservices berikut dan berikan rekomendasi..."}]
)
5. Implementasi Retry Logic yang Terlacak
import agentops
from agentops import ActionEvent
import time
def callwithretry(messages, maxretries=3):
for attempt in range(maxretries):
try:
response = client.chat.completions.create(
model="gpt-4o",
messages=messages
)
return response
except openai.RateLimitError:
agentops.record(ActionEvent(
actiontype="retry",
params={"attempt": attempt + 1, "reason": "ratelimit"}
))
time.sleep(2 attempt)
agentops.record(ErrorEvent(
errortype="MaxRetriesExceeded",
details=f"Failed after {maxretries} attempts"
))
raise Exception("Max retries exceeded")
6. Batch Processing dengan Session Per Batch
def processbatch(items: list, batchid: str):
session = agentops.startsession(
tags=["batch-processing", f"batch-{batchid}"]
)
successcount = 0
errorcount = 0
for item in items:
try:
processitem(item)
successcount += 1
except Exception as e:
errorcount += 1
agentops.record(ErrorEvent(
errortype=type(e).name,
details=f"Item {item['id']}: {str(e)}"
))
agentops.record(ActionEvent(
actiontype="batchcomplete",
params={"total": len(items)},
returns={"success": successcount, "errors": errorcount}
))
status = "Success" if errorcount == 0 else "Fail"
session.endsession(status)
Perbandingan dengan Tools Monitoring Lain
| Fitur | AgentOps | LangSmith | Helicone | Portkey |
|-------|----------|-----------|----------|---------|
| Agent-specific tracking | Ya | Ya | Tidak | Sebagian |
| Auto-instrumentation | Ya | Ya | Ya | Ya |
| Multi-agent support | Ya | Sebagian | Tidak | Tidak |
| Cost tracking | Ya | Ya | Ya | Ya |
| Session replay | Ya | Ya | Tidak | Tidak |
| Open-source | Ya | Tidak | Sebagian | Tidak |
| Framework integrations | Banyak | LangChain | Agnostic | Agnostic |
| Self-hosted option | Ya | Enterprise | Ya | Tidak |
Troubleshooting
Session Tidak Muncul di Dashboard
# Pastikan init() dipanggil sebelum LLM call
agentops.init() # HARUS di awal
Periksa koneksi
import agentops
result = agentops.init()
print(f"Init status: {result}")
Token Count Tidak Akurat
Beberapa model mungkin tidak mengembalikan token count. Pastikan menggunakan model yang didukung dan versi SDK terbaru:
pip install --upgrade agentops openai
High Latency pada Logging
AgentOps mengirim data secara asynchronous, sehingga tidak seharusnya menambah latency signifikan. Jika terjadi, periksa koneksi internet dan pertimbangkan penggunaan batch mode:
agentops.init(
maxwaittime=1000, # Maksimal wait time dalam ms
maxqueuesize=100 # Ukuran queue sebelum flush
)
Contoh Lengkap: RAG Agent dengan Monitoring
Berikut contoh lengkap RAG agent yang dimonitor dengan AgentOps:
import agentops
from agentops import trackagent, ActionEvent, ToolEvent
import openai
import numpy as np
agentops.init(tags=["rag-agent", "production"])
@trackagent(name="rag-retrieval-agent")
class RAGAgent:
def init(self):
self.client = openai.OpenAI()
self.knowledgebase = self.loadknowledgebase()
def loadknowledgebase(self) -> list:
agentops.record(ActionEvent(
actiontype="loadknowledgebase",
returns={"status": "loaded", "documents": 150}
))
return [
{"text": "Python adalah bahasa pemrograman populer.", "embedding": None},
{"text": "Machine learning memerlukan data yang berkualitas.", "embedding": None},
{"text": "Docker memudahkan deployment aplikasi.", "embedding": None},
]
def retrieve(self, query: str, topk: int = 3) -> list:
toolevent = ToolEvent(name="vectorsearch")
toolevent.params = {"query": query, "topk": topk}
queryembedding = self.client.embeddings.create(
model="text-embedding-3-small",
input=query
)
results = self.knowledgebase[:topk]
toolevent.returns = {"resultscount": len(results)}
agentops.record(toolevent)
return results
def generate(self, query: str, context: list) -> str:
contexttext = "\n".join([doc["text"] for doc in context])
response = self.client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": f"Jawab berdasarkan konteks:\n{contexttext}"},
{"role": "user", "content": query}
]
)
return response.choices[0].message.content
def answer(self, query: str) -> str:
context = self.retrieve(query)
return self.generate(query, context)
agent = RAGAgent()
answer = agent.answer("Apa keuntungan menggunakan Docker?")
print(answer)
agentops.end_session("Success")
Kesimpulan
AgentOps memberikan visibilitas yang sangat dibutuhkan ketika menjalankan AI agent di production. Dengan fitur auto-instrumentation, Anda hanya perlu menambahkan beberapa baris kode untuk mendapatkan monitoring yang komprehensif.
Poin-poin penting dari tutorial ini:
pip install agentops dan agentops.init() untuk mulai trackingDengan AgentOps, Anda bisa membangun AI agent yang tidak hanya berfungsi, tetapi juga observable dan maintainable di production. Mulailah dengan integrasi sederhana, lalu tambahkan custom events seiring kebutuhan monitoring Anda berkembang.