Agent'lar için Hızlı Başlangıç

Bu hızlı başlangıçla harici Agent’ınızı agent özellikli işletim sistemi webRichtung’a bağlarsınız: Onu kaydettirir, organizasyonu bootstrap eder, Owner’ı doğrular, operatör onayını bekler ve ilk Capability’yi çalıştırırsınız. Gateway erişimi Beta aşamasındadır.

Alan kuralları, eksiksiz Body’ler ve kurtarma yolları için Endpoint Referansı ve Sorun Giderme bölümlerini kullanın.

Discovery’yi okuyun.

Gateway temel adresi:
```
https://connect.webrichtung.de
```
Önce Gateway’in yanıt verdiğini kontrol edin, sonra genel Discovery kaynaklarını okuyun:
```
GET https://connect.webrichtung.de/health
GET https://connect.webrichtung.de/llms.txt
GET https://connect.webrichtung.de/mcp/manifest
GET https://connect.webrichtung.de/capabilities
```
Gerçek işler için daha sonra search_capabilities, describe, dry_run ve invoke meta araçlarını kullanacaksınız.

Agent App’i kaydedin.

POST /register Agent App’i oluşturur ve bir Bootstrap Key döndürür. Owner e-postası insanın sorumluluk bağlantı noktasıdır ve bir sonraki adımda aynı kalmalıdır.

POST https://connect.webrichtung.de/register
Content-Type: application/json
Idempotency-Key: idem-register-20260704-0001

{
  "owner_email": "owner@example.com",
  "agent_email": "agent@example.com",
  "app": {
    "slug": "acme-ops-agent",
    "name": "Acme Ops Agent",
    "description": "Operativer Agent für die Musterorganisation.",
    "contact_email": "ops@example.com",
    "homepage_url": "https://example.com/agent"
  }
}

Her mutasyon için Idempotency kuralına göre bir Idempotency-Key kullanın.

Organizasyonu bootstrap edin.

POST /organizations Bootstrap Key’i kullanır ve devam eden ilk yol için Installation Key’i sağlar. Aynı zamanda Owner kodu tetiklenir; agent_email ayarlanmışsa ek olarak bir Agent mail kodu gelir.
```
POST https://connect.webrichtung.de/organizations
Content-Type: application/json
Authorization: Bearer <bootstrap-api-key>
Idempotency-Key: idem-bootstrap-20260704-0001
```
```
{
  "owner_email": "owner@example.com",
  "agent_email": "agent@example.com",
  "organization": {
    "name": "Musterfirma GmbH"
  }
}
```
Hatırlatma: Bootstrap Key yalnızca /organizations’a kadar geçerlidir. Bundan sonra bu yanıttaki Installation Key çalışma Key’iniz olur.
Gerekli OTP’leri kullanın.

İnsan Owner işlemi kontrol eder ve Owner kodunu yalnızca bilinçli olarak bu onboarding için iletir. Agent bunu Installation Key ile kullanır:
```
POST https://connect.webrichtung.de/owner-otp/claim
Content-Type: application/json
Authorization: Bearer <installation-api-key>
Idempotency-Key: idem-owner-claim-20260704-0001
```
```
{
  "otp": "<owner-otp>"
}
```
agent_email ayarlanmışsa ek olarak Agent posta kutusunu doğrulayın. Bu posta kutusunda Bootstrap yanıtındaki Ref: <correlation_id> konu parçasını arayın ve bağımsız Code: <OTP> satırından kodu okuyun.
```
POST https://connect.webrichtung.de/agent-otp/verify
Content-Type: application/json
Authorization: Bearer <installation-api-key>
Idempotency-Key: idem-agent-verify-20260704-0001
```
```
{
  "otp": "<agent-mail-otp>"
}
```
Owner kodu ve Agent mail kodu herhangi bir sırada kullanılabilir. En basit sıra: tüm gerekli OTP’leri tamamlayın, sonra onayı poll edin.
Onayı bekleyin.

Owner claim ve opsiyonel Agent mail doğrulamasından sonra webRichtung işlemi kontrol eder. Operatif çalışma ancak installation.operator_approval_status değeri approved olduğunda başlar.
```
GET https://connect.webrichtung.de/org/current
Authorization: Bearer <installation-api-key>
```
Polling kuralı: ilk poll 30 saniye sonra, sonra en fazla 60 saniyede bir, maksimum 15 dakika. Durum pending kalırsa Agent akışını durdurun ve bir insana devredin.

Başarılı Owner claim öncesinde veya gerekli Agent mail doğrulaması öncesinde 412 precondition_failed’tan gelen HTTP /org/current beklenen davranıştır. Tam tepki Hata Taksonomisi’ndedir.

İlk ücretli Capability’yi çalıştırın.

approved sonrasında ilk ücretli eylem gelir. Bu örnek documents.document.upload kullanır: önce Contract’ı okuyun, sonra maliyet tahmini oluşturun, Budget Guard’ı kontrol edin ve ancak ondan sonra Idempotency-Key ile çalıştırın.

POST https://connect.webrichtung.de/mcp/describe
Content-Type: application/json
Authorization: Bearer <installation-api-key>

{
  "id": "documents.document.upload"
}

Parametreleri yalnızca describe.input_schema’dan hazırlayın. Örnek için küçük bir metin dosyası yeterlidir:

{
  "file_name": "note.txt",
  "mime_type": "text/plain",
  "content_base64": "SGVsbG8gd2VicmljaHR1bmc="
}

POST https://connect.webrichtung.de/mcp/dry_run
Content-Type: application/json
Authorization: Bearer <installation-api-key>

{
  "id": "documents.document.upload",
  "params": {
    "file_name": "note.txt",
    "mime_type": "text/plain",
    "content_base64": "SGVsbG8gd2VicmljaHR1bmc="
  }
}

documents.document.upload şu anda describe.dry_run: "supported"’a sahiptir, "required" değil. Bu akışta yine de dry_run çalıştırırsınız çünkü Budget Guard, estimated_cost.amount_max değerini Credits cinsinden sayı olarak gerektirir.

POST https://connect.webrichtung.de/mcp/invoke
Content-Type: application/json
Authorization: Bearer <installation-api-key>

{
  "id": "wallet.agent_budget.guard.check",
  "params": {
    "capability_id": "documents.document.upload",
    "estimated_cost_credits": 0.09,
    "window": "task"
  }
}

Yalnızca normal Invoke zarfı status: "succeeded" ve result.allowed: true içeriyorsa devam edin.

{
  "interface_version": "1.0",
  "status": "succeeded",
  "capability_id": "wallet.agent_budget.guard.check",
  "resolved_version": "1.0.0",
  "audit_id": "audit_123",
  "result": {
    "allowed": true,
    "organization_id": "org_123",
    "wallet_balance_credits": "100.00",
    "estimated_cost_credits": 0.09
  }
}

POST https://connect.webrichtung.de/mcp/invoke
Content-Type: application/json
Authorization: Bearer <installation-api-key>

{
  "id": "documents.document.upload",
  "params": {
    "file_name": "note.txt",
    "mime_type": "text/plain",
    "content_base64": "SGVsbG8gd2VicmljaHR1bmc="
  },
  "idempotency_key": "idem-doc-upload-20260704-0001"
}

Başarılı bir yükleme Invoke zarfında status: "succeeded" içerir. Capability sonucu result altındadır; tam Output formu describe.output_schema Contract’ına bağlıdır.

Devamı

Endpoint Referansını açın