AI Agents · Ders

Aracı Adımları İçin İz Günlüğü Kaydı

Olay sonrası analiz için her akıl yürütme adımını, araç çağrısını ve sonucu günlüğe kaydetme.

Aracı Adımları İçin İz Günlüğü Kaydı, CoddyKit'te ücretsiz bir AI Agents dersidir. Bu, 4 dersinin 2. dersidir. Aşağıdan dersin tamamını ücretsiz okuyabilir, sonra tarayıcıda yerleşik kod editörü ve 7/24 yapay zeka koçu ile uygulamalı olarak pratik yapabilirsin. Bu, AI Agents öğrenme yolunun bir parçasıdır ve ilerlemeniz web ve CoddyKit uygulaması arasında senkronize olur. AI Agents kursu toplamda 4 dersten oluşur.

İz Günlüklemesi Aracılar İçin Neden Vazgeçilmezdir

Standart uygulama günlükleri hataları ve olayları kaydeder. Aracı iz günlükleri ise akıl yürütmeyi kaydeder: aracı her adımda ne düşündü, hangi aracı seçti, hangi bağımsız değişkenleri kullandı ve araç ne döndürdü?

İz günlüklemesi olmadan bir aracı hatasında hata ayıklamak, gösterge paneli olmadan bir araç sorununu tanılamaya benzer — yalnızca tahminde bulunabilirsiniz.

Python Günlükleme Modülünü Kurma

Python'un yerleşik logging modülü standart araçtır. Aracınızın başlangıcında, zaman damgasını, düzeyi ve iletiyi içeren bir biçimle yapılandırın. İz verileri için DEBUG düzeyini kullanın — üretimde kapatılabilir.

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 steps

Her Akıl Yürütme Adımını Günlüğe Kaydetme

Her adımın başında temel bilgileri günlüğe kaydedin: adım numarası, LLM tarafından üretilen akıl yürütme, seçtiği araç ve ilettiği bağımsız değişkenler. Bu, aracının karar sürecinin eksiksiz bir kaydını oluşturur.

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'}
    )

Araç Sonuçlarını Günlüğe Kaydetme

Her araç çağrısından sonra işlemin başarılı olup olmadığını ve sonucun bir önizlemesini günlüğe kaydedin. Sonucun tamamını günlüğe kaydetmek gereğinden fazla ayrıntılı olabilir — okunabilirlik için ilk 200 karakterle kısaltın.

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)

JSON Biçimiyle Yapılandırılmış Günlükleme

Düz metin günlüklerini okumak kolaydır, ancak sorgulamak zordur. Yapılandırılmış JSON günlükleri, filtreleme, gösterge panoları ve uyarılar için günlük toplama sistemlerine (Datadog, Splunk, CloudWatch) aktarılabilir.

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'})

Ek Alanlarla Günlükleme

Filtreleme ve analiz için JSON biçimlendiricileri veya günlük toplayıcıları tarafından kullanılabilecek yapılandırılmış alanlar eklemek üzere bir günlük çağrısına extra={} iletin.

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'})

Bir Dosyaya Günlükleme

Üretim aracılarında daha sonra analiz etmek üzere bir dosyaya günlük kaydı yapın. Günlük dosyasının boyutunu sınırlamak ve diskin tükenmesini önlemek için RotatingFileHandler kullanın.

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')

Çok Kullanıcılı Aracılar İçin Oturum ID'lerini Günlüğe Kaydetme

Birden fazla kullanıcı veya görev aynı anda çalıştığında günlük kayıtları birbirine karışabilir. Belirli bir çalıştırmaya ait günlükleri filtreleyebilmek için her günlük iletisine bir oturum ID'si veya görev ID'si ekleyin.

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')

Her Adımın Süresini Ölçme

Darboğazları saptamak için her adımın günlük kaydına süre bilgisi ekleyin. Hangi araç en yavaş? LLM'nin akıl yürütmesi ne kadar sürüyor? Bu veriler iyileştirmeye yön verir.

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)

Eksiksiz Adım İzleme Şablonu

Bir aracı adımı için üretime hazır eksiksiz iz günlükleme şablonu aşağıdadır. Her adımda adım numarası, akıl yürütme, araç seçimi, bağımsız değişkenler, sonuç önizlemesi ve süre günlüğe kaydedilir — böylece aracının yürütülmesi tamamen görünür hale gelir.

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)

Üretimde Günlükleri Kapatma

Hata ayıklama iz günlükleri hassas veriler (sorgular, API yanıtları) içerir ve oldukça ayrıntılı olabilir. Üretimde hata ayıklama izlerini bastırmak için günlük düzeyini INFO veya WARNING olarak ayarlayın. Düzeyi denetlemek için bir ortam değişkeni kullanın.

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')

Bilgi Yoklaması: İz Günlüklemesi

Aracı adımları için iz günlüklemesini anlayıp anlamadığınızı sınayın.

Özet: Aracı Adımları İçin İz Günlüklemesi

Artık aracılar için eksiksiz bir iz günlükleme stratejiniz var:

İz düzeyindeki günlükleri etkinleştirmek için logging.basicConfig(level=DEBUG) kullanın
Her adımda adım numarasını, akıl yürütmeyi, araç adını ve bağımsız değişkenleri günlüğe kaydedin
Araç sonuçlarını önizleme ve başarı/başarısızlık durumuyla birlikte günlüğe kaydedin
Yapılandırılmış ve sorgulanabilir günlükler için JSON biçimlendirmesi kullanın
Çok kullanıcılı veya eşzamanlı aracılar için oturum ID'leri ekleyin
Yavaş adımları saptamak için süre bilgisi ekleyin
Günlük ayrıntı düzeyini LOG_LEVEL ortam değişkeniyle denetleyin

Sıkça Sorulan Sorular

“Aracı Adımları İçin İz Günlüğü Kaydı” dersi ücretsiz mi?

Evet — “Aracı Adımları İçin İz Günlüğü Kaydı” dersin tüm metni burada web'de ücretsiz olarak okunabilir. Etkileşimli olarak pratik yapmak (yerleşik kod editörü ve 7/24 yapay zeka koçu) ve AI Agents kursunun geri kalanını açmak için CoddyKit PRO'ya yükselt. AI Agents kursu toplamda 4 dersten oluşur.

“Aracı Adımları İçin İz Günlüğü Kaydı” dersinde ne öğreneceğim?

Olay sonrası analiz için her akıl yürütme adımını, araç çağrısını ve sonucu günlüğe kaydetme. AI Agents ile uygulamalı kodu tarayıcıda doğrudan çalıştırarak pratik yaparsın ve 7/24 yapay zeka koçu dersi çalışırken sorularını yanıtlar.

AI Agents öğrenmeye başlamak için deneyim gerekli mi?

Önceden deneyim gerekmez. CoddyKit'te AI Agents, başlangıçtan ileri seviyeye kadar yapılandırıldığı için buradan başlayabilir veya başından başlayıp kendi hızında ilerleme yapabilirsin. Bu, 4 dersinin 2. dersidir.

“Aracı Adımları İçin İz Günlüğü Kaydı” dersi ne kadar sürer?

Çoğu CoddyKit dersi yaklaşık 5–10 dakika sürer. Her biri kısa ve etkileşimli olduğu için sabit ilerleme yaparsın ve web ile uygulama arasında tam olarak bıraktığın yerden devam edebilirsin.

Bu AI Agents dersinde kod yazıp çalıştırabilir miyim?

Evet. Her AI Agents dersi yerleşik bir kod editörü içerir, bu sayede tarayıcıda gerçek kod yazıp çalıştırabilir ve anlık yapay zeka geri bildirimi alırsın — yerel kurulum gerekli değildir.

Bu kursun tüm dersleri

← AI Agents Sayfasına Dön