agent_aid 1.3.0

Local Windows desktop control for AI agents — Python library and CLI.

agent-aid

Yerel Windows masaüstünü AI ajanlardan kontrol etmek için küçük bir Python kütüphanesi ve CLI. Open Interpreter, GPT, Claude veya kendi yazdığın bir agent — agent-aid komutuyla ekran okuma, fare/klavye kontrolü, pencere yönetimi yapar. Tek bağımlılık: mss.

pip install agent-aid

uv ile (önerilen — Python yoksa otomatik indirir):

uv tool install agent-aid --python 3.11

Hızlı bakış

agent-aid health
agent-aid state
agent-aid screenshot active_window=true save_path=captures/active.png include_base64=false
agent-aid click x=500 y=300
agent-aid type text="merhaba"
agent-aid press keys=ctrl+s
agent-aid focus_window title_fragment=Chrome
agent-aid open target=https://example.com

Tüm route'lar:

agent-aid --list

AI ajanlar için tam komut referansı (stdout'a markdown):

agent-aid --readme

Yetenekler

• Ekran görüntüsü: tam masaüstü, tek monitör, aktif pencere, belirli hwnd, dikdörtgen bölge
• Karşılaştırma için PNG sha256 hash'i (wait_screen_change ile birlikte kullanılır)
• Fare: tıkla, çift tıkla, sağ tık, sürükle, hareket ettir, kaydır (dikey/yatay), basılı tut
• Klavye: kısa metin, hotkey (ctrl+shift+a), modifier'ları el ile aç/kapa
• Pano: clipboard text=... + press keys=ctrl+v ile uzun metin yapıştırma
• Pencere: bul, odakla, küçült/büyüt/restore/kapat, taşı/yeniden boyutlandır, gizle/göster
• Sistem: süreç listesi, dosya/URL/shell aç, pixel oku, durum sorgula
• Verify: wait_screen_change, wait_pixel, wait_window
• batch ile birden fazla aksiyonu tek çağrıda atomik çalıştırma

Pencere/koordinat hedefleme

Tüm koordinatlar fiziksel ekran pikselidir. Belirli pencerenin içine göre çalışmak için:

agent-aid click x=120 y=80 relative_to=active_window
agent-aid click x=120 y=80 hwnd=123456

Python kütüphanesi olarak kullanım

from agent_aid import core

core.set_dpi_aware()
print(core.active_window())
core.click(800, 500)
core.type_text("merhaba")

CLI ile aynı yetenekler — Python kodunda doğrudan core modülünü çağırırsın.

Komut formatları

# key=value (en kısa)
agent-aid click x=500 y=300 button=left

# JSON (iç içe alanlar için)
agent-aid screenshot '{"region":{"left":0,"top":0,"width":800,"height":600},"save_path":"r.png"}'

# Çıktıyı pretty-print
agent-aid --pretty state

AI agent için pratik akış

1. agent-aid state — neye baktığını gör
2. agent-aid screenshot active_window=true save_path=captures/now.png include_base64=false
3. Görüntüye bak, hedef koordinatı seç
4. Aksiyon: click / type / press / clipboard
5. Doğrula: yeni screenshot veya wait_screen_change

Güvenlik notları

• Gerçek fare ve klavye girdisi gönderir — etkin pencereye yazar.
• clipboard panoyu üzerine yazar.
• open Windows hedefini başlatır (kullanıcı çift tıklamış gibi).
• window/manage close WM_CLOSE postalar — kaydedilmemiş veri varsa uygulama sorabilir.
• Aksiyon sonrası wait_* veya yeni screenshot ile doğrulama yapmak önerilir.

Lisans

MIT.