agentlite

Proje Özeti

Python'da Claude tabanlı agent yazarken iki yaygın yol var: ya Anthropic SDK'sını doğrudan kullanır, agent loop'u, prompt caching'i, izin sistemini el ile yazarsın; ya da LangChain gibi büyük bir çerçeveye geçer, ~150 bin satır soyutlamayla debug edersin. agentlite bu boşluğu doldurur: ~2.000 satırlık odaklı kod, agent döngüsü + tool tanımları + prompt caching + permission system her şey içeride.

MIT lisanslı, PyPI'da kurulabilir, %80 unit test kapsamı, 4 Python sürümünde CI yeşil (3.10–3.13). Anthropic'in resmi SDK'sının üzerine bilinçli mimari kararlarla bir katman ekler — Modül 4 fail-safe felsefesi, Modül 5 prompt-caching disiplini, Modül 6 multi-agent kompozisyonu üretim seviyesi disiplinle taşınır.

Kullanım — 8 Satırda Çalışan Agent

$ pip install agentlite-py

Not: PyPI'da dağıtım adı agentlite-py, Python import adı agentlite.

from agentlite import Agent, tool

@tool
def get_weather(city: str) -> str:
    """Bir şehrin güncel hava durumunu döndür."""
    return f"{city}: 22°C, güneşli"

agent = Agent(model="claude-opus-4-7", tools=[get_weather])
agent.run("İstanbul'da hava nasıl?")

Hepsi bu. Type hints'ten JSON Schema otomatik üretilir, docstring modele talimat olur, döngü kütüphanenin içinde yönetilir. Boilerplate yok.

Öne Çıkan Özellikler

Özellik	Ne yapar
`@tool` decorator	Python fonksiyonu → `Tool` nesnesi (introspection ile şema otomatik)
Agent döngüsü	tool_use ↔ tool_result feedback loop + `max_turns` güvenlik freni
Streaming	`agent.stream_text()` — token başına çıktı (UX için)
Prompt caching	Varsayılan AÇIK — system prompt + tools otomatik `cache_control`, ~%80 tasarruf
Permission system	`@tool(requires_confirmation=True)` → kullanıcıya soruluyor, deny → modele bildiriliyor
Dependency injection	Custom `client` ve `confirm_fn` → mock'la test, üretimde GUI/Slack ile bağla

Mimari

Tek bir while döngüsü etrafında dönen 3 katman. Anthropic SDK'sı en altta, Tool tarafımız sözleşmeyi belirler, Agent sınıfı orkestrasyondur.

kullanıcı_mesajı │ ▼ [ Agent.run ] ────────────────────────┐ │ │ ▼ │ [ messages.create ] ── tools + system │ while turn ≤ max_turns: │ + cache_control │ ▼ │ stop_reason == "end_turn"? ─── EVET ──┴──► son metni döndür │ │ HAYIR (tool_use) ▼ [ permission check ] ── read_only? confirm? deny? │ ▼ izin verildi [ tool.call(**input) ] │ ▼ tool_result → messages'a ekle → DÖNGÜ BAŞA

Tasarım Kararları

Az soyutlama, çok ölçüm. ~2K LOC, %80 test kapsamı. LangChain'in "her şey lego" felsefesinin tersi — küçük yüzey alanı, anlaşılır debug.
Varsayılan AÇIK güvenlik. Prompt caching, max_turns freni, type hint zorunluluğu — kullanıcı bilinçli olarak kapatmadıkça doğru olan otomatik.
Polymorphic decorator. @tool ve @tool(...) ikisi de çalışır; eski kullanıcı kodu kırılmaz.
Dependency injection — client ve confirm_fn dışarıdan verilebilir; test edilebilirlik birinci sınıf vatandaş.

Karşılaştırma

	LangChain	OpenAI Agents	Anthropic SDK	agentlite
LoC	~150K	~5K	SDK içinde	~2K
Prompt caching	manuel	yok	manuel	otomatik
Permission model	yok	yok	yok	built-in
Birincil model	vendor-agnostik	OpenAI	Anthropic	Anthropic-first
Öğrenme eğrisi	dik	orta	düşük	çok düşük

Teknik Yığın

Dil: Python 3.10+
Bağımlılık: sadece anthropic (bilinçli tek dış paket)
Paket yapısı: src/ layout, pyproject.toml (modern, setup.py yok)
Test: pytest, 17 unit test, %80 kapsam, 0.4s'de koşar
CI: GitHub Actions, Python 3.10 / 3.11 / 3.12 / 3.13 matrix
Tip kontrolü: mypy (strict mode)
Lint: ruff
Lisans: MIT

Bir Sonraki Adımlar (Yol Haritası)

🚧 v0.2 — streaming + tool döngüsü entegrasyonu
🚧 v0.3 — sub-agent spawning (@subagent)
🚧 v0.4 — multi-provider (OpenAI, Gemini ek backend)
🚧 v0.5 — MCP server desteği
🎯 v1.0 — kararlı API, semantic versioning, üretim önerisi