Quickstart dla Agentów

Ten Quickstart połączy Twojego zewnętrznego Agenta z systemem operacyjnym webRichtung obsługującym agentów: zarejestrujesz go, zbootstrapujesz organizację, zlegitimujesz Ownera, poczekasz na aktywację przez operatora i wykonasz pierwszą Capability. Dostęp do Gateway jest w wersji Beta.

Po tym przejdź do Referencji Endpointów i Rozwiązywania Problemów w celu poznania reguł walidacji pól, pełnych treści Body oraz ścieżek odzyskiwania.

Odczytaj Discovery.

Adres bazowy Gateway to:
```
https://connect.webrichtung.de
```
Najpierw sprawdź, czy Gateway odpowiada, a następnie odczytaj publiczne zasoby Discovery:
```
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
```
Do rzeczywistej pracy wykorzystasz później narzędzia Meta search_capabilities, describe, dry_run i invoke.

Zarejestruj Agent App.

POST /register tworzy Agent App i zwraca Bootstrap-Key. E-mail Ownera stanowi punkt odpowiedzialności człowieka i musi pozostać identyczny w następnym kroku.

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"
  }
}

Dla każdej mutacji użyj Idempotency-Key zgodnie z regułą Idempotency.

Zbootstrapuj organizację.

POST /organizations używa Bootstrap-Key i zwraca Installation-Key do dalszej ścieżki początkowej. Jednocześnie wysyłany jest kod dla Ownera; jeśli ustawiony jest agent_email, dodatkowo otrzymujesz kod Agent-Mail.
```
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"
  }
}
```
Zasada: Bootstrap-Key działa tylko do /organizations. Następnie Installation-Key z tej odpowiedzi staje się Twoim kluczem roboczym.
Zrealizuj wymagane OTP.

Właściciel-człowiek weryfikuje operację i przekazuje kod Ownera świadomie tylko dla tego onboardingu. Agent przekazuje go wraz z Installation-Key:
```
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>"
}
```
Jeśli ustawiony jest agent_email, zweryfikuj dodatkowo skrzynkę pocztową Agenta. Wyszukaj w tej skrzynce fragment tematu Ref: <correlation_id> z odpowiedzi bootstrap i odczytaj kod z osobnej linii Code: <OTP>.
```
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>"
}
```
Kod Ownera i kod Agent-Mail mogą być realizowane w dowolnej kolejności. Najprostsza kolejność to: zakończ wszystkie wymagane OTP, a następnie sprawdzaj aktywację.
Poczekaj na aktywację.

Po Owner-Claim i opcjonalnej weryfikacji Agent-Mail, webRichtung weryfikuje operację. Praca operacyjna rozpoczyna się dopiero, gdy installation.operator_approval_status ma wartość approved.
```
GET https://connect.webrichtung.de/org/current
Authorization: Bearer <installation-api-key>
```
Reguła pollingu: pierwsze sprawdzenie po 30 sekundach, następnie maksymalnie raz na 60 sekund, maksymalnie 15 minut. Jeśli status pozostaje pending, zatrzymaj flow Agenta i przekaż człowiekowi.

HTTP 412 precondition_failed z /org/current przed pomyślnym Owner-Claim lub przed wymaganą weryfikacją Agent-Mail jest oczekiwanym zachowaniem. Dokładna reakcja znajduje się w Taksonomii Błędów.

Wykonaj pierwszą płatną Capability.

Po approved następuje pierwsza płatna akcja. Ten przykład wykorzystuje documents.document.upload: najpierw odczytaj Contract, następnie wygeneruj oszacowanie kosztów, sprawdź Budget-Guard i dopiero potem wykonaj z Idempotency-Key.

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

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

Przygotuj parametry wyłącznie z describe.input_schema. Dla przykładu wystarczy mały plik tekstowy:

{
  "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 ma obecnie describe.dry_run: "supported", a nie "required". W tym przepływie wykonujesz dry_run mimo to, ponieważ Budget-Guard potrzebuje estimated_cost.amount_max jako liczby w Credits.

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"
  }
}

Kontynuuj tylko wtedy, gdy normalna otoczka Invoke zawiera status: "succeeded" i result.allowed: true.

{
  "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"
}

Udane przesłanie ma status: "succeeded" w otoczce Invoke. Wynik Capability znajduje się w result; dokładna forma Output pozostaje zgodna z contractem describe.output_schema.

Dalej

Otwórz Referencję Endpointów