Guide de démarrage rapide pour les agents

Ce guide vous aide à connecter votre agent externe à webRichtung : enregistrer l’agent, initialiser l’organisation, obtenir l’autorisation du propriétaire, attendre l’activation par l’opérateur et exécuter une première capacité. L’accès à la passerelle est en bêta.

Pour les règles des champs, les corps de requête complets et les procédures de reprise, consultez ensuite la Référence des endpoints et le Dépannage.

Consultez les ressources de découverte.

L’adresse de base de la passerelle est :
```
https://connect.webrichtung.de
```
Vérifiez d’abord que la passerelle répond, puis lisez les ressources publiques de découverte :
```
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
```
Pour le travail réel, vous utiliserez ensuite les méta-outils search_capabilities, describe, dry_run et invoke.

Enregistrez l’Agent App.

POST /register crée l’Agent App et renvoie une clé de bootstrap. L’e-mail Owner identifie la personne responsable et doit rester identique à l’étape suivante.

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

Utilisez une clé d’idempotence pour chaque mutation, selon la Règle d’idempotence.

Initialisez l’organisation.

POST /organizations utilise la clé de bootstrap et fournit la clé d’installation pour la suite du parcours initial. Cet appel déclenche aussi l’envoi du code Owner. Si agent_email est renseigné, un code e-mail est également envoyé à l’agent.
```
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"
  }
}
```
La clé de bootstrap sert jusqu’à /organizations. Ensuite, la clé d’installation fournie dans cette réponse devient votre clé de travail.
Validez les OTP requis.

Le propriétaire humain examine la demande et transmet le code Owner uniquement en connaissance de cause pour cette inscription. L’agent le soumet avec la clé d’installation :
```
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>"
}
```
Si agent_email est renseigné, vérifiez également la boîte e-mail de l’agent. Recherchez dans cette boîte l’objet contenant Ref: <correlation_id>, à partir de la réponse de bootstrap, et lisez le code dans la ligne distincte 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>"
}
```
Les codes Owner et e-mail de l’agent peuvent être validés dans n’importe quel ordre. Le plus simple est de terminer tous les OTP requis, puis d’interroger le statut d’activation.
Attendez l’activation.

Après la validation Owner et la vérification e-mail facultative de l’agent, webRichtung examine la demande. Le travail opérationnel commence uniquement lorsque installation.operator_approval_status vaut approved.
```
GET https://connect.webrichtung.de/org/current
Authorization: Bearer <installation-api-key>
```
Interrogez le statut une première fois après 30 secondes, puis au maximum une fois toutes les 60 secondes, pendant 15 minutes au maximum. Si le statut reste à pending, arrêtez le parcours de l’agent et passez le relais à une personne.

La réponse HTTP 412 precondition_failed de /org/current est attendue avant la validation Owner ou la vérification e-mail requise de l’agent. La réaction exacte est décrite dans Catégories d’erreurs.

Exécutez la première capacité payante.

Une fois le statut approved obtenu, vous pouvez effectuer la première action payante. Cet exemple utilise documents.document.upload : lire le contrat, estimer les coûts, vérifier le budget, puis exécuter avec une clé d’idempotence.

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

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

Préparez les paramètres exclusivement à partir de describe.input_schema. Un petit fichier texte suffit pour cet exemple :

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

Actuellement, documents.document.upload indique describe.dry_run: "supported" et non "required". Dans ce parcours, vous effectuez tout de même dry_run, car le contrôle budgétaire a besoin de estimated_cost.amount_max sous forme de nombre en 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"
  }
}

Continuez uniquement si l’enveloppe habituelle d’Invoke contient status: "succeeded" et 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"
}

Un import réussi indique status: "succeeded" dans l’enveloppe d’Invoke. Le résultat de la capacité se trouve sous result. Sa forme exacte est définie par le contrat describe.output_schema.

Pour continuer

Ouvrir la référence des endpoints