Questions pour développeurs

HumanLayer est une API d’orchestration de décisions humaines.

Elle permet à un système (agent IA, backend, workflow engine) de :

• soumettre un dossier de décision
• attendre une validation humaine qualifiée
• recevoir une réponse structurée
• avec un audit trail complet

👉 Pour un développeur, HumanLayer est un service externe appelable, comme Stripe, Twilio ou Auth0 — mais pour la décision humaine.

Quand votre système arrive à un point où :

• une décision engage une responsabilité humaine
• une règle n’est plus suffisante
• une signature ou une validation est requise
• ou quand vous voulez une preuve formelle de validation

Règle simple :

Si vous hésitez à automatiser → appelez HumanLayer.

Oui.

HumanLayer est conçu pour :

• être appelé comme un tool
• fonctionner dans des boucles agentiques
• être utilisé par des LLMs sous contrôle

Exemple mental :

if confidence < threshold or risk == "high":
    r = requests.post(API, headers={"x-api-key": KEY}, json=dossier)
    # puis webhook signé, ou GET /api/v1/decisions?id=…

Asynchrone.

Vous créez une demande (POST /api/v1/decisions) : la réponse est immédiate (request_id, status, sla_minutes, expires_at) et votre workflow continue. La décision vous parvient ensuite par webhook signé ; vous pouvez aussi la consulter via GET /api/v1/decisions?id=…

Pas de mode bloquant : le délai le plus court est de 30 min (niveau conformité).

Le délai de chaque demande est annoncé dès sa création (sla_minutes, expires_at).

Une décision est un objet structuré, avec :

• un type (request_type : compliance, judgment ou signature)
• un niveau (level : 1, 2 ou 3)
• le contexte fourni par l’agent (summary, context_json)
• un statut (pending, assigned, decided, sla_breached) et la dernière décision (verdict : approved, rejected ou escalated)
• la justification du Sentinel (reasoning)
• une signature Ed25519 (signature, signed_payload, key_id) et des horodatages

👉 Ce n’est pas un texte libre. C’est un artefact exploitable par un système.

Uniquement :

• le résumé et le contexte transmis par votre agent : à vous de n’y mettre que le nécessaire
• les éléments préparés par l’IA
• les champs requis pour décider

Pas d’accès global au système, pas de données inutiles.

👉 Minimisation by design.

Pas pour l’instant. Les demandes sont confiées au réseau de Sentinels de HumanLayer, selon le domaine et la juridiction ; réserver des Sentinels à votre organisation n’est pas proposé aujourd’hui.

HumanLayer reste :

• la couche d’orchestration
• la source de vérité
• la preuve d’audit

Au-delà du délai, un webhook signé sla.breached vous est envoyé (une fois) et la demande est réassignée automatiquement à un autre Sentinel qualifié, trois fois au plus. Aucune décision n’est prise par défaut, et rien n’est configurable hormis un délai plus long (sla_minutes).

L’API étant asynchrone, votre code n’attend jamais : c’est à votre agent de décider quoi faire tant qu’aucune décision n’est rendue.

Oui, c’est la règle. Toute décision finale est binaire : approved ou rejected, avec une justification écrite obligatoire (10 caractères au moins), et signée. Le Sentinel peut aussi escalader la demande vers un autre Sentinel. Les décisions conditionnelles, les champs de réponse personnalisés et les seuils ne sont pas proposés : précisez vos critères dans summary ou context_json.

HumanLayer ne laisse pas de décisions ambiguës.

Oui. Envoyez une nouvelle demande avec second_opinion_of (l’identifiant de la demande tranchée) : un autre Sentinel, qui n’a jamais traité le dossier et ne voit pas le premier verdict, rend sa propre décision signée. Un seul second avis par demande, facturé comme une nouvelle décision du même niveau. Le Sentinel assigné peut aussi escalader le dossier de lui-même. La validation multi-signature et le quorum ne sont pas proposés.

Non. Jamais.

HumanLayer :

• ne génère pas de décision
• ne modifie pas la réponse humaine
• ne "corrige" pas le Sentinel

Il orchestre, structure et trace.

• Authentification par clé d’API (en-tête x-api-key), stockée uniquement sous forme d’empreinte SHA-256
• Niveaux de décision autorisés selon le forfait de chaque clé
• Isolation par organisation
• Journaux d’accès
• Chiffrement en transit (HTTPS obligatoire, webhooks compris) ; secrets de double authentification chiffrés (AES-256-GCM) ; clés d’API et mots de passe stockés sous forme d’empreinte

Un Sentinel n’a accès qu’aux dossiers qui lui sont assignés et à ceux qu’il a déjà tranchés ou escaladés.

Vous pouvez extraire :

• un export JSON de vos décisions signées depuis l’espace client (5 000 demandes les plus récentes, dernière décision de chacune)
• les justifications
• les horodatages
• la référence pseudonyme du Sentinel (S-XXXXXX), l’identité réelle restant conservée par HumanLayer

👉 Pas besoin de reconstituer à partir de logs applicatifs.

Un workflow classique :

• ne vérifie pas les qualifications
• n’engage pas la responsabilité
• ne fournit pas de preuve opposable
• n’est pas pensé pour l’IA

HumanLayer traite la décision comme un acte engageant, pas un clic.

Oui — là où c’est volontaire.

HumanLayer est appelé :

• uniquement sur des points critiques
• quand ralentir est préférable à prendre un risque

Partout ailleurs, votre système reste entièrement automatisé.

Parce que vous devriez construire :

• un système d’assignation
• une gouvernance humaine
• une traçabilité audit-grade
• des SLA décisionnels
• une API pensée pour être appelée par des agents

👉 HumanLayer vous fait gagner des mois, voire des années.