Ajanın kendi kendine kaydı: Yapay zekâ ajanı tek çağrıyla Shager test ortamını nasıl açar, yayın düğmesi neden hâlâ insanda?

Bir ajan tek bir POST ile kendi Shager test ortamını açabilir. Çağrı, test ortamında neler yapılabildiği, insanın sahiplenmesi ve yayın izninin verilmesi.

Yazar: Yaniv PreslerShager'in kurucusuAjanınızı bağlayın12 Eylül 20267 dk okuma

Bir yapay zekâ ajanı Shager'a tek bir istekle kendi kendine kaydolabilir: en azından agent_name içeren bir JSON gövdesiyle POST https://app.shager.ai/api/v1/agent/signup. Karşılığında bir API anahtarı, bir MCP URL'si ve bir sahiplenme linki alır; hemen çalışma alanları oluşturabilir, medya içe aktarabilir ve gönderi taslakları hazırlayabilir. Bir insan sahiplenme linkini açıp giriş yapana ve o anahtarın yayın yapıp yapamayacağına karar verene kadar hiçbir şey planlanmaz ya da yayınlanmaz.

Tasarımın tamamı bu ayrımdan ibaret. Ajan bir insanı beklemeden işine devam eder; gerçek kitlelere dokunan karar ise insanda kalır.

Bir ajanın kendi kendine kaydolmasına neden izin verelim?

Çünkü alternatif, ajanın akışını bozar. "Müşterimizin sosyal medya dağıtımını kur" denen bir ajan, içeri girmenin tek yolu bir insanın kayıt formu doldurması, e-postasını doğrulaması ve panelde bir anahtar oluşturmasıysa daha ilk adımda duvara çarpar. Biri bunu yapana kadar ajanın bağlamı çoktan kaybolmuştur.

Kendi kendine kayıtla ajan hazırlık işini tek başına yapar: her müşteri için bir çalışma alanı oluşturur, medyayı çeker, gönderi taslaklarını yazar ve insana, incelenmeye hazır her şeyi içeren tek bir link verir. Kayıt tarifi ajanlar için /auth.md adresinde yayımlanmıştır; ajanlar sayfası da bir ajanın başlamadan önce okuyabileceği keşif dosyalarını listeler.

Diyagram: Ajan tek bir çağrıyla kaydolur ve yalnızca taslaklara izin veren bir deneme ortamı alır; bir kişi sahiplenme linkini açıp sahipliği üstlenir, ardından yayın yetkisi ayrıca verilir. Gönderi başına onay her müşteri için isteğe bağlıdır. — Ajan taslaklarla başlar. Bir insan sahipliği üstlenir ve anahtara yayın yetkisini ayrıca verir.

Kayıt çağrısı nasıl görünür?

Yalnızca agent_name zorunludur (2 ila 80 karakter). Diğer alanlar, insanın neyi sahiplendiğini tanımasına yardımcı olur.

curl -s https://app.shager.ai/api/v1/agent/signup \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Northwind content agent",
    "contact_email": "ops@northwind-agency.example",
    "organization_name": "Northwind Agency",
    "purpose": "Draft weekly posts for 12 restaurant clients"
  }'

Yanıt her şeyi data içinde döndürür:

{
  "data": {
    "api_key": "shgr_live_...",
    "organization_id": "...",
    "sandbox": true,
    "claim_url": "https://app.shager.ai/...",
    "expires_at": "2026-09-19T10:04:11.000Z",
    "mcp_url": "https://app.shager.ai/api/mcp",
    "api_base": "https://app.shager.ai/api/v1",
    "openapi_url": "https://app.shager.ai/api/v1/openapi.json",
    "limits": { "workspaces": 5, "requests_per_minute": 120, "publishing": "after a human claims the sandbox" },
    "next_steps": ["..."]
  }
}

İki alanla hemen ilgilenmek gerekir.

api_key yalnızca bir kez gösterilir. Başka bir şey yapmadan önce onu bir sır deposunda ya da ortam değişkeninde saklayın; asla bir log satırına yazmayın.
claim_url bir insana gider. contact_email verdiyseniz Shager sahiplenme linkini oraya da e-postayla gönderir, ama ajan yine de linki kendi yanıtında göstermelidir.

Kayıtlar adres başına saatte beşle sınırlıdır; bu da döngüye giren bir ajanın onlarca sahipsiz test ortamı açmasını önler.

Sahiplenilmemiş bir test ortamı neler yapabilir?

Sahiplenmeden önce izin verilenler	Bir insan sahiplenene kadar engellenenler
En fazla 5 çalışma alanı oluşturmak	Herhangi bir şeyi planlamak ya da yayınlamak
URL'lerden medya yüklemek	Müşteri bağlantı linkleri oluşturmak
Gönderi taslakları oluşturmak	Müşteri onay istekleri göndermek
Oluşturduğu her şeyi listelemek ve okumak

Engellenen çağrılar sessizce hiçbir şey yapmamak yerine açık bir hatayla başarısız olur. Planlama denemesi "code": "sandbox_unclaimed" ile HTTP 403 döndürür; create_connect_link ve request_approval da öyle. Altıncı bir çalışma alanı 403 sandbox_limit döndürür. İyi ajanlar yeniden denemek yerine code değerini okur ve insana neyin gerektiğini söyler.

Bağlantı linklerinin ve onay isteklerinin engellenmesinin nedeni, ikisinin de ajansın dışındaki gerçek insanlara ulaşmasıdır: Facebook Sayfasını bağlamak için linke tıklayan bir müşteri ya da onay e-postası alan bir onaylayan. Bu, kimsenin doğrulamadığı bir kuruluş adına gerçekleşmemeli.

Test ortamında makul bir ilk oturum

Düzgün davranan bir ajanın ilk dakikalarında yaptıkları, Python ve requests ile:

import os, requests

API = "https://app.shager.ai/api/v1"
H = {"Authorization": f"Bearer {os.environ['SHAGER_API_KEY']}"}

def call(method, path, **body):
    r = requests.request(method, f"{API}{path}", headers=H, json=body or None, timeout=60)
    payload = r.json()
    if not r.ok:
        err = payload["error"]
        raise RuntimeError(f"{r.status_code} {err['code']}: {err['message']}")
    return payload["data"]

me = call("GET", "/me")
print(me)  # organization, scopes, sandbox status

ws = call("POST", "/workspaces", name="Harbor Tacos", timezone="America/Chicago")

media = call("POST", f"/workspaces/{ws['id']}/media",
             url="https://harbortacos.example/press/fall-menu.jpg",
             file_name="fall-menu.jpg")

print("Workspace", ws["id"], "media", media["id"], media["kind"])

Bir çalışma alanı oluştururken timezone değerini açıkça verin. Bu bir IANA saat dilimi adıdır ve sonraki planlamalar bu dilime göre yorumlanır; Chicago'daki bir restoran başkasının varsayılanını devralmamalı.

Bu noktada henüz bağlı sosyal hesap yoktur, çünkü hesap bağlamak bir bağlantı linki gerektirir, bağlantı linki de sahiplenmeyi. Ajan içeriği ve yapıyı hazırlar; geri kalanının kapısını insan açar.

Diyagram: Bir ajan anahtarı için üç yetki düzeyi (read, write ve publish); her işlem denetim günlüğüne kaydedilir. — Ajana yalnızca ihtiyacı olanı verin ve yaptığı her şeyi görün.

İnsan sahiplendiğinde ne olur?

İnsan claim_url linkini açar, Shager'a giriş yapar (ya da hesap oluşturur) ve test ortamını, ajanın hazırladığı çalışma alanları, medya ve taslaklarla birlikte sahiplenir. Sahiplenme sırasında ajanın anahtarının planlama ve yayın da yapıp yapamayacağını seçer; bu seçim publish yetkisini ekler.

Bu seçim biraz düşünmeyi hak ediyor. publish yetkisini kapalı bırakmak uzun vadede gayet iyi bir kurulumdur: ajan taslak hazırlar, insan ya da müşteri onaylar ve planlar. Birçok ajans buradan başlar ve sonra https://app.shager.ai/dashboard/agents adresinde ayrı bir yayın anahtarı ekler; orada her anahtar iptal edilebilir ve ajanın her çağrısı denetim kaydında görünür. Bu kurulumlar arasındaki ödünleşimleri haftalık dağıtım rutini yazısında ele alıyoruz.

Sahiplenmeden sonra API'nin kendisinin önerdiği sonraki adımlar basittir: hesap sahibinin sosyal hesaplarını (Facebook, Instagram, YouTube, X, LinkedIn veya TikTok) Shager girişi olmadan bağlaması için create_connect_link, ardından create_post ve anahtarda publish varsa schedule_post.

Kimse sahiplenmezse ne olur?

Sahiplenilmemiş test ortamlarının süresi yedi gün sonra, expires_at alanında verilen saatte dolar. Taslaklar ve çalışma alanları da onlarla birlikte gider. Daha uzun bir proje üzerinde çalışan bir ajan, bu tarihten önce insana hatırlatmalı ve süre dolduğunda tekrar tekrar kaydolmamalıdır. Yeni bir test ortamı eski taslakları taşımaz.

Ajan devri nasıl ifade etmeli?

Açıkça, linkle ve sonuçlarıyla birlikte. Örneğin:

I set up a Shager sandbox for Northwind with 3 client workspaces and
9 draft posts. To connect the clients' accounts and publish, open this
link and sign in: <claim_url>
When you claim it you can choose whether I'm allowed to schedule posts
myself. If you don't claim it by Sep 19, the sandbox and drafts are deleted.

Bu mesaj neyin yapıldığı, neyin beklediği ve insanın neyi kontrol ettiği konusunda dürüsttür. Aynı zamanda tıklanma olasılığı en yüksek mesajdır.

SSS

Kendi kendine kayıt ücretli mi?

Hayır. Test ortamı ücretsizdir ve lansman döneminde Shager sahiplenmeden sonra da ücretsizdir, kart gerekmez; ücretlendirmeye başlamadan önce sizi önceden bilgilendireceğiz. API ve MCP erişimi her plana dahildir. Plan sınırları fiyatlandırma sayfasında.

Ajan kaydolduktan sonra REST yerine MCP kullanabilir mi?

Evet. Yanıt mcp_url içerir ve aynı anahtar MCP sunucusunda Authorization: Bearer shgr_live_... olarak çalışır. Araçlar, OpenAPI belgesinde tanımlanan REST işlemleriyle birebir eşleşir.

Sahiplenilmiş bir anahtar, bir insan gönderiyi görmeden yayın yapabilir mi?

Yalnızca insan sahiplenme sırasında publish yetkisini verdiyse ve çalışma alanı müşteri onayı gerektirmiyorsa. İkisi de insanın tercihidir ve ikisi de sonradan değiştirilebilir: anahtarlar panelden iptal edilebilir, onay da her çalışma alanı için ayrı ayrı zorunlu hale getirilebilir.

Sonraki adım

Test ortamı sahiplenildikten ve hesaplar bağlandıktan sonra keşiften tam bir çalıştırmaya geçin. Uçtan uca ajan içerik hattı, tam olarak burada bıraktığımız yerden devam ediyor: briften yayınlanmış gönderilere ve hesap bazındaki tıklamalara kadar.