Quickstart für Agents

Dieser Quickstart führt einen externen Agent durch den ersten erfolgreichen Weg: registrieren, Organisation bootstrappen, Owner legitimieren, Freischaltung abwarten und eine erste Capability ausführen.

Für Feldregeln, vollständige Bodies und Recovery-Pfade nutze danach die Endpunkt-Referenz und die Fehlerbehebung.

Lies Discovery.

Die Gateway-Basisadresse ist:
```
https://connect.webrichtung.de
```
Prüfe zuerst, dass der Gateway antwortet, und lies danach die öffentlichen Discovery-Ressourcen:
```
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
```
Für echte Arbeit nutzt du später die Meta-Tools search_capabilities, describe, dry_run und invoke.

Registriere die Agent App.

POST /register legt die Agent App an und gibt einen Bootstrap-Key zurück. Die Owner-E-Mail ist der Verantwortungsanker des Menschen und muss im nächsten Schritt identisch bleiben.

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

Nutze für jede Mutation eine Idempotency-Key nach der Idempotency-Regel.

Bootstrappe die Organisation.

POST /organizations verwendet den Bootstrap-Key und liefert den Installation-Key für den weiteren Erstpfad. Gleichzeitig wird der Owner-Code ausgelöst; wenn agent_email gesetzt ist, kommt zusätzlich ein Agent-Mail-Code.
```
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"
  }
}
```
Merksatz: Der Bootstrap-Key reicht nur bis /organizations. Danach ist der Installation-Key aus dieser Antwort dein Arbeits-Key.
Löse die erforderlichen OTPs ein.

Der menschliche Owner prüft den Vorgang und gibt den Owner-Code nur bewusst für dieses Onboarding weiter. Der Agent reicht ihn mit dem Installation-Key ein:
```
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>"
}
```
Wenn agent_email gesetzt ist, verifiziere zusätzlich die Agent-Mailbox. Suche in dieser Mailbox nach dem Betreffbestandteil Ref: <correlation_id> aus der Bootstrap-Antwort und lies den Code aus der eigenständigen Zeile 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>"
}
```
Owner-Code und Agent-Mail-Code dürfen in beliebiger Reihenfolge eingelöst werden. Die einfachste Reihenfolge ist: alle erforderlichen OTPs abschließen, dann Freischaltung pollen.
Warte auf die Freischaltung.

Nach Owner-Claim und optionaler Agent-Mail-Verifikation prüft webRichtung den Vorgang. Operative Arbeit startet erst, wenn installation.operator_approval_status den Wert approved hat.
```
GET https://connect.webrichtung.de/org/current
Authorization: Bearer <installation-api-key>
```
Polling-Regel: erster Poll nach 30 Sekunden, danach höchstens einmal pro 60 Sekunden, maximal 15 Minuten. Bleibt der Status pending, stoppe den Agent-Flow und übergib an einen Menschen.

HTTP 412 precondition_failed von /org/current vor erfolgreichem Owner-Claim oder vor erforderlicher Agent-Mail-Verifikation ist erwartetes Verhalten. Die genaue Reaktion steht in der Fehlertaxonomie.

Führe die erste bezahlte Capability aus.

Nach approved folgt die erste bezahlte Aktion. Dieses Beispiel nutzt documents.document.upload: erst Contract lesen, dann Kostenschätzung erzeugen, Budget-Guard prüfen und erst danach mit Idempotency-Key ausführen.

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

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

Bereite die Parameter ausschließlich aus describe.input_schema vor. Für das Beispiel reicht eine kleine Textdatei:

{
  "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 hat aktuell describe.dry_run: "supported", nicht "required". In diesem Ablauf führst du dry_run trotzdem aus, weil der Budget-Guard estimated_cost.amount_max als Zahl in Credits braucht.

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

Fahre nur fort, wenn die normale Invoke-Hülle status: "succeeded" und result.allowed: true enthält.

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

Ein erfolgreicher Upload hat status: "succeeded" in der Invoke-Hülle. Das Capability-Ergebnis liegt unter result; die genaue Output-Form bleibt der describe.output_schema-Contract.

Weiter

Endpunkt-Referenz öffnen