튜토리얼: 실제 세계의 작업을 사람에게 위임하는 AI 에이전트 구축하기

2026년에 등장하는 가장 강력한 기능 중 하나는 AI 에이전트가 물리적 세계의 작업을 검증된 인간 운영자에게 위임할 수 있는 능력입니다. 디지털 API를 통해 달성할 수 있는 것에 국한되지 않고, 이제 AI 에이전트는 특정 위치의 사진 촬영, 배송 확인, 장비 점검 또는 문서 수집과 같은 실제 세계의 작업을 요청할 수 있습니다. 이 튜토리얼에서는 설정부터 프로덕션 배포까지 이 작업을 정확히 수행하는 완전한 AI 에이전트를 구축하는 과정을 안내합니다.

우리는 레스토랑 리뷰 플랫폼을 모니터링하고, 폐업 보고나 위생 규정 위반과 같은 잠재적인 문제를 감지하며, 인간 운영자를 물리적 위치로 자동 파견하여 상황을 확인하고 사진 증거를 제출하도록 하는 예제 에이전트를 구축할 것입니다. 그런 다음 에이전트는 검증 결과를 처리하고 조사 결과에 따라 적절한 조치를 취합니다. 이는 온라인 정보의 현장 실사 검증이 필요한 비즈니스에 있어 현실적인 사용 사례를 나타냅니다.

이 튜토리얼에서는 두 가지 통합 방법을 다룹니다: 최대의 유연성과 언어 중립적 통합을 위한 HumanOps REST API, 그리고 Claude, Cursor 및 기타 MCP 호환 AI 에이전트와의 네이티브 통합을 위한 HumanOps MCP 서버입니다. 두 방법 모두 동일한 핵심 기능을 제공하며, 선택은 에이전트의 아키텍처에 따라 달라집니다. 모든 코드 예제는 TypeScript로 작성되었지만, REST API 개념은 모든 프로그래밍 언어에 적용됩니다.

이 튜토리얼을 마칠 때쯤이면 작업을 생성하고, 이를 인간 운영자에게 할당하고, 증거 제출을 받고, 검증 결과를 확인하고, 전체 작업 수명 주기를 프로그래밍 방식으로 처리할 수 있는 작동하는 에이전트를 갖게 될 것입니다. 또한 웹훅 통합, 배치 작업 생성 및 시간에 민감한 검증을 위한 우선순위 처리를 통해 이 기반을 확장하는 방법도 이해하게 될 것입니다.

사전 요구 사항 및 설정

시작하기 전에 API 키가 포함된 HumanOps 계정이 필요합니다. humanops.io에서 가입하고 온보딩 프로세스를 완료한 후 API 설정 페이지로 이동하여 첫 번째 키를 생성하세요. 키는 한 번만 표시되므로 환경 변수에 안전하게 저장하세요. 이 튜토리얼에서는 HUMANOPS_API_KEY 환경 변수를 사용합니다.

또한 개발 머신에 Node.js 버전 18 이상이 설치되어 있어야 합니다. 유형 안전성과 더 나은 개발자 경험을 위해 TypeScript를 사용하지만, REST API 예제는 HTTP 요청을 보낼 수 있는 모든 언어에 맞게 조정할 수 있습니다. 새 프로젝트 디렉토리를 생성하고 npm init으로 초기화한 다음 필요한 종속성인 typescript, TypeScript를 직접 실행하기 위한 tsx, 그리고 네이티브 fetch 지원이 없는 Node 18을 사용하는 경우 node-fetch를 설치하세요.

MCP 서버 통합을 위해 Claude Desktop, Cursor 또는 Model Context Protocol을 지원하는 모든 애플리케이션과 같은 MCP 호환 호스트가 필요합니다. HumanOps MCP 서버는 로컬 머신에서 실행되고 API 키를 사용하여 HumanOps API에 연결되는 npm 패키지로 제공됩니다. 이 튜토리얼의 뒷부분에 있는 전용 섹션에서 MCP 구성을 다룰 것입니다.

HumanOps 테스트 환경은 가상 운영자를 통해 작업이 즉시 해결되는 샌드박스를 제공합니다. 즉, 실제 USDC를 지출하거나 실제 인간 운영자가 작업을 완료할 때까지 기다리지 않고도 전체 통합을 개발하고 테스트할 수 있습니다. 프로덕션 준비가 되면 API 키를 테스트 키에서 프로덕션 키로 전환하기만 하면 동일한 코드가 실제 운영자와 함께 작동합니다.

REST API 기본 사항

HumanOps REST API는 api.humanops.io에서 호스팅되며 JSON 형식의 응답과 함께 JSON 요청 본문을 수락합니다. 인증은 모든 요청에 포함되어야 하는 X-API-Key 헤더를 통해 처리됩니다. API는 REST 규칙을 따릅니다: 리소스 생성을 위한 POST, 읽기를 위한 GET, 업데이트를 위한 PUT, 그리고 성공 및 오류 응답을 위한 표준 HTTP 상태 코드입니다.

가장 기본적인 작업인 작업 생성부터 시작해 보겠습니다. 작업에는 운영자에게 수행할 작업을 알려주는 설명, 작업이 완료되어야 하는 위치를 지정하는 위치, USDC 단위의 보상 금액, 작업이 완료되어야 하는 마감 기한이 필요합니다. 다음은 REST API를 통해 작업을 생성하는 TypeScript 함수입니다. 이 함수는 작업 매개변수를 받아 tasks 엔드포인트에 POST 요청을 보내고, 고유 ID, 상태 및 에스크로 트랜잭션 참조를 포함하여 생성된 작업 객체를 반환합니다.

작업 생성 응답에는 몇 가지 중요한 필드가 포함되어 있습니다. task ID는 이후의 모든 API 호출에서 이 특정 작업을 참조하는 데 사용됩니다. status 필드는 작업의 현재 상태를 나타내며, 운영자가 찾아볼 수 있는 상태인 POSTED로 시작합니다. escrow_tx_id는 에이전트의 예치 계좌에서 에스크로 보유 계좌로 자금을 이동시킨 원장 트랜잭션을 참조하여 작업에 자금이 완전히 지원되었음을 확인합니다. created_at 타임스탬프는 작업이 생성된 정확한 시간을 기록합니다.

작업이 게시되면 운영자는 예상 소요 시간을 제출하여 작업을 찾아보고 요청할 수 있습니다. 에이전트는 작업 엔드포인트를 폴링하거나 웹훅 알림을 받아 예상치에 대한 알림을 받게 됩니다. 예상치에는 운영자의 ID, 예상 완료 시간 및 신뢰 등급이 포함됩니다. 에이전트는 운영자의 자격 요건과 작업의 긴급성에 따라 예상치를 승인하거나 거부해야 합니다.

레스토랑 모니터링 에이전트 구축하기

다음은 레스토랑 모니터링 에이전트의 전체 TypeScript 구현입니다. 이 코드는 검증 작업 생성, 운영자 예상치 모니터링, 예상치 승인 및 검증 결과 검색과 같은 전체 작업 수명 주기를 보여줍니다.

에이전트는 모든 API 상호 작용을 캡슐화하는 HumanOpsClient 클래스를 중심으로 구성됩니다. createVerificationTask 메서드는 어떤 사진을 찍어야 하고 무엇을 확인해야 하는지에 대한 구체적인 지침을 포함하여 레스토랑 검증에 맞춤화된 설명과 함께 새 작업을 게시합니다. 설명은 운영자와 AI Guardian 모두에게 무엇이 성공적인 완료인지 알려주기 때문에 매우 중요합니다. 잘 작성된 작업 설명은 더 나은 증거 제출과 더 정확한 자동 검증으로 이어집니다.

waitForEstimate 메서드는 폴링 기반 작업 모니터링을 보여줍니다. 프로덕션에서는 일반적으로 폴링 대신 웹훅을 사용하지만, 폴링은 시연 목적으로 더 간단하며 적은 수의 작업을 처리하는 에이전트에게 잘 작동합니다. 이 메서드는 30초마다 작업 상태를 확인하여 POSTED에서 ESTIMATED로의 전환을 찾습니다. 이는 운영자가 예상 소요 시간을 제출하고 작업을 시작할 준비가 되었음을 나타냅니다.

approveEstimate 메서드는 운영자가 작업을 시작하도록 승인합니다. 승인 후 작업 상태는 IN_PROGRESS로 변경되며 운영자는 마감 기한까지 증거를 제출해야 합니다. getResult 메서드는 AI Guardian 검증 점수, 증거 URL 및 상세 검증 내역을 포함하여 완료된 작업을 검색합니다. 에이전트는 이 정보를 사용하여 데이터베이스에서 레스토랑 상태를 업데이트하거나 후속 조치를 트리거하는 등 레스토랑에 대한 결정을 내릴 수 있습니다.

오류 처리는 모든 API 호출에 내장되어 있습니다. 네트워크 오류는 포착되어 의미 있는 메시지와 함께 기록됩니다. HTTP 오류 응답은 API에서 오류 코드와 설명을 추출하기 위해 파싱됩니다. 속도 제한 응답에는 retry-after 헤더 값이 포함되어 에이전트가 적절하게 대기할 수 있습니다. 이러한 방어적 코딩 스타일은 사람의 감독 없이 안정적으로 작동해야 하는 프로덕션 에이전트에게 필수적입니다.

MCP 서버 통합

HumanOps MCP 서버는 Claude Desktop 및 Cursor와 같은 MCP 호환 환경에서 실행되는 AI 에이전트에게 특히 강력한 대체 통합 경로를 제공합니다. HTTP 요청을 만들고 JSON 응답을 파싱하는 대신, 에이전트는 HumanOps 작업을 네이티브 도구로 호출할 수 있으므로 통합이 자연스럽게 느껴지고 작성해야 하는 상용구 코드의 양이 줄어듭니다.

MCP 서버를 설정하려면 humanops-mcp-server 패키지를 전역으로 설치하거나 프로젝트 종속성에 추가하세요. 그런 다음 MCP 호스트의 구성 파일에 서버 구성을 추가합니다. Claude Desktop의 경우, 서버를 시작하는 명령과 API 키가 포함된 환경 변수를 사용하여 구성의 mcpServers 섹션에 항목을 추가하는 것을 의미합니다. 전체 구성은 명령 경로, 인수 배열, HUMANOPS_API_KEY가 포함된 env 객체의 세 줄로 이루어집니다.

구성이 완료되면 AI 에이전트는 네 가지 주요 도구에 액세스할 수 있습니다: 설명, 위치, 보상 및 마감 기한 매개변수를 사용하여 새 작업을 생성하는 post_task, 운영자가 작업을 시작하도록 승인하는 approve_estimate, 검증 결과와 함께 완료된 작업을 검색하는 get_task_result, AI Guardian의 분석 진행 상황을 모니터링하는 check_verification_status입니다. 각 도구는 구조화된 매개변수를 수락하고 유형이 지정된 응답을 반환하므로 수동 JSON 파싱이 필요하지 않습니다.

MCP 통합은 대화형 AI 에이전트에게 특히 강력합니다. Claude에서 실행되는 에이전트는 대화 중에 물리적 세계의 검증이 필요하다고 자연스럽게 판단하고, post_task 도구를 호출하여 작업을 생성한 다음, 나중에 대화에서 get_task_result를 호출하여 검증을 검색하고 분석할 수 있습니다. 이를 통해 에이전트가 수행해야 할 작업을 생각하고, 물리적 작업을 사람에게 위임하고, 결과를 처리하는 모든 과정이 단일 대화 스레드 내에서 이루어지는 원활한 워크플로우가 생성됩니다.

실시간 업데이트를 위한 웹훅 통합

단순한 에이전트의 경우 폴링이 작동하지만, 프로덕션 배포에서는 실시간 작업 수명 주기 알림을 위해 웹훅을 사용해야 합니다. HumanOps 웹훅은 작업 수명 주기에서 중요한 이벤트가 발생할 때마다 엔드포인트로 HMAC-SHA256 서명된 HTTP POST 요청을 전달합니다. 이는 주기적인 폴링으로 인한 지연 시간과 리소스 낭비를 제거하고 에이전트가 이벤트에 최대한 빨리 응답하도록 보장합니다.

웹훅을 설정하려면 API 또는 대시보드를 통해 엔드포인트 URL을 등록하세요. 모든 웹훅 전달에 서명하는 데 사용되는 웹훅 암호를 받게 됩니다. 엔드포인트는 암호를 사용하여 원본 요청 본문에 대한 서명을 계산하고 이를 X-HumanOps-Signature 헤더의 값과 비교하여 들어오는 모든 요청의 HMAC 서명을 확인해야 합니다. 유효하지 않거나 누락된 서명이 있는 요청은 스푸핑될 수 있으므로 즉시 거부해야 합니다.

웹훅 이벤트에는 운영자가 예상 소요 시간을 제출할 때의 task.estimated, 운영자가 작업을 시작할 때의 task.started, 증거가 업로드될 때의 task.proof_submitted, AI Guardian이 분석을 완료할 때의 task.verified, 결제가 해제될 때의 task.completed가 포함됩니다. 각 이벤트에는 task ID, 이벤트 유형, 타임스탬프 및 이벤트 관련 데이터가 포함됩니다. 예를 들어, task.verified 이벤트에는 Guardian 신뢰 점수와 통과 또는 실패 판정이 포함되어 있어 에이전트가 별도의 API 호출 없이 즉시 결과를 처리할 수 있습니다.

웹훅 전달 시스템에는 지수 백오프를 사용한 자동 재시도가 포함되어 있습니다. 엔드포인트가 200 이외의 상태 코드를 반환하거나 10초 이내에 응답하지 않으면 시도 간 지연 시간을 늘려 최대 5번까지 전달을 재시도합니다. 모든 재시도가 소진되면 이벤트는 수동으로 재생할 수 있는 데드 레터 큐(dead letter queue)에 배치됩니다. 이러한 안정성 보장은 서버에 일시적인 가동 중지 시간이 발생하더라도 에이전트가 이벤트를 절대 놓치지 않도록 합니다.

고급 주제: 배치 처리, 우선순위 및 확장

동시에 많은 작업을 생성해야 하는 에이전트의 경우, 배치 생성 엔드포인트는 작업 사양 배열을 수락하고 단일 API 호출로 모든 작업을 생성합니다. 이는 HTTP 왕복 횟수를 줄이고 플랫폼이 에스크로 자금 지원 프로세스를 최적화할 수 있게 해주므로 작업을 하나씩 생성하는 것보다 훨씬 효율적입니다. 도시 전역에서 10개의 잠재적 문제를 감지하는 레스토랑 모니터링 에이전트는 단일 API 호출로 10개의 검증 작업을 모두 파견할 수 있으며, 각 작업은 동일한 에이전트 예치 계좌에서 자금이 지원됩니다.

우선순위 처리를 통해 에이전트는 작업의 긴급성을 나타낼 수 있습니다. 표준 우선순위 작업은 운영자가 위치 근접성과 개인적 선호도에 따라 찾아보고 요청하는 일반 풀에 들어갑니다. 높은 우선순위 작업은 운영자 인터페이스에서 강조 표시되며 근처 운영자와의 신속한 매칭 대상이 될 수 있습니다. 보고된 폐업 후 레스토랑이 다시 문을 열었는지 확인하는 것과 같이 시간에 민감한 검증의 경우, 높은 우선순위는 작업이 최대한 빨리 요청되고 완료되도록 보장합니다.

개념 증명에서 프로덕션으로 에이전트를 확장하려면 몇 가지 고려 사항이 필요합니다. 첫째, 지연 시간과 리소스 소비를 줄이기 위해 폴링에서 웹훅으로 전환하세요. 둘째, 각 작업 생성 요청에 클라이언트가 생성한 멱등성 키를 포함하여 멱등성 작업 생성을 구현함으로써 네트워크 시간 초과로 인해 에이전트가 요청을 재시도할 경우 중복 작업이 발생하는 것을 방지하세요. 셋째, 속도 제한, 잔액 부족 및 API 가동 중지 시간에 대한 적절한 오류 처리를 구현하세요. 넷째, 에이전트 전체에서 작업 생성 속도, 검증 점수 및 완료 시간을 추적할 수 있도록 로깅 및 모니터링을 추가하세요.

HumanOps API는 작업 목록을 표시하기 위한 페이지네이션과 상태, 날짜 범위 및 위치별 필터링을 지원합니다. 수백 개의 동시 작업을 관리하는 에이전트의 경우 이러한 필터링 기능은 효율적인 워크플로우를 유지하는 데 필수적입니다. 보류 중인 승인을 처리하기 위해 ESTIMATED 상태의 모든 작업을 쿼리하거나, 마감 기한이 다가오는 작업을 모니터링하기 위해 IN_PROGRESS 상태의 모든 작업을 쿼리하거나, 보고 및 분석을 위해 특정 날짜 범위 내의 모든 완료된 작업을 쿼리할 수 있습니다.

종합하기

우리의 레스토랑 모니터링 에이전트는 이러한 모든 구성 요소를 프로덕션 준비가 된 시스템으로 결합합니다. 에이전트는 지속적으로 실행되어 리뷰 데이터의 이상 징후를 모니터링합니다. 잠재적인 문제를 감지하면 상세한 설명, 위치, 작업 복잡도에 맞게 조정된 보상, 긴급도에 따른 마감 기한을 설정하여 검증 작업을 생성합니다. 에이전트는 웹훅을 사용하여 운영자가 작업을 요청하고, 증거를 제출하고, 검증 결과를 받을 때 실시간 업데이트를 받습니다.

검증 결과는 에이전트의 의사 결정 프로세스에 다시 반영됩니다. AI Guardian이 레스토랑이 폐업한 것으로 보인다고 확인하면 에이전트는 데이터베이스를 업데이트하고 다운스트림 시스템에 알림을 트리거할 수 있습니다. Guardian의 점수가 수동 검토 영역에 있는 경우, 에이전트는 인간의 검토를 기다리거나 자체 인간 운영자가 조사할 수 있도록 결과를 표시할 수 있습니다. Guardian이 레스토랑이 정상적으로 영업 중임을 확인하면 에이전트는 기록을 업데이트하고 조사를 종료합니다.

이러한 감지, 위임, 검증 및 결정 패턴은 레스토랑 모니터링을 훨씬 넘어 적용 가능합니다. 동일한 아키텍처가 배송 확인, 부동산 점검, 재고 조사, 현장 서비스 검증 및 AI 에이전트가 물리적 세계의 현장 실사가 필요한 기타 모든 사용 사례에 작동합니다. HumanOps 플랫폼은 인프라를 제공하고, 에이전트는 무엇을 검증하고 결과로 무엇을 할지 결정하는 지능을 제공합니다.

구축을 시작하려면 HumanOps 문서를 방문하여 전체 API 참조, SDK 설치 가이드 및 추가 코드 예제를 확인하세요. 테스트 환경은 가입 즉시 신용카드 없이 사용할 수 있습니다. MCP 통합 경로를 선호하는 경우, MCP 서버 문서에 Claude Desktop, Cursor 및 기타 지원되는 호스트에 대한 구성 예제가 포함되어 있습니다. 검증 작업을 완료하고 USDC를 벌고 싶은 운영자의 경우, 운영자 가이드에서 가입 및 검증 프로세스를 다룹니다.