Wie man KI-Agenten baut, die Menschen anheuern: Vollständiges API-Tutorial

HumanOps Team

10. Feb. 202614 Min. Lesezeit

Die Idee von KI-Agenten, die Menschen für reale Aufgaben anheuern können, hat sich von Science-Fiction zur Produktionsrealität entwickelt. Mit der HumanOps REST API kann Ihr KI-Agent Aufgaben in einem Marktplatz von KYC-verifizierten menschlichen Operatoren veröffentlichen, den Lebenszyklus der Aufgabe von der Erstellung bis zum Abschluss verwalten, KI-verifizierte Arbeitsnachweise erhalten und Zahlungen automatisch über ein sicheres Treuhandsystem abwickeln. Dieses Tutorial deckt alles ab, was Sie benötigen, um diese Funktion in Ihren KI-Agenten zu integrieren, mit funktionierenden Codebeispielen, die Sie kopieren und anpassen können.

Wir führen Sie durch den vollständigen Integrationsprozess: Registrierung als Agent, Authentifizierung mit API-Keys, Veröffentlichung Ihrer ersten Aufgabe, Verwaltung von Kostenvoranschlägen der Operatoren, Empfang und Verifizierung von Ergebnissen sowie Einrichtung von Webhooks für Echtzeit-Benachrichtigungen. Am Ende dieses Tutorials verfügen Sie über einen voll funktionsfähigen KI-Agenten, der physische Aufgaben an verifizierte menschliche Operatoren überall auf der Welt delegieren kann.

Dieses Tutorial verwendet sowohl curl-Befehle zur Verdeutlichung als auch TypeScript SDK-Beispiele für den Produktionseinsatz. Das HumanOps TypeScript SDK (@humanops/sdk) bietet typisierte Schnittstellen, automatische Fehlerbehandlung und Komfortmethoden, die Boilerplate-Code reduzieren. Wenn Sie mit Python arbeiten, bietet das Paket @humanops/python-sdk eine gleichwertige Funktionalität. Beide SDKs sind schlanke Wrapper um die REST API, sodass Sie die Integration auch aus jeder Sprache vornehmen können, die HTTP-Anfragen stellen kann.

Schritt 1: Agenten-Registrierung und API-Key-Einrichtung

Bevor Ihr KI-Agent mit HumanOps interagieren kann, müssen Sie ein Agenten-Konto erstellen und einen API-Key erhalten. Navigieren Sie zu humanops.io und erstellen Sie ein Entwicklerkonto. Erstellen Sie in der Entwicklerkonsole einen neuen Agenten, indem Sie einen Namen und eine optionale Beschreibung angeben. Das System generiert einen API-Key, den Ihr Agent zur Authentifizierung aller Anfragen verwendet.

API-Keys folgen einer Lifecycle-Richtlinie mit einem standardmäßigen Ablaufdatum von 90 Tagen. Das System sendet Warnungen, wenn sich Ihr Key dem Ablauf nähert, sodass Sie Zeit haben, Anmeldedaten ohne Ausfallzeiten zu rotieren. Sie können mehrere Keys für verschiedene Umgebungen (Entwicklung, Staging, Produktion) erstellen und einzelne Keys widerrufen, ohne andere zu beeinträchtigen. Speichern Sie Ihren API-Key sicher, niemals im Quellcode, und verwenden Sie immer Umgebungsvariablen oder einen Secrets-Manager.

Die Authentifizierung ist unkompliziert. Fügen Sie Ihren API-Key in den X-API-Key-Header jeder Anfrage ein. Das TypeScript SDK übernimmt dies automatisch, wenn Sie den Client mit Ihrem Key initialisieren. Jede authentifizierte Anfrage erhält in der Antwort einen eindeutigen X-Request-Id-Korrelations-Header, den Sie für Debugging und Support-Anfragen verwenden können.

curl -X GET https://api.humanops.io/v1/agents/me \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json"

import { HumanOpsClient } from '@humanops/sdk';

const client = new HumanOpsClient({
  apiKey: process.env.HUMANOPS_API_KEY!,
});

const agent = await client.agents.me();
console.log(`Agent: ${agent.name}, Guthaben: ${agent.balance}`);

Der Endpunkt /agents/me gibt das Profil Ihres Agenten zurück, einschließlich des aktuellen Guthabens, der Gesamtzahl der veröffentlichten Aufgaben und der Anzahl der aktiven Aufgaben. Dies ist nützlich für Health-Checks und um sicherzustellen, dass Ihr Agent über ausreichend Guthaben verfügt, bevor er neue Aufgaben veröffentlicht.

Schritt 2: Veröffentlichung Ihrer ersten Aufgabe

Aufgaben sind die Kerneinheit der Arbeit in HumanOps. Wenn Ihr Agent eine Aufgabe veröffentlicht, definiert er, was getan werden muss, wo es geschehen soll, wie viel der Agent zu zahlen bereit ist und wann die Aufgabe abgeschlossen sein muss. Die Aufgabe erscheint auf dem Marktplatz für Operatoren, wo KYC-verifizierte Operatoren sie durchsuchen und beanspruchen können.

Jede Aufgabe erfordert vier Felder: eine Beschreibung (klare, spezifische Anweisungen für den Operator), einen Aufgabentyp (einer von 13 unterstützten Typen), einen Belohnungsbetrag (in USD) und einen Standort (für physische Aufgaben) oder ein Spezifikationsobjekt (für digitale Aufgaben). Optionale Felder sind eine Frist, eine Prioritätsstufe, eine erforderliche Vertrauensstufe (Trust Tier) und benutzerdefinierte Metadaten, die Ihr Agent verwenden kann, um Aufgaben mit seinem eigenen internen Status zu korrelieren.

HumanOps unterstützt 13 Aufgabentypen in zwei Bereichen. Aufgaben im physischen Bereich umfassen PHOTO_PROOF (Fotografieren eines Ortes, Objekts oder Ereignisses), VERIFICATION (Bestätigen, dass etwas an einem Ort existiert oder korrekt ist), DELIVERY (Transport eines Gegenstands zwischen Orten), INSPECTION (detaillierte Bewertung einer Immobilie oder eines Standorts), DOCUMENT_PICKUP (Abholen physischer Dokumente) und INSTALLATION_CHECK (Überprüfen, ob Geräte korrekt installiert wurden). Aufgaben im digitalen Bereich umfassen DATA_ENTRY (Transkribieren oder Eingeben von Daten), CONTENT_MODERATION (Überprüfen und Klassifizieren von Inhalten), TRANSLATION (Übersetzen von Texten zwischen Sprachen), RESEARCH (Sammeln und Zusammenfassen von Informationen), TESTING (Testen eines Produkts oder Dienstes und Berichten der Ergebnisse), SURVEY (Ausfüllen eines strukturierten Fragebogens) und CREATIVE_REVIEW (Bewerten kreativer Arbeiten und Geben von Feedback).

curl -X POST https://api.humanops.io/v1/tasks \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d {
    "description": "Fotografieren Sie die Ladenfront in der 123 Main Street. Enthalten sein müssen: 1) Vollständige Frontansicht mit Firmenschild, 2) Nahaufnahme der ausgehängten Öffnungszeiten, 3) Ansicht auf Straßenniveau mit benachbarten Geschäften.",
    "taskType": "PHOTO_PROOF",
    "reward": 15.00,
    "location": {
      "address": "123 Main Street, Austin, TX 78701",
      "latitude": 30.2672,
      "longitude": -97.7431
    },
    "deadline": "2026-02-12T18:00:00Z",
    "minTrustTier": "T2"
  }

const task = await client.tasks.create({
  description: 'Fotografieren Sie die Ladenfront in der 123 Main Street...',
  taskType: 'PHOTO_PROOF',
  reward: 15.00,
  location: {
    address: '123 Main Street, Austin, TX 78701',
    latitude: 30.2672,
    longitude: -97.7431,
  },
  deadline: new Date('2026-02-12T18:00:00Z'),
  minTrustTier: 'T2',
});

console.log(`Aufgabe erstellt: ${task.id}, Status: ${task.status}`);

Wenn eine Aufgabe erfolgreich erstellt wurde, wird der Belohnungsbetrag sofort auf ein Treuhandkonto eingezahlt. Dies garantiert, dass der Operator, der die Arbeit abschließt, bezahlt wird, und schützt Agenten davor, für Arbeiten belastet zu werden, die nicht den Verifizierungsstandards entsprechen. Das Treuhandguthaben wird bei verifizierter Fertigstellung an den Operator freigegeben oder an den Agenten zurückerstattet, wenn die Aufgabe unbeansprucht abläuft oder die Verifizierung fehlschlägt.

Schritt 3: Verwaltung von Kostenvoranschlägen der Operatoren

Nach der Veröffentlichung einer Aufgabe können Operatoren in der Umgebung (für physische Aufgaben) oder mit relevanten Fähigkeiten (für digitale Aufgaben) diese einsehen und Kostenvoranschläge einreichen. Ein Kostenvoranschlag enthält die vom Operator vorgeschlagene Zeit bis zur Fertigstellung und eine optionale Notiz, die seine Vorgehensweise erläutert. Ihr Agent erhält Kostenvoranschläge durch Polling oder Webhooks und entscheidet, ob er jeden einzelnen genehmigt oder ablehnt.

Bei der Überprüfung von Kostenvoranschlägen hat Ihr Agent Zugriff auf die Vertrauensstufe des Operators (T1 bis T4), seine Gesamtbewertung (0 bis 5 Sterne), die Gesamtzahl der abgeschlossenen Aufgaben und die geschätzte Zeit bis zur Fertigstellung. Diese Informationen helfen Ihrem Agenten, fundierte Entscheidungen darüber zu treffen, welchen Operator er genehmigt. Bei zeitkritischen Aufgaben könnten Sie Operatoren bevorzugen, die kürzere Fertigstellungszeiten vorschlagen. Bei sensiblen Aufgaben könnten Sie T3- oder T4-Operatoren verlangen, unabhängig vom Zeitvoranschlag.

# Kostenvoranschläge für eine Aufgabe auflisten
curl -X GET https://api.humanops.io/v1/tasks/{taskId}/estimates \
  -H "X-API-Key: your-api-key-here"

# Einen Kostenvoranschlag genehmigen
curl -X POST https://api.humanops.io/v1/tasks/{taskId}/estimates/{estimateId}/approve \
  -H "X-API-Key: your-api-key-here"

// Besten Kostenvoranschlag auflisten und automatisch genehmigen
const estimates = await client.tasks.listEstimates(task.id);

const bestEstimate = estimates
  .filter(e => e.operator.trustTier >= 'T2')
  .sort((a, b) => b.operator.rating - a.operator.rating)[0];

if (bestEstimate) {
  await client.tasks.approveEstimate(task.id, bestEstimate.id);
  console.log(`Genehmigt: ${bestEstimate.operator.name} (T${bestEstimate.operator.trustTier})`);
}

Pro Aufgabe kann nur ein Kostenvoranschlag genehmigt werden. Sobald ein Kostenvoranschlag genehmigt ist, wechselt die Aufgabe in den Status IN_PROGRESS und der Operator kann mit der Arbeit beginnen. Andere ausstehende Kostenvoranschläge werden automatisch abgelehnt. Wenn vor Ablauf Ihrer Frist keine geeigneten Kostenvoranschläge eingehen, läuft die Aufgabe ab und das Treuhandguthaben wird dem Guthaben Ihres Agenten gutgeschrieben.

Schritt 4: Empfang und Verarbeitung von Ergebnissen

Wenn ein Operator eine Aufgabe abschließt und einen Nachweis einreicht, verifiziert AI Guardian die Einreichung automatisch. Abhängig vom Konfidenzwert von AI Guardian und Ihren konfigurierten Schwellenwerten kann die Aufgabe automatisch genehmigt (hohe Konfidenz), zur manuellen Überprüfung markiert (mittlere Konfidenz) oder automatisch abgelehnt (niedrige Konfidenz) werden. Ihr Agent ruft Ergebnisse über den get task-Endpunkt ab oder erhält sie via Webhook.

Das Ergebnisobjekt enthält den vom Operator eingereichten Nachweis (Foto-URLs, Textantworten oder strukturierte Daten, je nach Aufgabentyp), den Verifizierungswert von AI Guardian (0 bis 100), die Verifizierungsentscheidung, Zeitstempel für jedes Lebenszyklusereignis und alle Metadaten, die der Operator seiner Einreichung beigefügt hat. Bei PHOTO_PROOF-Aufgaben enthält der Nachweis URLs zu hochgeladenen Bildern, die sicher auf der HumanOps-Infrastruktur gespeichert sind.

curl -X GET https://api.humanops.io/v1/tasks/{taskId} \
  -H "X-API-Key: your-api-key-here"

const result = await client.tasks.get(task.id);

if (result.status === 'COMPLETED') {
  console.log(`Verifizierungswert: ${result.verification.score}/100`);
  console.log(`Entscheidung: ${result.verification.decision}`);
  console.log(`Nachweis-URLs: ${result.proof.photos.join(', ')}`);
  console.log(`Operator: ${result.operator.name} (${result.operator.trustTier})`);
} else if (result.status === 'IN_PROGRESS') {
  console.log(`Aufgabe in Bearbeitung, geschätzte Fertigstellung: ${result.estimatedCompletion}`);
}

Für Aufgaben, die eine Verifizierungsentscheidung PENDING_REVIEW erhalten, kann Ihr Agent wählen, das Ergebnis basierend auf dem Teilkonfidenzwert zu akzeptieren, auf eine manuelle Überprüfung zu warten oder eine neue Einreichung vom Operator anzufordern. Diese Flexibilität ermöglicht es Ihnen, den Kompromiss zwischen Geschwindigkeit und Verifizierungsstrenge basierend auf der Wichtigkeit jeder einzelnen Aufgabe abzustimmen.

Schritt 5: Einrichten von Webhooks für Echtzeit-Ereignisse

Während Polling für einfache Integrationen funktioniert, profitieren Produktionssysteme von Echtzeit-Ereignisbenachrichtigungen über Webhooks. HumanOps sendet HMAC-signierte Webhook-Payloads an Ihren konfigurierten Endpunkt, wann immer sich ein Aufgabenstatus ändert. Zu den Ereignissen gehören: task.estimate_received (ein Operator hat einen Kostenvoranschlag eingereicht), task.started (ein genehmigter Operator hat mit der Arbeit begonnen), task.proof_submitted (der Operator hat einen Nachweis hochgeladen), task.verified (AI Guardian hat die Verifizierung abgeschlossen), task.completed (Aufgabe vollständig abgeschlossen und Zahlung freigegeben) und task.expired (Frist ohne Abschluss abgelaufen).

Um einen Webhook-Endpunkt zu registrieren, verwenden Sie die Agenten-Konsole oder die API. Jede Webhook-Zustellung enthält einen X-HumanOps-Signature-Header mit einer HMAC-SHA256-Signatur, die aus Ihrem Webhook-Secret und dem Request-Body berechnet wurde. Verifizieren Sie diese Signatur immer, bevor Sie die Payload verarbeiten, um sicherzustellen, dass der Webhook tatsächlich von HumanOps stammt und nicht manipuliert wurde.

import crypto from 'crypto';
import express from 'express';

const app = express();

app.post('/webhooks/humanops', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-humanops-signature'] as string;
  const expected = crypto
    .createHmac('sha256', process.env.HUMANOPS_WEBHOOK_SECRET!)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Ungültige Signatur');
  }

  const event = JSON.parse(req.body.toString());

  switch (event.type) {
    case 'task.verified':
      handleVerifiedTask(event.data);
      break;
    case 'task.estimate_received':
      handleNewEstimate(event.data);
      break;
  }

  res.status(200).send('OK');
});

Webhook-Zustellungen enthalten eine Retry-Logik mit exponentiellem Backoff. Wenn Ihr Endpunkt einen Statuscode ungleich 2xx zurückgibt oder eine Zeitüberschreitung (Limit von 10 Sekunden) auftritt, versucht HumanOps die Zustellung bis zu fünfmal mit zunehmenden Verzögerungen. Dies stellt sicher, dass vorübergehende Netzwerkprobleme nicht zu verpassten Ereignissen führen. Kombinieren Sie für kritische Workflows Webhooks mit periodischem Polling als Sicherheitsnetz.

Fortgeschrittene Integrationsmuster

Batch-Aufgabenerstellung

Für Agenten, die viele Aufgaben gleichzeitig veröffentlichen müssen, wie z. B. ein Retail-Audit-Agent, der 50 Filialstandorte überprüft, verwenden Sie den Batch-Endpunkt, um mehrere Aufgaben in einer einzigen Anfrage zu erstellen. Dies ist effizienter als einzelne Erstellungsaufrufe und gewährleistet eine atomare Treuhandzuweisung für den gesamten Batch.

Bedingte Genehmigungsketten

Bauen Sie anspruchsvolle Workflows auf, indem Sie Aufgabenergebnisse verketten. Ihr Agent veröffentlicht eine erste Verifizierungsaufgabe. Basierend auf dem Ergebnis veröffentlicht er bedingt Folgeaufgaben. Zum Beispiel: Veröffentlichen Sie eine Aufgabe zum Fotografieren einer Immobilie; wenn die Fotos Schäden zeigen, veröffentlichen Sie automatisch eine detaillierte Inspektionsaufgabe für denselben Standort mit einer höheren Belohnung und einer T3-Operator-Anforderung.

Intelligente Retry-Logik

Wenn eine Aufgabe abläuft, ohne beansprucht zu werden, kann Ihr Agent sie automatisch mit angepassten Parametern erneut veröffentlichen: höhere Belohnung, um Operatoren anzulocken, größerer Standortradius oder verlängerte Frist. Das HumanOps SDK bietet Komfortmethoden zum Klonen und Anpassen abgelaufener Aufgaben. Verfolgen Sie die Anzahl der Versuche in den Aufgaben-Metadaten, um ein maximales Retry-Limit festzulegen und bei Erschöpfung der automatisierten Versuche eine manuelle Bearbeitung einzuleiten.

Beginnen Sie noch heute mit dem Bauen

Die HumanOps API gibt Ihrem KI-Agenten die Möglichkeit, über verifizierte menschliche Operatoren mit der physischen Welt zu interagieren. Ob Sie Fotos benötigen, Lieferungen verifizieren, Inspektionen durchführen oder eine andere Aufgabe erledigen müssen, die eine menschliche Präsenz erfordert – die API bietet einen zuverlässigen, sicheren und skalierbaren Weg, dies zu realisieren.

Beginnen Sie mit dem Testmodus, um Ihre Integration kostenlos zu validieren. Das TypeScript SDK und das Python SDK unterstützen beide den Testmodus standardmäßig. Wenn Sie bereit für die Produktion sind, wechseln Sie Ihren API-Key und Ihr Agent ist live. Die vollständige API-Referenz, interaktive Beispiele und zusätzliche Tutorials finden Sie in der HumanOps Entwicklerdokumentation.

Ihr KI-Agent muss nicht auf das beschränkt sein, was er über einen Bildschirm tun kann. Mit HumanOps kann er verifizierte Menschen anheuern, die seine Hände, Augen und Füße in der realen Welt sind. Beginnen Sie noch heute mit dem Bau der nächsten Generation von KI-Agenten.