# Yapay Zeka Destekli Alışveriş Ajanları

> AI alışveriş ajanlarını vitrin API’lerine güvenli bir sunucu araç katmanıyla bağlama: önerilen araçlar, şemalar, güvenlik kuralları ve analytics olayları.
>
> Kaynak: https://tecof-app-dev.vercel.app/agents · Bölüm: AI ve MCP · Son güncelleme: 2018-10-20

Tecof alışveriş ajanları için önerilen yol, mevcut storefront API'lerini güvenli bir server-side tool katmanı arkasından kullanmaktır. Ajan doğrudan browser secret key'i veya customer token'ı taşımamalı; sizin backend'iniz Tecof API ile konuşmalıdır.

---

## Temel Akış

```mermaid
sequenceDiagram
    participant User as Kullanıcı
    participant Agent as AI Ajan
    participant Tools as Tool Backend
    participant Tecof as Tecof Store API

    User->>Agent: "Kırmızı ayakkabı bul"
    Agent->>Tools: search_products(query)
    Tools->>Tecof: GET /api/store/ecommerce/products?search=...
    Tecof-->>Tools: Ürün listesi
    Tools-->>Agent: Normalize ürün sonucu
    Agent->>User: Ürünleri önerir
    User->>Agent: "Sepete ekle"
    Agent->>Tools: validate_cart(items)
    Tools->>Tecof: POST /api/store/ecommerce/cart/validate
    Tools->>Tecof: POST /api/store/ecommerce/checkout-session
    Tools-->>Agent: redirectUrl
    Agent->>User: Checkout bağlantısı verir
```

---

## Önerilen Tool Seti

Bu isimler ajan tarafındaki soyut tool isimleridir; altta çağırmaları gereken gerçek Tecof endpointleri tabloda verilmiştir.

| Tool | Tecof endpoint | Not |
| :--- | :--- | :--- |
| `search_products` | `GET /api/store/ecommerce/products` | `search`, `category`, `brand`, `minPrice`, `maxPrice`, `tag`, `sort` destekler |
| `get_product` | `GET /api/store/ecommerce/products/:slug` | Ürün detayını slug ile getirir |
| `get_categories` | `GET /api/store/ecommerce/categories` | Kategori ağacı |
| `get_search_suggestions` | `GET /api/store/ecommerce/search/suggest` | Autocomplete için |
| `validate_cart` | `POST /api/store/ecommerce/cart/validate` | Stok, fiyat ve otomatik indirimleri doğrular |
| `validate_coupon` | `POST /api/store/ecommerce/coupon/validate` | Kupon/free shipping kontrolü |
| `get_shipping_rates` | `POST /api/store/ecommerce/shipping/rates` | Adrese göre kargo |
| `create_checkout_session` | `POST /api/store/ecommerce/checkout-session` | Hosted checkout redirect URL'i üretir |
| `get_cms_items` | `POST /api/store/cms/collections/:slug/items` | Canlı CMS içeriği |

---

## Tool Şema Örnekleri

### `search_products`

```json
{
  "name": "search_products",
  "description": "Tecof mağazasında aktif ürünleri arar.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "locale": { "type": "string", "default": "tr" },
      "limit": { "type": "number", "default": 5 },
      "category": { "type": "string" },
      "minPrice": { "type": "number" },
      "maxPrice": { "type": "number" }
    },
    "required": ["query"]
  }
}
```

### `create_checkout_session`

```json
{
  "name": "create_checkout_session",
  "description": "Doğrulanmış sepet için hosted checkout oturumu oluşturur.",
  "input_schema": {
    "type": "object",
    "properties": {
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "productId": { "type": "string" },
            "variantId": { "type": "string" },
            "quantity": { "type": "number" }
          },
          "required": ["productId", "quantity"]
        }
      },
      "locale": { "type": "string", "default": "tr" },
      "successUrl": { "type": "string" },
      "failUrl": { "type": "string" }
    },
    "required": ["items"]
  }
}
```

---

## Güvenlik Kuralları

1. `x-secret-key` değerini ajan istemcisine vermeyin; tool backend içinde tutun.
2. Customer token gereken işlemleri sadece kullanıcı oturumu doğrulandıktan sonra yapın.
3. Checkout için mümkünse `checkout-session` üretip kullanıcıyı hosted ödeme akışına yönlendirin.
4. Ajanın ürün fiyatı veya stok bilgisini model hafızasından değil, her istekte `cart/validate` sonucundan okumasını sağlayın.
5. Webhook veya admin işlemlerini AI ajanına doğrudan açmayın; ayrı izin katmanı kullanın.

---

## Analytics Eventleri

Ajan destekli storefront deneyimlerinde checkout davranışı için mevcut analytics event tipleri kullanılabilir:

| Event | Kullanım |
| :--- | :--- |
| `cart_add` | Ajan önerisiyle ürün sepete eklendiğinde |
| `cart_remove` | Sepetten ürün çıkarıldığında |
| `checkout_start` | Hosted checkout veya ödeme adımı başladığında |

Bu eventler `POST /api/analytics/event` üzerinden toplanır ve live analytics ekranında davranış metriklerine katkı verir.

---

## Mağazanın AI dosyaları

Ajanların mağazayı araç çağırmadan da anlayabilmesi için Tecof mağaza kökünde `agents.md`, `llms.txt`, `llms-full.txt` ve `/ai/*.json` (katalog, koleksiyonlar, bilgi merkezi, içerik dizini) yayınlar; ajan kaynaklı ödeme bağlantıları `utm_source=ai_agent` taşır. Dosyaların içeriği, site türüne göre farkları ve tema proxy’si: [GEO: AI Storefront](/ai-storefront).