Pencatatan Jejak untuk Langkah Agen
Catat setiap langkah penalaran, pemanggilan alat, dan hasilnya untuk analisis setelah kejadian.
Pencatatan Jejak untuk Langkah Agen adalah pelajaran AI Agents gratis di CoddyKit. Ini adalah pelajaran 2 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar AI Agents, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus AI Agents mencakup 4 pelajaran total.
Mengapa Pencatatan Jejak Penting bagi Agen
Catatan aplikasi standar merekam kesalahan dan peristiwa. Catatan jejak agen merekam penalaran: apa yang dipikirkan agen pada setiap langkah, alat mana yang dipilih, argumen apa yang digunakan, dan apa yang dikembalikan alat tersebut?
Tanpa pencatatan jejak, menelusuri kesalahan agen seperti mendiagnosis masalah mobil tanpa dasbor—Anda hanya dapat menebak.
Menyiapkan Modul Pencatatan Python
Modul logging bawaan Python adalah alat standar. Konfigurasikan modul tersebut di awal agen dengan format yang mencakup stempel waktu, tingkat, dan pesan. Gunakan tingkat DEBUG untuk data jejak—tingkat ini dapat dinonaktifkan di produksi.
import logging
import sys
logging.basicConfig(
level=logging.DEBUG,
format='%(asctime)s [%(levelname)s] %(name)s: %(message)s',
datefmt='%H:%M:%S',
stream=sys.stdout
)
logger = logging.getLogger('myagent')
# Usage:
logger.debug('Step 1: reasoning started')
logger.info('Agent task completed in 5 steps')
logger.warning('Tool returned empty result')
logger.error('Failed to parse tool arguments')
# Output:
# 14:32:01 [DEBUG] myagent: Step 1: reasoning started
# 14:32:03 [INFO] myagent: Agent task completed in 5 stepsMencatat Setiap Langkah Penalaran
Catat fakta utama di awal setiap langkah: nomor langkah, penalaran yang dihasilkan LLM, alat yang dipilih, dan argumen yang diteruskan. Ini membuat catatan lengkap tentang proses pengambilan keputusan agen.
import logging
import json
logger = logging.getLogger('myagent')
def log_step(step: int, thought: str, tool_name: str, tool_args: dict):
logger.debug(
f'Step {step}: '
f'reasoning="{thought[:100]}" '
f'tool={tool_name} '
f'args={json.dumps(tool_args, ensure_ascii=False)[:200]}'
)
# Example usage in the agent loop:
# log_step(
# step=1,
# thought='I need to find the current weather in Tokyo',
# tool_name='get_weather',
# tool_args={'city': 'Tokyo', 'unit': 'celsius'}
# )
if __name__ == '__main__':
import sys
logging.basicConfig(level=logging.DEBUG, format='%(message)s', stream=sys.stdout)
log_step(
step=1,
thought='I need to find the current weather in Tokyo',
tool_name='get_weather',
tool_args={'city': 'Tokyo', 'unit': 'celsius'}
)
Mencatat Hasil Alat
Setelah setiap pemanggilan alat, catat apakah pemanggilan tersebut berhasil dan pratinjau hasilnya. Mencatat hasil lengkap mungkin terlalu panjang—potong hingga 200 karakter pertama agar mudah dibaca.
import logging
logger = logging.getLogger('myagent')
def log_tool_result(step: int, tool_name: str, result: str, success: bool):
status = 'OK' if success else 'ERROR'
preview = str(result)[:200].replace('\n', ' ')
logger.debug(
f'Step {step} result [{status}]: tool={tool_name} '
f'result_preview="{preview}"'
)
if not success:
logger.warning(f'Tool {tool_name} failed at step {step}')
# Log at the start of the step:
# log_step(step, thought, tool_name, tool_args)
# result = execute_tool(tool_name, tool_args)
# log_tool_result(step, tool_name, result, success=True)
if __name__ == '__main__':
import sys
logging.basicConfig(level=logging.DEBUG, format='%(message)s', stream=sys.stdout)
log_tool_result(1, 'get_weather', '{"temp_c": 18, "condition": "cloudy"}', success=True)
log_tool_result(2, 'get_weather', 'Connection timed out', success=False)
Pencatatan Terstruktur dengan Format JSON
Catatan teks biasa mudah dibaca, tetapi sulit dikueri. Catatan JSON terstruktur dapat dimasukkan ke sistem penggabungan catatan (Datadog, Splunk, CloudWatch) untuk penyaringan, dasbor, dan peringatan.
import logging
import json
import sys
class JSONFormatter(logging.Formatter):
def format(self, record: logging.LogRecord) -> str:
log_obj = {
'timestamp': self.formatTime(record),
'level': record.levelname,
'logger': record.name,
'message': record.getMessage()
}
# Add any extra fields attached to the log record
if hasattr(record, 'step'):
log_obj['step'] = record.step
if hasattr(record, 'tool'):
log_obj['tool'] = record.tool
return json.dumps(log_obj)
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(JSONFormatter())
logger = logging.getLogger('agent_trace')
logger.addHandler(handler)
logger.setLevel(logging.DEBUG)
logger.setLevel(logging.DEBUG)
logger.debug('Step 3: tool=search_web', extra={'step': 3, 'tool': 'search_web'})
Pencatatan dengan Kolom Tambahan
Teruskan extra={} ke pemanggilan pencatatan untuk melampirkan kolom terstruktur yang dapat digunakan oleh pemformat JSON atau sistem penggabungan catatan untuk penyaringan dan analisis.
import logging
logger = logging.getLogger('agent_trace')
def log_step_structured(step: int, tool: str, thought: str, args: dict):
logger.debug(
f'Step {step}: tool={tool}',
extra={
'step': step,
'tool': tool,
'thought': thought[:200],
'tool_args': args
}
)
# If using a JSON formatter, this produces:
# {
# 'timestamp': '14:32:01',
# 'level': 'DEBUG',
# 'message': 'Step 3: tool=search_web',
# 'step': 3,
# 'tool': 'search_web',
# 'thought': 'I need to find recent news about...',
# 'args': {'query': 'AI news 2025'}
# }
if __name__ == '__main__':
import sys
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(logging.Formatter('%(message)s | step=%(step)s tool=%(tool)s'))
logger.addHandler(handler)
logger.setLevel(logging.DEBUG)
log_step_structured(3, 'search_web', 'I need to find recent news about...', {'query': 'AI news 2025'})
Mencatat ke Berkas
Untuk agen produksi, catat ke berkas agar dapat dianalisis nanti. Gunakan RotatingFileHandler untuk membatasi ukuran berkas catatan dan mencegah disk kehabisan ruang.
import logging
from logging.handlers import RotatingFileHandler
import sys
logger = logging.getLogger('myagent')
logger.setLevel(logging.DEBUG)
# Console handler — INFO and above
console = logging.StreamHandler(sys.stdout)
console.setLevel(logging.INFO)
console.setFormatter(logging.Formatter('%(message)s'))
# File handler — DEBUG and above, rotates at 10MB
file_handler = RotatingFileHandler(
'agent_trace.log',
maxBytes=10 * 1024 * 1024, # 10 MB
backupCount=3
)
file_handler.setLevel(logging.DEBUG)
file_handler.setFormatter(logging.Formatter(
'%(asctime)s [%(levelname)s] %(message)s'
))
logger.addHandler(console)
logger.addHandler(file_handler)
logger.info('Agent task completed in 5 steps')
logger.debug('Step 1: reasoning started')
Mencatat ID Sesi untuk Agen Banyak Pengguna
Ketika beberapa pengguna atau tugas berjalan secara bersamaan, catatan dapat tercampur. Lampirkan ID sesi atau ID tugas ke setiap pesan catatan agar Anda dapat menyaring catatan untuk proses tertentu.
import logging
import uuid
class SessionLogger:
def __init__(self, name: str):
self.logger = logging.getLogger(name)
self.session_id = str(uuid.uuid4())[:8]
def debug(self, msg: str, **kwargs):
self.logger.debug(f'[session={self.session_id}] {msg}', **kwargs)
def info(self, msg: str, **kwargs):
self.logger.info(f'[session={self.session_id}] {msg}', **kwargs)
def error(self, msg: str, **kwargs):
self.logger.error(f'[session={self.session_id}] {msg}', **kwargs)
# Each agent run gets its own logger with a unique session ID
# log = SessionLogger('myagent')
# log.info(f'Starting task: {query}') # [session=a3f1b290] Starting task: ...
if __name__ == '__main__':
import sys
logging.basicConfig(level=logging.INFO, format='%(message)s', stream=sys.stdout)
log = SessionLogger('myagent')
log.info(f'Starting task: summarize the quarterly report')
Mengukur Waktu Setiap Langkah
Tambahkan informasi waktu ke catatan setiap langkah untuk mengidentifikasi hambatan. Alat mana yang paling lambat? Berapa lama waktu yang dibutuhkan LLM untuk menalar? Data ini membantu mengarahkan pengoptimalan.
import time
import logging
logger = logging.getLogger('myagent')
def timed_tool_call(tool_name: str, tool_fn, args: dict) -> str:
start = time.perf_counter()
try:
result = tool_fn(**args)
elapsed = time.perf_counter() - start
logger.debug(f'Tool {tool_name} completed in {elapsed:.2f}s')
return result
except Exception as e:
elapsed = time.perf_counter() - start
logger.error(f'Tool {tool_name} failed in {elapsed:.2f}s: {e}')
raise
# In the agent loop:
# result = timed_tool_call('search_web', search_web, {'query': 'Python'})
# Logs: Tool search_web completed in 1.34s
if __name__ == '__main__':
import sys
logging.basicConfig(level=logging.DEBUG, format='%(message)s', stream=sys.stdout)
def search_web(query):
return f'3 results for {query}'
result = timed_tool_call('search_web', search_web, {'query': 'Python'})
print('Tool result:', result)
Pola Jejak Langkah Lengkap
Berikut pola pencatatan jejak lengkap yang siap digunakan di produksi untuk satu langkah agen. Setiap langkah mencatat nomor, penalaran, pilihan alat, argumen, pratinjau hasil, dan waktu—memberi Anda gambaran menyeluruh tentang eksekusi agen.
import time
import logging
import json
logger = logging.getLogger('myagent')
def trace_step(step_num: int, thought: str, tool: str, args: dict, execute_fn):
# Log decision
logger.debug(
f'Step {step_num}: thought="{thought[:80]}" tool={tool} '
f'args={json.dumps(args)[:100]}'
)
# Execute with timing
t0 = time.perf_counter()
try:
result = execute_fn(tool, args)
elapsed = time.perf_counter() - t0
preview = str(result)[:100].replace('\n', ' ')
logger.debug(f'Step {step_num} done in {elapsed:.2f}s: "{preview}"')
return result
except Exception as e:
elapsed = time.perf_counter() - t0
logger.error(f'Step {step_num} failed in {elapsed:.2f}s: {e}')
return f'ERROR: {e}'
if __name__ == '__main__':
import sys
logging.basicConfig(level=logging.DEBUG, format='%(message)s', stream=sys.stdout)
def execute_fn(tool, args):
return f'42 (from {tool})'
trace_step(1, 'I should compute the answer', 'calculator', {'expr': '6*7'}, execute_fn)
Menonaktifkan Catatan di Produksi
Catatan jejak debug berisi data sensitif (kueri, tanggapan API) dan dapat sangat panjang. Di produksi, atur tingkat catatan ke INFO atau WARNING untuk menekan jejak debug. Gunakan variabel lingkungan untuk mengontrol tingkat tersebut.
import os
import logging
import sys
# Read log level from environment variable
log_level_str = os.environ.get('LOG_LEVEL', 'INFO').upper()
log_level = getattr(logging, log_level_str, logging.INFO)
logging.basicConfig(level=log_level, stream=sys.stdout)
logger = logging.getLogger('myagent')
# Development: LOG_LEVEL=DEBUG python agent.py -> full traces
# Production: LOG_LEVEL=WARNING python agent.py -> only warnings/errors
# Default: LOG_LEVEL not set -> INFO level
logger.debug('This only appears in DEBUG mode')
logger.info('This appears in INFO and DEBUG modes')
logger.warning('This always appears')Uji Pemahaman: Pencatatan Jejak
Uji pemahaman Anda tentang pencatatan jejak untuk langkah-langkah agen.
Ringkasan: Pencatatan Jejak untuk Langkah Agen
Sekarang Anda memiliki strategi pencatatan jejak yang lengkap untuk agen:
- Gunakan
logging.basicConfig(level=DEBUG)untuk mengaktifkan catatan tingkat jejak - Catat nomor langkah, penalaran, nama alat, dan argumen pada setiap langkah
- Catat hasil alat dengan pratinjau serta status berhasil atau gagal
- Gunakan pemformatan JSON untuk catatan yang terstruktur dan dapat dikueri
- Lampirkan ID sesi untuk agen dengan banyak pengguna atau agen yang berjalan serentak
- Tambahkan pengukuran waktu untuk mengidentifikasi langkah yang lambat
- Kontrol panjang catatan dengan variabel lingkungan
LOG_LEVEL
Belajar AI Agents dengan tutor AI — gratis
Tulis dan jalankan kode asli di browser kamu, dapatkan bantuan instan dari tutor AI 24/7, dan lanjutkan di mana kamu tinggalkan di web atau aplikasi.
- Kursus
- 60
- Pelajaran
- 239
Pertanyaan yang Sering Diajukan
Apakah pelajaran “Pencatatan Jejak untuk Langkah Agen” gratis?
Ya — teks lengkap “Pencatatan Jejak untuk Langkah Agen” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus AI Agents, upgrade ke CoddyKit PRO. Kursus AI Agents mencakup 4 pelajaran total.
Apa yang akan aku pelajari di “Pencatatan Jejak untuk Langkah Agen”?
Catat setiap langkah penalaran, pemanggilan alat, dan hasilnya untuk analisis setelah kejadian. Kamu berlatih AI Agents dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.
Apakah aku perlu pengalaman untuk memulai AI Agents?
Tidak diperlukan pengalaman sebelumnya. AI Agents di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 2 dari 4.
Berapa lama pelajaran “Pencatatan Jejak untuk Langkah Agen” memakan waktu?
Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.
Bisakah aku menulis dan menjalankan kode dalam pelajaran AI Agents ini?
Ya. Setiap pelajaran AI Agents menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.
Semua pelajaran dalam kursus ini
- Kegagalan Umum dalam Putaran Agen
- Pencatatan Jejak untuk Langkah Agen
- Mendeteksi dan Memutus Putaran Tak Berujung
- Teknik Debugging Langkah demi Langkah