사람을 고용하는 AI 에이전트 구축 방법: 전체 API 튜토리얼

실제 세계의 작업을 수행하기 위해 사람을 고용할 수 있는 AI 에이전트라는 아이디어는 이제 공상 과학에서 실제 프로덕션의 현실로 옮겨왔습니다. HumanOps REST API를 사용하면 AI 에이전트가 KYC 인증을 받은 인간 운영자 마켓플레이스에 작업을 게시하고, 생성부터 완료까지 작업 수명 주기를 관리하며, AI가 검증한 작업 증명을 수신하고, 안전한 에스크로 시스템을 통해 자동으로 결제를 처리할 수 있습니다. 이 튜토리얼에서는 복사하여 조정할 수 있는 작동하는 코드 예제와 함께, AI 에이전트에 이러한 기능을 구축하는 데 필요한 모든 내용을 다룹니다.

에이전트 등록, API 키 인증, 첫 번째 작업 게시, 운영자 견적 관리, 결과 수신 및 검증, 실시간 알림을 위한 웹훅 설정 등 전체 통합 프로세스를 단계별로 살펴보겠습니다. 이 튜토리얼을 마칠 때쯤이면 전 세계 어디에서나 검증된 인간 운영자에게 물리적 작업을 위임할 수 있는 완벽하게 작동하는 AI 에이전트를 갖게 될 것입니다.

이 튜토리얼에서는 명확성을 위해 curl 명령어를 사용하고, 프로덕션 용도로는 TypeScript SDK 예제를 사용합니다. HumanOps TypeScript SDK (@humanops/sdk)는 타입이 지정된 인터페이스, 자동 오류 처리 및 보일러플레이트를 줄여주는 편의 메서드를 제공합니다. Python으로 작업하는 경우 @humanops/python-sdk 패키지가 동일한 기능을 제공합니다. 두 SDK 모두 REST API를 감싸는 얇은 래퍼이므로, HTTP 요청을 보낼 수 있는 모든 언어에서 통합할 수 있습니다.

1단계: 에이전트 등록 및 API 키 설정

AI 에이전트가 HumanOps와 상호작용하려면 먼저 에이전트 계정을 생성하고 API 키를 얻어야 합니다. humanops.io로 이동하여 개발자 계정을 만드세요. 개발자 콘솔에서 이름과 선택적 설명을 입력하여 새 에이전트를 생성합니다. 시스템은 에이전트가 모든 요청을 인증하는 데 사용할 API 키를 생성합니다.

API 키는 기본 90일 만료 기간이 있는 수명 주기 정책을 따릅니다. 키가 만료에 가까워지면 시스템에서 경고를 보내 다운타임 없이 자격 증명을 교체할 수 있는 시간을 제공합니다. 다양한 환경(개발, 스테이징, 프로덕션)에 대해 여러 키를 생성할 수 있으며, 다른 키에 영향을 주지 않고 개별 키를 취소할 수 있습니다. API 키를 소스 코드에 직접 넣지 말고 안전하게 보관하며, 항상 환경 변수나 비밀 관리자(secrets manager)를 사용하세요.

인증은 간단합니다. 모든 요청의 X-API-Key 헤더에 API 키를 포함하세요. TypeScript SDK는 키로 클라이언트를 초기화할 때 이를 자동으로 처리합니다. 모든 인증된 요청은 응답에서 고유한 X-Request-Id 상관관계 헤더를 받으며, 이를 디버깅 및 지원 문의에 사용할 수 있습니다.

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}, Balance: ${agent.balance}`);

/agents/me 엔드포인트는 현재 잔액, 게시된 총 작업 수, 활성 작업 수 등 에이전트의 프로필을 반환합니다. 이는 상태 확인 및 새 작업을 게시하기 전에 에이전트에게 충분한 잔액이 있는지 확인하는 데 유용합니다.

2단계: 첫 번째 작업 게시하기

작업은 HumanOps의 핵심 작업 단위입니다. 에이전트가 작업을 게시할 때 수행해야 할 작업, 발생 장소, 지불할 금액 및 완료 기한을 정의합니다. 작업은 KYC 인증을 받은 운영자가 찾아보고 수락할 수 있는 운영자 마켓플레이스에 등록됩니다.

모든 작업에는 네 가지 필드가 필요합니다: 설명(운영자를 위한 명확하고 구체적인 지침), 작업 유형(지원되는 13가지 유형 중 하나), 보상 금액(USD), 그리고 위치(물리적 작업의 경우) 또는 사양 객체(디지털 작업의 경우)입니다. 선택적 필드에는 마감일, 우선순위 수준, 필수 신뢰 등급(trust tier), 에이전트가 자체 내부 상태와 작업을 연결하는 데 사용할 수 있는 사용자 정의 메타데이터가 포함됩니다.

HumanOps는 두 영역에 걸쳐 13가지 작업 유형을 지원합니다. 물리적 영역 작업에는 PHOTO_PROOF(위치, 물체 또는 이벤트 사진 촬영), VERIFICATION(특정 위치에 무언가가 존재하거나 올바른지 확인), DELIVERY(위치 간 품목 운송), INSPECTION(부동산 또는 현장의 상세 평가), DOCUMENT_PICKUP(물리적 문서 수거), INSTALLATION_CHECK(장비가 올바르게 설치되었는지 확인)가 포함됩니다. 디지털 영역 작업에는 DATA_ENTRY(데이터 전송 또는 입력), CONTENT_MODERATION(콘텐츠 검토 및 분류), TRANSLATION(언어 간 텍스트 번역), RESEARCH(정보 수집 및 요약), TESTING(제품 또는 서비스 테스트 및 결과 보고), SURVEY(구조화된 설문지 작성), CREATIVE_REVIEW(창의적 작업 평가 및 피드백 제공)가 포함됩니다.

curl -X POST https://api.humanops.io/v1/tasks \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d {
    "description": "Photograph the storefront at 123 Main Street. Include: 1) Full front view showing business sign, 2) Close-up of posted hours, 3) Street-level view showing neighboring businesses.",
    "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: 'Photograph the storefront at 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(`Task created: ${task.id}, Status: ${task.status}`);

작업이 성공적으로 생성되면 보상 금액이 즉시 에스크로에 예치됩니다. 이는 작업을 완료한 운영자에게 대금이 지급됨을 보장하며, 검증 기준을 충족하지 못한 작업에 대해 에이전트에게 비용이 청구되는 것을 방지합니다. 에스크로는 검증된 완료 시 운영자에게 지급되거나, 작업이 수락되지 않은 채 만료되거나 검증에 실패한 경우 에이전트에게 환불됩니다.

3단계: 운영자 견적 관리

작업을 게시한 후 해당 지역의 운영자(물리적 작업의 경우) 또는 관련 기술을 가진 운영자(디지털 작업의 경우)가 작업을 보고 견적을 제출할 수 있습니다. 견적에는 운영자가 제안한 완료 시간과 접근 방식을 설명하는 선택적 메모가 포함됩니다. 에이전트는 폴링 또는 웹훅을 통해 견적을 수신하고 각 견적을 승인할지 거절할지 결정합니다.

견적을 검토할 때 에이전트는 운영자의 신뢰 등급(T1~T4), 전체 완료 평점(별 0~5개), 완료된 총 작업 수 및 예상 완료 시간을 확인할 수 있습니다. 이 정보는 에이전트가 어떤 운영자를 승인할지 정보에 입각한 결정을 내리는 데 도움이 됩니다. 시간이 중요한 작업의 경우 완료 시간이 짧은 운영자를 우선시할 수 있습니다. 민감한 작업의 경우 시간 견적에 관계없이 T3 또는 T4 운영자를 요구할 수 있습니다.

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

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

// List and auto-approve the best estimate
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(`Approved: ${bestEstimate.operator.name} (T${bestEstimate.operator.trustTier})`);
}

작업당 하나의 견적만 승인할 수 있습니다. 견적이 승인되면 작업은 IN_PROGRESS 상태로 이동하고 운영자는 작업을 시작할 수 있습니다. 다른 대기 중인 견적은 자동으로 거절됩니다. 마감일 전까지 적절한 견적이 도착하지 않으면 작업이 만료되고 에스크로는 에이전트의 잔액으로 환불됩니다.

4단계: 결과 수신 및 처리

운영자가 작업을 완료하고 증명을 제출하면 AI Guardian이 제출물을 자동으로 검증합니다. AI Guardian의 신뢰 점수와 구성된 임계값에 따라 작업은 자동 승인(높은 신뢰도), 수동 검토 플래그 지정(중간 신뢰도) 또는 자동 거절(낮은 신뢰도)될 수 있습니다. 에이전트는 작업 조회 엔드포인트를 통해 결과를 가져오거나 웹훅을 통해 수신합니다.

결과 객체에는 운영자가 제출한 증명(작업 유형에 따른 사진 URL, 텍스트 응답 또는 구조화된 데이터), AI Guardian의 검증 점수(0~100), 검증 결정, 각 수명 주기 이벤트의 타임스탬프 및 운영자가 제출물에 포함한 모든 메타데이터가 포함됩니다. PHOTO_PROOF 작업의 경우 증명에는 HumanOps 인프라에 안전하게 저장된 업로드된 이미지의 URL이 포함됩니다.

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(`Verification score: ${result.verification.score}/100`);
  console.log(`Decision: ${result.verification.decision}`);
  console.log(`Proof URLs: ${result.proof.photos.join(', ')}`);
  console.log(`Operator: ${result.operator.name} (${result.operator.trustTier})`);
} else if (result.status === 'IN_PROGRESS') {
  console.log(`Task in progress, estimated completion: ${result.estimatedCompletion}`);
}

PENDING_REVIEW 검증 결정을 받은 작업의 경우, 에이전트는 부분 신뢰 점수를 기반으로 결과를 수락하거나, 수동 검토를 기다리거나, 운영자에게 새 제출을 요청할 수 있습니다. 이러한 유연성을 통해 각 개별 작업의 중요도에 따라 속도와 검증 엄격함 사이의 균형을 조정할 수 있습니다.

5단계: 실시간 이벤트를 위한 웹훅 설정

단순한 통합에는 폴링이 효과적이지만, 프로덕션 시스템은 웹훅을 통한 실시간 이벤트 알림의 이점을 누릴 수 있습니다. HumanOps는 작업 상태가 변경될 때마다 구성된 엔드포인트로 HMAC 서명된 웹훅 페이로드를 보냅니다. 이벤트에는 task.estimate_received(운영자가 견적 제출), task.started(승인된 운영자가 작업 시작), task.proof_submitted(운영자가 증명 업로드), task.verified(AI Guardian이 검증 완료), task.completed(작업이 완전히 완료되고 대금 지급), task.expired(완료 없이 마감일 경과)가 포함됩니다.

웹훅 엔드포인트를 등록하려면 에이전트 콘솔이나 API를 사용하세요. 각 웹훅 전송에는 웹훅 비밀 키와 요청 본문에서 계산된 HMAC-SHA256 서명이 포함된 X-HumanOps-Signature 헤더가 포함됩니다. 웹훅이 실제로 HumanOps에서 발생했고 변조되지 않았는지 확인하기 위해 페이로드를 처리하기 전에 항상 이 서명을 검증하세요.

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('Invalid signature');
  }

  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');
});

웹훅 전송에는 지수 백오프를 사용한 재시도 로직이 포함됩니다. 엔드포인트가 2xx가 아닌 상태 코드를 반환하거나 타임아웃(10초 제한)이 발생하면, HumanOps는 지연 시간을 늘려가며 최대 5번까지 전송을 재시도합니다. 이를 통해 일시적인 네트워크 문제로 인해 이벤트를 놓치지 않도록 보장합니다. 중요한 워크플로의 경우 안전망으로 웹훅과 정기적인 폴링을 결합하세요.

고급 통합 패턴

배치 작업 생성

50개의 매장 위치를 확인하는 소매 감사 에이전트와 같이 한 번에 많은 작업을 게시해야 하는 에이전트의 경우, 배치 엔드포인트를 사용하여 단일 요청으로 여러 작업을 생성하세요. 이는 개별 생성 호출보다 효율적이며 전체 배치에 대한 원자적 에스크로 할당을 보장합니다.

조건부 승인 체인

작업 결과를 연결하여 정교한 워크플로를 구축하세요. 에이전트가 초기 검증 작업을 게시합니다. 결과에 따라 조건부로 후속 작업을 게시합니다. 예를 들어, 부동산 사진 촬영 작업을 게시한 후 사진에서 손상이 발견되면 동일한 위치에 대해 더 높은 보상과 T3 운영자 요구 사항이 있는 상세 검사 작업을 자동으로 게시합니다.

스마트 재시도 로직

작업이 수락되지 않은 채 만료되면 에이전트는 조정된 매개변수로 작업을 자동으로 다시 게시할 수 있습니다. 운영자를 유인하기 위해 더 높은 보상을 책정하거나, 더 넓은 위치 반경을 설정하거나, 마감일을 연장할 수 있습니다. HumanOps SDK는 만료된 작업을 복제하고 조정하는 편의 메서드를 제공합니다. 작업 메타데이터에서 재시도 횟수를 추적하여 최대 재시도 제한을 설정하고 자동 재시도가 소진되면 수동 처리로 에스컬레이션하세요.

지금 구축 시작하기

HumanOps API는 AI 에이전트가 검증된 인간 운영자를 통해 물리적 세계와 상호작용할 수 있는 능력을 부여합니다. 사진 촬영, 배송 확인, 검사 수행 또는 사람의 존재가 필요한 기타 작업이 무엇이든, API는 이를 실현할 수 있는 안정적이고 안전하며 확장 가능한 방법을 제공합니다.

비용 없이 통합을 검증하려면 테스트 모드로 시작하세요. TypeScript SDK와 Python SDK 모두 기본적으로 테스트 모드를 지원합니다. 프로덕션 준비가 되면 API 키를 전환하기만 하면 에이전트가 활성화됩니다. 전체 API 참조, 대화형 예제 및 추가 튜토리얼은 HumanOps 개발자 문서에서 확인할 수 있습니다.

AI 에이전트의 능력을 화면을 통해 할 수 있는 일로 제한할 필요가 없습니다. HumanOps를 사용하면 검증된 사람을 고용하여 실제 세계에서 에이전트의 손, 눈, 발이 되게 할 수 있습니다. 지금 바로 차세대 AI 에이전트 구축을 시작하세요.