Ajan araç referansı

SemAgent ajanı, işleri araçlar (tools) aracılığıyla yürütür. Bu sayfa 50+ yerleşik aracın tamamını listeler: her aracın ne yaptığı, hangi katmanda olduğu ve onay davranışı. Kendi araçlarınızı MCP ile ekleyebilirsiniz — onlar da aynı politika motorundan geçer.

Araçlar nasıl çalışır

Her kullanıcı isteğinde ajan bir plan kurar ve gereken araçları sırayla çağırır. Hiçbir araç çağrısı doğrudan çalışmaz — önce politika motorundan geçer:

Kullanıcı isteği
   ↓
Planlayıcı  →  araç çağrısı önerir
   ↓
Politika motoru:  yetenek kapısı → allow-list → risk sınıfı → onay eşiği
   ↓                                                    ↓
onaysız çalışır (SAFE)                        kullanıcı onayı bekler (aksiyon)
   ↓
Araç çalışır  →  sonuç plana geri döner  →  ajan devam eder

Bu değerlendirme kod seviyesindedir; prompt ile ("kuralları yok say") aşılamaz. Ayrıntı: Otonomi & onaylar ve Güvenlik mimarisi sayfaları (yakında).

İki katman: T1 & T2

Katman	Anlamı	Onay
T1 · Hazırlık	Yan etkisiz: okuma, arama, analiz, taslak/artifact üretme. Dış dünyada kalıcı değişiklik yapmaz.	Serbest çalışır SAFE
T2 · Aksiyon	Yazma / gönderme / silme / dış sistemi değiştirme. Geri alınması zor olabilir.	Riskine göre onaylı

ℹ️

Aşağıdaki tablolardaki risk etiketleri göstergedir. Bir aracın gerçek onay davranışı; tenant'ın otonomi seviyesine (Denetimli → Otonom), araç yapılandırmasına ve "asla sessiz çalışmaz" kurallarına göre politika motorunda belirlenir. Salt-okuma araçları temelde SAFE'tir.

Bilgi & araştırma T1

Bağlam toplayan, hiçbir şeyi değiştirmeyen araçlar. Ajanın "gözleri".

Araç	Ne yapar	Risk
`kb_search`	Tenant'ın bilgi tabanında (pgvector) hibrit arama; grounding'in temeli. Kaynak parçalarını döndürür.	SAFE
`web_research`	Web'de araştırma yapar, sonuçları özetler. Sonuçlar "güvensiz içerik" olarak karantinadan geçer.	SAFE
`url_fetch`	Belirli bir URL'nin içeriğini getirir (tek sayfa).	SAFE
`apify_run`	Bir Apify actor'ünü çalıştırıp veri çeker (sosyal/scraping). Dış maliyet doğurabilir.	LOW
`social_read`	Bağlı sosyal connector'lardan gönderi/yorum okur.	SAFE
`reddit_read`	Reddit'ten (PRAW) konu/yorum okur.	SAFE

Üretim & artifact T1

Dosya ve içerik üretir; oluşturulan dosyalar tenant'ın artifact deposunda saklanır (dışarı gönderilmez). Üretilen dosyayı dışarı çıkarmak ayrı bir aksiyondur — ör. Drive'a kaydetme onaya tabidir.

Araç	Ne yapar	Risk
`doc_generate`	Word/döküman üretir (rapor, teklif, sözleşme taslağı). Sonuç Drive'a kaydedilebilir.	SAFE
`pptx_generate`	PowerPoint sunum üretir. Sonuç Drive'a kaydedilebilir.	SAFE
`xlsx_generate`	Excel tablosu üretir (veri, hesap, liste). Sonuç Drive'a kaydedilebilir.	SAFE
`image_generate`	Görsel üretir.	SAFE
`list_artifacts`	Bu görevde üretilmiş dosyaları listeler.	SAFE
`email_draft`	E-posta taslağı hazırlar — göndermez. Gönderme `email_send` ile ayrı onaya tabidir.	SAFE

Bellek & bağlam T1

Araç	Ne yapar	Risk
`recall_history`	Geçmiş konuşmaların epizodik özetlerini getirir ("geçen haftaki iş").	SAFE
`memory_save`	Kullanıcı belleğine bir gerçek/tercih kaydeder (rıza-tabanlı).	LOW
`memory_delete`	Kayıtlı bir belleği siler.	LOW
`data_aggregate`	Toplanan verileri birleştirir/özetler (hesaplama, gruplama).	SAFE

Zamanlama T1

Araç	Ne yapar	Risk
`schedule_task`	Doğal dille tekrarlı/tek-sefer görev kurar ("her sabah 8'de…").	LOW
`schedule_list`	Kurulu zamanlanmış görevleri listeler.	SAFE
`schedule_cancel`	Bir zamanlanmış görevi iptal eder.	LOW

E-posta & Gmail T2

Araç	Ne yapar	Risk
`gmail_read`	Bir e-postayı okur.	SAFE
`gmail_search`	Gelen kutusunda arama yapar.	SAFE
`email_send`	E-posta gönderir. Alıcı alan adı allow-list'e tabidir; "asla sessiz" aksiyondur.	MED
`gmail_forward`	Bir e-postayı iletir.	MED
`gmail_delete`	Bir e-postayı siler — geri alınamaz.	HIGH
`gmail_attachments`	E-posta eklerini listeler / güvenli karantinaya indirir (Drive'a yüklemek için). `extract_text=true` ile ekin içindeki metni de okur — PDF, Word, Excel, CSV; taranmış PDF'te OCR. Çıkan metin dış içerik sayılıp karantinadan geçer.	SAFE

Takvim & Drive

Araç	Ne yapar	Risk
`calendar_list_events`	Takvim etkinliklerini listeler.	SAFE
`calendar_create_event`	Takvimde etkinlik oluşturur (davetli ekleyebilir).	MED
`calendar_delete_event`	Bir etkinliği siler.	MED
`drive_read`	Google Drive'dan dosya okur ve içindeki metni çıkarır — PDF, Word (docx), Excel (xlsx), CSV ve düz metin; taranmış (görüntü tabanlı) PDF'te OCR devreye girer.	SAFE
`drive_upload`	Drive'a dosya yükler. İki kaynaktan: mail eki (karantinadaki dosya) ve ajanın kendi ürettiği dosya — `xlsx_generate` / `doc_generate` / `pptx_generate` çıktısı (`artifact` kaynağı). Klasör yoksa oluşturulur; iç içe yol verilebilir.	LOW

🔒

Drive yetki kapsamı — tek-tık bağlantı yalnız kendi dosyalarını görür. Tek tıkla kurduğunuz Drive Yükleme bağlantısı Google'ın drive.file kapsamıyla çalışır: ajan yalnız kendi oluşturduğu dosya ve klasörleri görebilir. Sizin elle açtığınız bir klasörü göremez, dolayısıyla doğrudan oraya yazamaz. İki yol var: (a) hedef klasör ağacını ajana kurdurun ve bundan sonra hep onu kullanın, ya da (b) Kasa'ya tam drive kapsamlı bir Google kimliği (kendi OAuth'unuzun refresh token'ı / service-account) koyun.

Veri & sistem T2

Araç	Ne yapar	Risk
`http_request`	Dış bir API/endpoint'e HTTP isteği yapar. Hedef egress allow-list'ine tabidir.	MED
`db_query`	Bağlı veritabanında sorgu çalıştırır. Hedef ve yazma yetkisi allow-list ile sınırlıdır.	HIGH

E-ticaret (Shopify) T2

Araç	Ne yapar	Risk
`shopify_query`	Mağazadan canlı veri okur (ürün, stok, sipariş, müşteri) — GraphQL query.	MED
`shopify_mutation`	Mağazada değişiklik yapar (stok, sipariş, iade vb.) — GraphQL mutation.	HIGH

🛍️

Widget içindeki müşteri-yüzlü e-ticaret cevapları ayrıca search_products, search_orders, get_order_detail, search_customers gibi salt-okuma yardımcılarını kullanır. Ayrıntı: Shopify & e-ticaret (yakında).

Mesajlaşma & kanallar T2

Araç	Ne yapar	Risk
`whatsapp_send`	WhatsApp mesajı gönderir (API).	HIGH
`whatsapp_qr_send`	QR-bağlı (Baileys) WhatsApp hattından mesaj gönderir.	HIGH
`sms_send`	SMS gönderir.	HIGH
`call_make`	Otomatik sesli arama başlatır (Make/telefon entegrasyonu).	HIGH

Sosyal yayınlama T2

Araç	Ne yapar	Risk
`social_channels`	Bağlı yayınlama kanallarını (Postiz) listeler.	LOW
`social_post`	Sosyal medyada gönderi yayınlar/zamanlar (Postiz). Herkese açık aksiyondur.	HIGH

Orkestrasyon T2

Araç	Ne yapar	Risk
`delegate_task`	Büyük bir işi alt-ajan(lar)a böler; uzun işlerde ara-durum mesajları döner.	HIGH

Kendi araçlarınız (MCP)

Yerleşik 50+ araç yetmezse, kendi MCP sunucunuzu bağlayabilirsiniz. Sunucunun açtığı araçlar otomatik keşfedilir ve aynı politika motorundan geçer — yani onlar da T1/T2 sınıfına, allow-list'lere ve onay eşiklerine tabidir. Ayrıntı: MCP ile araç ekleme (yakında).

⚠️

Konfabulasyon koruması: Bir araç boş ya da hatalı sonuç dönerse ajan sebep uydurmaz; bir teşhis notuyla ("olası nedenler…") durumu raporlar. Bu, "token bitti/erişim engellendi" gibi yanlış gerekçelerin önüne geçer.

Bu sayfa yardımcı oldu mu? Geri bildirim gönder

← Önceki Bilgi tabanı oluşturma Sonraki → Docs ana sayfa