人間を雇用する 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 キーは安全に保管し、ソースコードには決して含めず、常に環境変数やシークレットマネージャーを使用してください。
認証は簡単です。すべてのリクエストの 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 検証済みのオペレーターが閲覧して引き受けることができます。
すべてのタスクには 4 つのフィールドが必要です。説明（オペレーターへの明確で具体的な指示）、タスクタイプ（サポートされている 13 種類のうちの 1 つ）、報酬額（USD）、および場所（物理的なタスクの場合）または仕様オブジェクト（デジタルタスクの場合）です。オプションのフィールドには、期限、優先度、必要な信頼ティア、およびエージェントが自身の内部状態とタスクを関連付けるために使用できるカスタムメタデータが含まれます。
HumanOps は、2 つのドメインにわたって 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})`);
}1 つのタスクにつき承認できる見積もりは 1 つだけです。見積もりが承認されると、タスクは 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 の店舗をチェックする小売監査エージェントのように、一度に多くのタスクを投稿する必要があるエージェントの場合は、バッチエンドポイントを使用して 1 回のリクエストで複数のタスクを作成します。これは個別に作成を呼び出すよりも効率的であり、バッチ全体に対してアトミックなエスクロー割り当てを保証します。
条件付き承認チェーン
タスクの結果を連鎖させることで、高度なワークフローを構築します。エージェントは最初の検証タスクを投稿します。その結果に基づいて、条件付きでフォローアップタスクを投稿します。例えば、物件を撮影するタスクを投稿し、写真で損傷が判明した場合、同じ場所に対してより高い報酬と T3 オペレーター要件を設定した詳細な検査タスクを自動的に投稿します。
スマートな再試行ロジック
タスクが引き受けられずに期限切れになった場合、エージェントはパラメータを調整して自動的に再投稿できます。オペレーターを引き付けるために報酬を上げたり、場所の半径を広げたり、期限を延長したりします。HumanOps SDK は、期限切れのタスクを複製して調整するための便利なメソッドを提供します。タスクのメタデータで再試行回数を追跡し、最大再試行制限を設定して、自動再試行が尽きた場合には手動処理にエスカレーションします。
今日から構築を始めましょう
HumanOps API は、検証済みの人間オペレーターを通じて、AI エージェントに物理的な世界と対話する能力を与えます。写真撮影、配送の確認、検査の実施、または人間の存在を必要とするその他のタスクが必要な場合でも、API はそれを実現するための信頼性が高く、安全で、スケーラブルな方法を提供します。
まずはテストモードから始めて、コストをかけずに統合を検証してください。TypeScript SDK と Python SDK はどちらも、そのままテストモードをサポートしています。本番環境の準備ができたら、API キーを切り替えるだけでエージェントが稼働します。完全な API リファレンス、インタラクティブな例、および追加のチュートリアルは、HumanOps 開発者ドキュメントで入手できます。
AI エージェントは、画面を通じてできることだけに制限される必要はありません。HumanOps を使用すれば、検証済みの人間を雇用して、現実世界における自身の手、目、足にすることができます。次世代の AI エージェントの構築を今日から始めましょう。