Otonom Yapay Zeka Ajanı Oluşturma: LangChain Agent Rehberi

Yazar:komut.io ekibi
0 Yorum

Yapay zeka dünyasında “agent” kavramı artık sadece akademik bir terim değil. Üretimde çalışan, gerçek görevleri yerine getiren, kararlar alan sistemler haline geldi. LangChain Agent, bu dönüşümün tam merkezinde duruyor. Bir LLM’e araçlar verip onu serbest bıraktığınızda ne olur? İşte bu yazıda tam olarak bunu inceliyoruz, hem teorik altyapıyı hem de production’da karşılaşacağınız gerçek senaryoları ele alıyoruz.

LangChain Agent Nedir ve Neden Önemlidir?

Klasik LLM kullanımında akış bellidir: kullanıcı bir şey sorar, model cevap verir, iş biter. Ama gerçek dünyada işler bu kadar basit değil. Bir soruyu cevaplamak için önce internette arama yapmak, sonra bir veritabanına bakmak, ardından hesaplama yapmak ve nihayetinde bu bilgileri sentezlemek gerekebilir.

LangChain Agent tam burada devreye giriyor. ReAct (Reason + Act) döngüsüyle çalışır: düşün, harekete geç, sonucu gözlemle, tekrar düşün. Bu döngü, modele gerçek anlamda “ajanlık” yeteneği kazandırıyor.

Sysadmin perspektifinden bakarsak: Agent’ı, komut satırından birden fazla aracı çağırabilen, sonuçları değerlendirip bir sonraki adımını belirleyebilen bir otomasyon motoru olarak düşünebiliriz. bash scriptlerinin yerini almaz, ama belirsiz ve dinamik görevleri çözmekte çok daha esnektir.

Ortam Kurulumu

Önce temel bağımlılıkları kuralım. Python 3.10+ önerilir.

# Sanal ortam oluştur
python3 -m venv langchain-agent-env
source langchain-agent-env/bin/activate

# Temel paketleri kur
pip install langchain langchain-openai langchain-community
pip install python-dotenv
pip install duckduckgo-search
pip install wikipedia

# Versiyonları kontrol et
pip show langchain | grep Version
pip show langchain-openai | grep Version

API anahtarlarını yönetmek için .env dosyası oluşturun. Bu dosyayı asla Git’e commit etmeyin.

# .env dosyası oluştur
cat > .env << 'EOF'
OPENAI_API_KEY=sk-your-key-here
SERPAPI_API_KEY=your-serpapi-key-here
EOF

# .gitignore'a ekle
echo ".env" >> .gitignore
echo "*.env" >> .gitignore

İlk Agent: Temel Yapı

En basit agent örneğiyle başlayalım. Bu örnek, ajanın nasıl düşündüğünü ve araçları nasıl seçtiğini gösterir.

cat > basic_agent.py << 'EOF'
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import create_react_agent, AgentExecutor
from langchain.tools import DuckDuckGoSearchRun
from langchain import hub

load_dotenv()

# LLM tanımla
llm = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0,      # Determinizm için 0
    max_tokens=4096
)

# Araçları tanımla
search_tool = DuckDuckGoSearchRun()
tools = [search_tool]

# ReAct prompt'unu hub'dan çek
prompt = hub.pull("hwchase17/react")

# Agent oluştur
agent = create_react_agent(llm, tools, prompt)

# AgentExecutor - agent'ı yöneten sarmalayıcı
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,           # Düşünme sürecini göster
    max_iterations=5,       # Sonsuz döngüyü önle
    handle_parsing_errors=True
)

# Çalıştır
result = agent_executor.invoke({
    "input": "Python 3.12'nin en önemli yenilikleri neler? Kısaca özetle."
})

print("n=== SONUÇ ===")
print(result["output"])
EOF

python3 basic_agent.py

verbose=True ile agent’ın “Thought -> Action -> Observation” döngüsünü canlı izleyebilirsiniz. Production’da bunu kapatın ama development aşamasında açık tutmak altın değerinde.

Özel Araçlar Yazmak

DuckDuckGo araması güzel ama gerçek gücü özel araçlar yazarken görüyorsunuz. Bir sysadmin senaryosu düşünelim: agent’ın sunucu durumunu kontrol edip, disk kullanımını analiz etmesini ve log dosyalarında hata aramasını istiyoruz.

cat > sysadmin_tools.py << 'EOF'
import subprocess
import os
from langchain.tools import tool
from typing import Optional

@tool
def check_disk_usage(path: str = "/") -> str:
    """
    Belirtilen dizinin disk kullanımını kontrol eder.
    Path parametresi kontrol edilecek dizini belirtir.
    Örnek: check_disk_usage("/var/log")
    """
    try:
        result = subprocess.run(
            ["df", "-h", path],
            capture_output=True,
            text=True,
            timeout=10
        )
        return result.stdout
    except Exception as e:
        return f"Hata: {str(e)}"

@tool
def search_logs(
    log_file: str,
    pattern: str,
    lines: int = 50
) -> str:
    """
    Log dosyasında belirtilen pattern'ı arar ve sonuçları döndürür.
    log_file: Aranacak log dosyasının tam yolu
    pattern: Aranacak metin veya pattern
    lines: Döndürülecek maksimum satır sayısı
    """
    try:
        if not os.path.exists(log_file):
            return f"Dosya bulunamadı: {log_file}"

        result = subprocess.run(
            ["grep", "-n", pattern, log_file],
            capture_output=True,
            text=True,
            timeout=15
        )

        lines_list = result.stdout.strip().split("n")
        limited = lines_list[:lines]
        return f"Bulunan satır sayısı: {len(lines_list)}nn" + "n".join(limited)
    except Exception as e:
        return f"Hata: {str(e)}"

@tool
def get_system_load() -> str:
    """
    Sistemin anlık CPU ve memory kullanımını döndürür.
    Parametre gerektirmez.
    """
    try:
        uptime = subprocess.run(["uptime"], capture_output=True, text=True)
        free = subprocess.run(["free", "-h"], capture_output=True, text=True)

        return f"Uptime:n{uptime.stdout}nnMemory:n{free.stdout}"
    except Exception as e:
        return f"Hata: {str(e)}"

@tool
def list_top_processes(count: int = 10) -> str:
    """
    CPU kullanımına göre sıralanmış üst N prosesi listeler.
    count: Listelenecek proses sayısı (varsayılan: 10)
    """
    try:
        result = subprocess.run(
            ["ps", "aux", "--sort=-%cpu"],
            capture_output=True,
            text=True
        )
        lines = result.stdout.strip().split("n")
        return "n".join(lines[:count + 1])  # Header dahil
    except Exception as e:
        return f"Hata: {str(e)}"
EOF

Bu araçlar hazır. Şimdi bunları bir agent’a bağlayalım.

Sysadmin Agent: Gerçek Senaryo

cat > sysadmin_agent.py << 'EOF'
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import create_react_agent, AgentExecutor
from langchain import hub
from sysadmin_tools import (
    check_disk_usage,
    search_logs,
    get_system_load,
    list_top_processes
)

load_dotenv()

llm = ChatOpenAI(model="gpt-4o", temperature=0)

tools = [
    check_disk_usage,
    search_logs,
    get_system_load,
    list_top_processes
]

prompt = hub.pull("hwchase17/react")

agent = create_react_agent(llm, tools, prompt)
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,
    max_iterations=8,
    handle_parsing_errors=True
)

# Gerçek dünya senaryosu: Sistem sağlık raporu oluştur
query = """
Şu anda sistemin genel durumunu analiz et:
1. CPU ve memory kullanımını kontrol et
2. Root dizinin disk doluluk oranına bak
3. En çok CPU kullanan 5 prosesi listele
4. Tüm bu bilgileri bir sysadmin raporu formatında özetle ve varsa sorunları belirt
"""

result = agent_executor.invoke({"input": query})
print("n" + "="*60)
print("SISTEM SAGLIK RAPORU")
print("="*60)
print(result["output"])
EOF

python3 sysadmin_agent.py

Memory ile Konuşmayı Sürdürme

Stateless agent’lar tek seferlik görevler için iyi, ama çok adımlı diyaloglar için memory şart. LangChain’in ConversationBufferMemory ile bunu nasıl ekleyeceğimize bakalım.

cat > agent_with_memory.py << 'EOF'
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import create_react_agent, AgentExecutor
from langchain.memory import ConversationBufferWindowMemory
from langchain import hub
from langchain.tools import DuckDuckGoSearchRun, WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

load_dotenv()

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.1)

# Memory: Son 5 konuşma turunu hatırla
memory = ConversationBufferWindowMemory(
    memory_key="chat_history",
    k=5,                        # Son 5 tur
    return_messages=True
)

wikipedia = WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
search = DuckDuckGoSearchRun()

tools = [search, wikipedia]

# Memory destekli prompt
prompt = hub.pull("hwchase17/react-chat")

agent = create_react_agent(llm, tools, prompt)
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    memory=memory,
    verbose=False,
    max_iterations=6,
    handle_parsing_errors=True
)

print("Agent hazır. Çıkmak için 'quit' yazın.n")

while True:
    user_input = input("Sen: ").strip()

    if user_input.lower() in ["quit", "exit", "çık"]:
        print("Görüşürüz!")
        break

    if not user_input:
        continue

    try:
        response = agent_executor.invoke({"input": user_input})
        print(f"nAgent: {response['output']}n")
    except Exception as e:
        print(f"Hata oluştu: {str(e)}n")
EOF

python3 agent_with_memory.py

OpenAI Functions Agent: Daha Güvenilir Araç Çağrısı

ReAct pattern metin tabanlı parsing yaptığı için zaman zaman parse hataları verebilir. OpenAI’nin function calling özelliğini kullanan agent çok daha güvenilir.

cat > functions_agent.py << 'EOF'
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import create_openai_functions_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain.tools import tool
import requests
import json

load_dotenv()

@tool
def get_weather(city: str) -> str:
    """Belirtilen şehrin hava durumunu getirir. city: Şehir adı (İngilizce)"""
    try:
        url = f"https://wttr.in/{city}?format=j1"
        response = requests.get(url, timeout=10)
        data = response.json()

        current = data["current_condition"][0]
        temp_c = current["temp_C"]
        feels_like = current["FeelsLikeC"]
        description = current["weatherDesc"][0]["value"]
        humidity = current["humidity"]

        return (
            f"{city} hava durumu:n"
            f"Sıcaklık: {temp_c}°C (Hissedilen: {feels_like}°C)n"
            f"Durum: {description}n"
            f"Nem: %{humidity}"
        )
    except Exception as e:
        return f"Hava durumu alınamadı: {str(e)}"

@tool
def calculate(expression: str) -> str:
    """
    Matematiksel ifadeyi hesaplar.
    Sadece sayısal ifadeler kabul edilir.
    Örnek: calculate("2 ** 10") veya calculate("1024 / 8")
    """
    try:
        # Güvenli eval - sadece matematiksel operatörlere izin ver
        allowed_chars = set("0123456789+-*/()., ")
        if not all(c in allowed_chars for c in expression):
            return "Güvensiz ifade. Sadece matematiksel operatörler kullanın."

        result = eval(expression)
        return f"{expression} = {result}"
    except Exception as e:
        return f"Hesaplama hatası: {str(e)}"

# Function calling için özel prompt
prompt = ChatPromptTemplate.from_messages([
    ("system", """Sen yardımcı bir asistansın. 
    Kullanıcının sorularını yanıtlamak için mevcut araçları kullanabilirsin.
    Her zaman Türkçe yanıt ver."""),
    MessagesPlaceholder(variable_name="chat_history", optional=True),
    ("human", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad")
])

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
tools = [get_weather, calculate]

agent = create_openai_functions_agent(llm, tools, prompt)
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,
    max_iterations=5
)

# Test
questions = [
    "İstanbul'un hava durumu nasıl?",
    "2^16 kaç eder?",
    "Hem Ankara hem İzmir'in hava durumunu karşılaştır"
]

for q in questions:
    print(f"nSoru: {q}")
    print("-" * 40)
    result = agent_executor.invoke({"input": q})
    print(f"Yanıt: {result['output']}")
EOF

python3 functions_agent.py

Multi-Agent Orkestrasyon

Tek bir agent her şeyi yapabilir ama büyük projelerde uzmanlaşmış agent’ları orkestre etmek çok daha etkili. Basit bir multi-agent setup örneği:

cat > multi_agent.py << 'EOF'
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import create_openai_functions_agent, AgentExecutor
from langchain.tools import tool, DuckDuckGoSearchRun
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

load_dotenv()

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
search = DuckDuckGoSearchRun()

# ---- Araştırma Agent'ı ----
research_prompt = ChatPromptTemplate.from_messages([
    ("system", "Sen bir araştırma uzmanısın. Verilen konuyu internette araştır ve kapsamlı bilgi topla. Türkçe yanıt ver."),
    ("human", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad")
])

research_agent = AgentExecutor(
    agent=create_openai_functions_agent(llm, [search], research_prompt),
    tools=[search],
    max_iterations=4,
    handle_parsing_errors=True
)

# ---- Analiz Agent'ı ----
@tool
def research_topic(topic: str) -> str:
    """Belirtilen konuyu araştırır ve detaylı bilgi döndürür."""
    result = research_agent.invoke({"input": f"Şu konu hakkında araştır: {topic}"})
    return result["output"]

analysis_prompt = ChatPromptTemplate.from_messages([
    ("system", """Sen bir analiz uzmanısın. 
    Verilen bilgileri analiz et, artı ve eksileri belirle, sonuç çıkar.
    Raporunu yapılandırılmış formatta sun. Türkçe yanıt ver."""),
    ("human", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad")
])

analysis_agent = AgentExecutor(
    agent=create_openai_functions_agent(llm, [research_topic], analysis_prompt),
    tools=[research_topic],
    max_iterations=3,
    verbose=True
)

# Orkestrasyon: Analiz agent'ı, araştırma agent'ını bir araç olarak kullanır
topic = "Kubernetes vs Docker Swarm 2024 karşılaştırması"
print(f"Konu analiz ediliyor: {topic}n")

result = analysis_agent.invoke({
    "input": f"Şu konuyu araştır ve kapsamlı analiz raporu hazırla: {topic}"
})

print("n" + "="*60)
print("ANALİZ RAPORU")
print("="*60)
print(result["output"])
EOF

python3 multi_agent.py

Production’da Dikkat Edilecekler

Geliştirme ortamında her şey güzel çalışıyor, ama production’a almadan önce birkaç kritik noktayı ele alalım.

Maliyet kontrolü: Her max_iterations bir LLM çağrısı demektir. Gereksiz yere yüksek değer vermeyin.

# Token kullanımını izlemek için basit bir wrapper
cat > cost_aware_agent.py << 'EOF'
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.callbacks import get_openai_callback
from langchain.agents import create_openai_functions_agent, AgentExecutor
from langchain.tools import DuckDuckGoSearchRun
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

load_dotenv()

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
search = DuckDuckGoSearchRun()

prompt = ChatPromptTemplate.from_messages([
    ("system", "Yardımcı bir asistansın. Türkçe yanıt ver."),
    ("human", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad")
])

agent = create_openai_functions_agent(llm, [search], prompt)
agent_executor = AgentExecutor(
    agent=agent,
    tools=[search],
    max_iterations=5
)

# Maliyet takibi ile çalıştır
with get_openai_callback() as cb:
    result = agent_executor.invoke({
        "input": "LangChain'in en son versiyonu nedir ve yenilikleri neler?"
    })

    print(f"nYanıt: {result['output']}")
    print("n--- MALİYET ANALİZİ ---")
    print(f"Toplam Token: {cb.total_tokens}")
    print(f"Prompt Token: {cb.prompt_tokens}")
    print(f"Completion Token: {cb.completion_tokens}")
    print(f"Toplam Maliyet: ${cb.total_cost:.6f}")
EOF

python3 cost_aware_agent.py

Hata yönetimi ve retry: Production’da ağ hataları, rate limit gibi durumlar kaçınılmaz.

  • handle_parsing_errors=True: Parsing hatalarında agent’ın crash olmasını önler
  • max_iterations: Sonsuz döngüyü kesinlikle önleyin, 5-10 arası genelde yeterli
  • max_execution_time: Saniye cinsinden maksimum çalışma süresi belirleyin
  • return_intermediate_steps=True: Debug için ara adımları kaydedin
  • Tool bazlı timeout: Her araç çağrısında subprocess.run(..., timeout=15) gibi timeout ekleyin
  • Rate limiting: OpenAI API rate limit’e çarpmamak için tenacity kütüphanesiyle retry mekanizması kurun
  • Logging: Agent’ın ne yaptığını logging modülüyle kayıt altına alın
  • Input validation: Kullanıcı girdisini agent’a göndermeden önce sanitize edin

Güvenlik notları:

  • Shell komutu çalıştıran araçlarda kullanıcı girdisini asla doğrudan kullanmayın
  • Araçları minimum yetki prensibine göre tasarlayın
  • Hassas bilgilere (API key, password) erişebilecek araçları agent’a vermeyin
  • Production’da verbose=False kullanın, log’ları güvenli bir yere yönlendirin

Sonuç

LangChain Agent, otomasyon dünyasında gerçekten yeni bir paradigma sunuyor. Klasik scriptlerin önceden tüm senaryoları bilmesi gerekir, ama agent’lar belirsizliği idare edebilir. Birden fazla araç arasında dinamik olarak seçim yapar, hataları gözlemleyip alternatif yol dener ve görevin ne olduğunu anlayarak adımları kendisi planlar.

Sysadmin olarak bu teknolojiyi nerede kullanabilirsiniz? Sistem sağlık raporları oluşturmak, log analizi yapmak, dokümantasyon aramak ve özetlemek, rutin sorunları diagnose etmek ve kullanıcı taleplerine göre dinamik scriptler üretmek bunların başında geliyor.

Elbette her şeyin bir agent’a ihtiyacı yok. Basit, belirli girdi-çıktısı olan işler için klasik scripting hala en doğru tercih. Agent’lar en çok belirsiz, çok adımlı, bağlam gerektiren görevlerde parlıyor.

Başlangıç için önerim: küçük ve odaklı bir araç seti ile başlayın, verbose=True ile agent’ın düşünce sürecini iyice anlayın, maliyet kontrolünü baştan kurun ve production’a almadan önce mutlaka güvenlik katmanını ekleyin. Bu temeli sağlam attıktan sonra multi-agent orkestrasyona geçmek çok daha kolay olacak.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir