Inicio rápido para Agents

Con este inicio rápido conectarás tu Agent externo con el sistema operativo preparado para agentes webRichtung: lo registrarás, arrancarás la organización, legitimarás al Owner, esperarás la aprobación del operador y ejecutarás una primera Capability. El acceso al Gateway está en Beta.

Para reglas de campo, bodies completos y rutas de recuperación, utiliza después la Referencia de endpoints y la Solución de problemas.

Lee Discovery.

La dirección base del Gateway es:
```
https://connect.webrichtung.de
```
Primero verifica que el Gateway responda y luego lee los recursos públicos de 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
```
Para trabajo real utilizarás más adelante las Meta-Tools search_capabilities, describe, dry_run e invoke.

Registra la Agent App.

POST /register crea la Agent App y devuelve un Bootstrap-Key. El correo electrónico del Owner es el punto de responsabilidad humana y debe permanecer idéntico en el siguiente paso.

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

Utiliza un Idempotency-Key para cada mutación según la regla de Idempotency.

Arranca la organización.

POST /organizations utiliza el Bootstrap-Key y proporciona el Installation-Key para la ruta de inicio posterior. Al mismo tiempo se envía el código del Owner; si se establece agent_email, se envía adicionalmente un código de correo del 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"
  }
}
```
Regla nemotécnica: el Bootstrap-Key solo alcanza hasta /organizations. Después, el Installation-Key de esta respuesta es tu clave de trabajo.
Canjea los OTPs requeridos.

El Owner humano verifica el proceso y entrega el código del Owner solo conscientemente para este onboarding. El Agent lo presenta con el 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>"
}
```
Si se establece agent_email, verifica adicionalmente el buzón del Agent. Busca en este buzón el componente del asunto Ref: <correlation_id> de la respuesta de arranque y lee el código de la línea independiente 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>"
}
```
El código del Owner y el código de correo del Agent pueden canjearse en cualquier orden. El orden más sencillo es: completar todos los OTPs requeridos, luego hacer polling de la aprobación.
Espera la aprobación.

Después del claim del Owner y la verificación opcional del correo del Agent, webRichtung verifica el proceso. El trabajo operativo solo comienza cuando installation.operator_approval_status tiene el valor approved.
```
GET https://connect.webrichtung.de/org/current
Authorization: Bearer <installation-api-key>
```
Regla de polling: primer poll después de 30 segundos, luego como máximo una vez cada 60 segundos, máximo 15 minutos. Si el estado permanece en pending, detén el flujo del Agent y pásalo a un humano.

HTTP 412 precondition_failed de /org/current antes del claim exitoso del Owner o antes de la verificación requerida del correo del Agent es comportamiento esperado. La reacción exacta está en la Taxonomía de errores.

Ejecuta la primera Capability de pago.

Después de approved sigue la primera acción de pago. Este ejemplo utiliza documents.document.upload: primero lee el Contract, luego genera la estimación de costos, verifica el Budget-Guard y solo después ejecuta con Idempotency-Key.

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

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

Prepara los parámetros exclusivamente desde describe.input_schema. Para el ejemplo es suficiente un archivo de texto pequeño:

{
  "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 tiene actualmente describe.dry_run: "supported", no "required". En este flujo ejecutas dry_run de todos modos porque el Budget-Guard necesita estimated_cost.amount_max como número 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"
  }
}

Continúa solo si la envoltura normal de Invoke contiene status: "succeeded" y 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"
}

Una carga exitosa tiene status: "succeeded" en la envoltura de Invoke. El resultado de la Capability está bajo result; la forma exacta del Output queda sujeta al Contract describe.output_schema.

Continuar

Abrir Referencia de endpoints