Ajan Connector'ları

Connector, ajana dış dünyada iş yapma yeteneği verir: e-posta gönderir, SMS atar, Shopify'da sipariş okur, takvime etkinlik ekler. Bağlanan her servis ajanın araç setine yeni araçlar ekler — ve her araç çağrısı politika motorundan geçer.

Önce şunu netleştirelim: iki ayrı connector var

SemAgent'ta "connector" kelimesi iki farklı ekranda geçer. Karıştırmak en sık yapılan hatadır.

Üçüncü bir ekran daha var: Sosyal Medya Connector'ları (/settings/social-connectors) — ayrı bir sistemdir ve ayrı bir bayrağın arkasındadır.

Bir connector nasıl bağlanır?

1. Yönetim paneli → Ayarlar → Connectors ekranını açın. Kartlar Öne çıkanlar ve Daha fazlası sekmelerine ayrılmıştır.
2. Bir kartın üzerine tıklayın. Açılan pencerede servisin açıklaması, açacağı araçlar, kurulum notu ve gerekli alanlar görünür.
3. Alanları doldurup Bağla'ya basın. Kimlik bilgileri Ajan Kasası'na şifreli yazılır.
4. Test et ile canlı doğrulayın. Test yan etkisizdir — örneğin SMTP testi sunucuya bağlanıp giriş yapar ama mail göndermez.

Bağlanan kart yeşil Bağlı rozeti alır. Sonradan Yeniden yapılandır ile alanları güncelleyebilir, Bağlantıyı kaldır ile sökebilirsiniz.

Aynı servisten birden fazla hesap

Bir servisle tek hesaba mahkûm değilsiniz. Aynı connector'a birden fazla hesap bağlayabilir, her birine bir takma ad verebilirsiniz — ör. "Ana Hesap", "Muhasebe". Ajanla konuşurken bu adı kullanırsınız:

Ana Hesap hesabıyla bu haftaki siparişleri listele

Araçlar bunun için bir account parametresi alır (account="Ana Hesap"); ajan takma adı kendisi eşleştirir.

Devralınan hesabın adı nereden gelir? Ad, bağlantının gerçek kimliğinden türetilir: e-posta adresi, mağaza alan adı gibi. Türetilecek bir kimlik yoksa servis adıyla adlandırılır ("Mevcut Google"); kimlik yalnızca bir numaraysa başına servis adı gelir ("Etsy 63288487"). Ad sabit değildir — satır-içi kalem simgesiyle dilediğiniz gibi değiştirebilirsiniz; ajan sizin verdiğiniz adı kullanır.

Gmail'e kendi OAuth uygulamanızla bağlandıysanız bu bağlantı da algılanır — devralma için uygulama şifresi ya da IMAP şart değildir.

Panelde nasıl görünür

Connectors ekranında her servis tek karttır; kartın içinde o servise bağlı hesapların listesi yer alır. Her satırda:

• Takma ad — ajana söyleyeceğiniz isim.
• Kimlik girildi rozeti — o hesabın kimlik bilgileri Kasa'ya yazılmış mı?
• "mevcut" rozeti — çoklu hesaptan önce kurulmuş, devralınan bağlantı (yukarıdaki nota bakın).
• Varsayılan yıldızı — belirsizlikte kullanılacak hesap.
• Aç / kapa — hesabı silmeden geçici olarak devre dışı bırakır; kapalı hesap ajana hiç görünmez.
• Düzenle (kalem) — o hesabın adını ve kimlik bilgilerini değiştirir.
• Sil — hesap kaydını kaldırır.

Yeni hesap eklemek için kartın içindeki Hesap ekle'yi kullanın: takma adı yazın, servisin alanlarını doldurun, Test et ile canlı doğrulayın.

Neden satır-içi düzenleme? Kartın üstündeki genel Yeniden yapılandır, birden fazla hesap varken hangisini değiştirdiği belirsiz kalıyordu. Bu yüzden her hesabın kendi kalem simgesi var — düzenleme her zaman tek bir hesaba işler.

Hesap ekleme formu: her alanın açıklaması var

Formda ham teknik anahtar adları (drive_oauth_client_id gibi) değil, etiket + açıklama görürsünüz: hangi değerin istendiği, nereden alınacağı ve beklenen biçim yazılıdır. Örnek — Google Drive (okuma) hesabı:

• İstenen şey servis-hesabı JSON dosyasının tam içeriğidir — dosya yolu ya da e-posta değil. Çok satırlı bir alandır ve içerik { ile başlar.
• Kişisel Drive'da okunmasını istediğiniz klasörü, JSON'ın içindeki client_email adresiyle paylaşmanız gerekir; paylaşılmayan klasör servis-hesabına görünmez.

Hangi servislerde çalışır?

Kasa-token'lı servisler (Printify, Notion gibi) zaten çoklu kimliği destekliyordu: Kasa'ya farklı isimlerle sır koyar, ajana auth_secret adıyla hangisini kullanacağını söylersiniz.

Bağlanma tipleri

Her connector'ın bir bağlanma tipi vardır; bu tip, arkada ne olduğunu ve "bağlı" sayılma koşulunu belirler.

Bağlanabilen connector'lar

Aşağıdakiler bugün çalışır durumda — panelden bağlayıp test edebilirsiniz. "Açtığı araçlar" sütunu, bağlandıktan sonra ajanın kullanabileceği araçları gösterir.

E-ticaret

• Shopify nasıl bağlanır? Mağaza domaininizi (magaza.myshopify.com) girip Bağla'ya basın. Storefront MCP araçları açılır — katalog araması, salt-okuma.
• Shopify (Admin API) nasıl bağlanır? Mağaza domaini, Client ID ve Client Secret girin. shopify_query (oku) ve shopify_mutation (yaz) araçları açılır.
• Printify nasıl bağlanır? Printify API token'ınızı girin. Ajan http_request ile Printify API'sine erişir (ürünler, mağazalar, siparişler).
• Etsy nasıl bağlanır? Etsy API keystring'inizi girin. Okuma için yeterlidir; mağaza adına yazma ayrıca OAuth ister.

İletişim

• E-posta (SMTP) nasıl bağlanır? SMTP sunucusu, port, kullanıcı adı, şifre ve gönderen adresini girin. Ajan email_send ile e-posta gönderebilir.
• SMS (Twilio) nasıl bağlanır? Account SID, Auth Token ve Twilio'dan satın aldığınız gönderen numarayı girin. sms_send ve call_make açılır.
• SMS (NetGSM) nasıl bağlanır? NetGSM kullanıcı kodunuzu (abone no), şifrenizi ve NetGSM'de onaylı mesaj başlığınızı girin. sms_send açılır.
• WhatsApp Business (Resmi) nasıl bağlanır? Meta uygulamanızdaki Phone Number ID'yi ve kalıcı (system-user) erişim token'ını girin. whatsapp_send açılır.
• WhatsApp (QR oturum) nasıl bağlanır? Kart üzerinden QR oluşturup telefonunuzdan okutun. whatsapp_qr_send açılır.

SMTP: Gmail kullanıyorsanız 2 Adımlı Doğrulama açıp bir Uygulama Şifresi üretmeniz gerekir; normal hesap şifresi çalışmaz.

NetGSM: Mesaj başlığının NetGSM tarafında onaylı olması gerekir. Test, bakiye ucundan kimliğinizi doğrular.

Twilio: Aynı hesap hem sms_send hem call_make için kullanılır. Sesli arama en yüksek riskli kanaldır ve her zaman onaya düşer.

WhatsApp: iki yol, çok farklı sonuçlar

Resmi (Cloud API): Meta Business doğrulaması, bir WhatsApp numarası ve iş-başlatımlı mesajlar için onaylı şablon gerekir. Doğrulama haftalar sürebilir — başvuruyu erken başlatın. 24 saat kuralı: müşteri size yazdıysa serbest metin gönderebilirsiniz; konuşmayı siz başlatıyorsanız onaylı şablon zorunludur.

QR oturum: Telefonunuzda WhatsApp → Ayarlar → Bağlı Cihazlar → Cihaz Bağla ile QR'ı okutursunuz. QR yaklaşık 20 saniyede bir yenilenir ve okutunca otomatik bağlanır.

Google

• Google Drive nasıl bağlanır? OAuth access token'ınızı veya service-account JSON'ınızı yapıştırın. drive_read açılır.
• Google Drive Yükleme (drive.file) nasıl bağlanır? Kendi Google Cloud projenizde bir OAuth client oluşturun (BYOC), Client ID + Client Secret'i kaydedin, sonra hesabın satırındaki "Google ile Bağlan (bu hesap için)" düğmesine basıp drive.file iznini onaylayın — refresh token üretilip o hesaba yazılır, elle üretmeniz gerekmez (alan opsiyoneldir). drive_upload açılır — mail eklerini ve ajanın ürettiği dosyayı Drive'a koymak bu bağlantıyı gerektirir.
• Google Calendar nasıl bağlanır? OAuth access token veya service-account JSON girin. calendar_list_events ve calendar_create_event açılır.
• Google Calendar (Kendi OAuth) nasıl bağlanır? Kendi Google Cloud projenizde bir OAuth client oluşturup Client ID, Client Secret ve calendar.events kapsamlı refresh token girin. Davet gönderen etkinlikler bununla oluşturulur.
• Gmail (IMAP + SMTP) nasıl bağlanır? Gmail adresinizi ve 16 haneli uygulama şifrenizi girin. gmail_search, gmail_read, gmail_delete, gmail_forward ve email_send açılır.
• Gmail (Kendi OAuth) nasıl bağlanır? Client ID, Client Secret ve gmail.modify kapsamlı refresh token girin.
• Gmail (Merkezi OAuth) nasıl bağlanır? Bağlanamaz — bu kart "Yakında" durumundadır.

Neden merkezi "Google ile bağlan" yok? Gmail okuma, Google'ın restricted scope sınıfındadır; platformun her yıl ücretli bir CASA güvenlik denetiminden geçmesi gerekir. Bu tamamlanana kadar iki çalışan alternatif var: IMAP (uygulama şifresi) veya kendi OAuth uygulamanız. E-posta gönderme zaten SMTP ile çalışır.

Google Calendar kartında ayrıca bir varsayılan takvim (calendar_id) alanı vardır. Ajan "takvimimde ne var" dediğinizde bu takvimi kullanır. Kişisel Gmail'de: service-account ile paylaştığınız kendi takvim e-postanız. Boş bırakırsanız service-account'un kendi boş takvimi kullanılır.

Verimlilik

Notion nasıl bağlanır? Notion'da bir internal integration oluşturup token'ı girin, ardından ilgili sayfaları o integration ile paylaşın — paylaşılmayan sayfalar API'ye görünmez.

Kimlik bilgilerini nereden alırsınız? (adım adım)

Her connector'ın istediği token / anahtar, ilgili servisin kendi panelinden alınır. Aşağıda gerçek bağlanabilir connector'lar için kaynak adımları var.

Shopify (Admin API) — Client ID + Secret

1. Shopify Dev Dashboard'a girin → Create app ile bir uygulama oluşturun (mağazanızla aynı Shopify organizasyonunda).
2. Uygulamanın Settings / Client credentials bölümünden Client ID ve Client secret'ı kopyalayın.
3. SemAgent'ta Shopify (Admin API) kartına mağaza domaini + Client ID + Client Secret girin. Sistem kısa-ömürlü token'ı otomatik alır (Client Credentials Grant); kendi mağazanız için App Store onayı gerekmez.

Not: Müşteri widget'ının canlı veri okuması için ayrı bir bağlantı vardır (OAuth veya Client Credentials) — bkz. Shopify & e-ticaret.

Printify — API token

1. printify.com'da oturum açın → My Profile → Connections.
2. Generate ile bir Personal Access Token oluşturup kopyalayın.
3. SemAgent'ta Printify kartına yapıştırın. Geliştirici dokümanı: developers.printify.com.

Etsy — API keystring

1. Etsy Developers → Create a New App ile bir uygulama oluşturun.
2. Uygulama sayfasından Keystring'i kopyalayın (okuma için bu yeterlidir; mağaza adına yazma ayrıca OAuth2 ister).
3. SemAgent'ta Etsy kartına girin.

Notion — Internal Integration Token

1. notion.so/my-integrations → New integration.
2. Internal Integration Token'ı kopyalayın (secret_… / ntn_…).
3. Erişmesini istediğiniz sayfaları Notion'da ••• → Connections ile entegrasyona paylaşın; sonra token'ı SemAgent'a girin.

SMS/Ses (Twilio) — Account SID + Auth Token + numara

1. Twilio Console'a girin → ana panelde Account SID ve Auth Token görünür (Auth Token'ı "Show" ile açın).
2. Phone Numbers → Buy a number ile SMS/ses yetenekli bir numara satın alın — bu, "gönderen numara"nızdır.
3. Üçünü SemAgent'taki SMS (Twilio) kartına girin. Doküman: twilio.com/docs/sms.

SMS (NetGSM) — kullanıcı kodu + şifre + başlık

1. NetGSM hesabınıza girin. Kullanıcı kodu (abone numaranız) ve API şifreniz panelde/hesap ayarlarında yer alır (gerekirse ayrı bir API şifresi tanımlayın).
2. Göndereceğiniz mesaj başlığının (ör. FIRMAADI) NetGSM'de onaylı olduğundan emin olun — onaysız başlıkla SMS gitmez.
3. Üçünü SemAgent'taki SMS (NetGSM) kartına girin. Doküman: netgsm.com.tr/dokuman.

WhatsApp Business (Resmi) — Phone Number ID + token

1. Meta for Developers'da bir uygulama oluşturun → WhatsApp ürününü ekleyin.
2. API Setup ekranında numerik Phone Number ID'yi kopyalayın.
3. Kalıcı erişim için bir System User oluşturup whatsapp_business_messaging izinli kalıcı token üretin (geçici token 24 saatte biter).
4. Meta Business doğrulaması + (iş-başlatımlı mesajlar için) onaylı şablon gerekir — haftalar sürebilir, erken başlayın. Rehber: Cloud API get started.

Google (Drive/Takvim/Gmail — kendi OAuth'unuz) — refresh token

1. Google Cloud Console → ilgili API'yi (Gmail / Google Calendar / Drive) Enable edin.
2. Credentials → Create credentials → OAuth client ID ile bir OAuth 2.0 istemcisi oluşturun; Client ID + Secret'ı not edin.
3. OAuth Playground → dişli → "Use your own OAuth credentials" → Client ID/Secret girin → ihtiyaç duyduğunuz kapsamı seçin (gmail.modify / calendar.events / drive.readonly) → Authorize → Exchange authorization code for tokens → dönen refresh token'ı kopyalayın.
4. Drive Yükleme'de bu adım gerekmez: Client ID + Secret'i kaydedip hesap satırındaki "Google ile Bağlan (bu hesap için)" düğmesine basmanız yeter; drive.file kapsamlı token otomatik üretilir.
5. Client ID + Secret + refresh token'ı SemAgent'taki ilgili karta girin. "Testing" modunda CASA gerekmez (100 kullanıcı / 7 gün token sınırı).

Gmail (IMAP) — uygulama şifresi

1. Google Hesabı → Güvenlik → 2 Adımlı Doğrulama'yı açın (zorunlu).
2. Aynı bölümde Uygulama şifreleri → yeni bir tane oluşturun → 16 haneli şifreyi kopyalayın.
3. SemAgent'taki Gmail (IMAP + SMTP) kartına Gmail adresiniz + bu 16 haneli şifreyle girin (normal hesap şifreniz çalışmaz).

"Yakında" işaretli connector'lar

Katalogda bazı kartlar Yakında rozeti taşır. Bunlar oto-bağlanmaz: Bağla düğmesi yerine bir açıklama görürsünüz. Kart görünüyor olması, bağlanabildiği anlamına gelmez.

Somut olarak: Slack bağlanamaz, Meta Ads bağlanamaz, Google Ads bağlanamaz, Microsoft 365 bağlanamaz, Canva bağlanamaz, Stripe bağlanamaz. Hepsi "Yakında" durumundadır.

"Yakında" işaretli servislerin tam listesi (hiçbiri oto-bağlanmaz): Gmail (Merkezi OAuth), Canva, Higgsfield, Meta (Facebook/Instagram), Meta Ads, Google Ads, Microsoft 365, Slack, Stripe, Cloudflare, Klaviyo, Hugging Face, Twilio (jenerik kart), Booking.com, Turkish Airlines, Kiwi.com, Uber, Trivago, GoDaddy, Mercury, PDF Viewer, Control Chrome, Apify, Blender, Autodesk Fusion, ElevenLabs. Bunların ilk altısı Öne çıkanlar, geri kalanı Daha fazlası sekmesinde listelenir.

Yine de kullanabilir misiniz? Evet — onay vererek

"Yakında" bir servisi bugün şöyle kullanabilirsiniz:

1. Servisin API anahtarını Ajan Kasası'na ekleyin (ör. slack_token).
2. Ajana ne yapmasını istediğinizi söyleyin. Ajan genel amaçlı http_request aracıyla servisi çağırır ve sırra ismiyle atıf yapar.
3. Hedef alan adı egress listenizde olmadığı için istek engellenmez, onaya düşer. Onay kartını görüp Onayla dediğinizde çalışır.

Egress allow-list: alan adı izinleri

Ajanın çıkabileceği alan adları tenant başına bir egress listesinde tutulur. Liste iki yolla dolar:

• Katalogdan bir connector bağladığınızda — servisin alan adı otomatik eklenir (katalog önceden doğrulanmıştır).
• WoopSocial sosyal connector'ını kaydettiğinizde — api.woopsocial.com otomatik eklenir.

Bunun dışında elle alan adı ekleyen bir tenant ekranı yoktur; ek alan adları platform yöneticisi tarafından tanımlanır.

Listede olmayan bir hedefe iki farklı davranış vardır — karıştırmayın:

Bağlantıyı kaldırma

Kaldırma davranışı tipe göre değişir — özellikle sırlar açısından:

• smtp ve fields → alan sırları Kasa'dan silinir.
• mcp → MCP sunucu kaydı düşer.
• rest ve oauth_google → alan adı egress listesinden çıkar, ancak token Kasa'da kalır. İsterseniz Kasa'dan elle silin.