ऐसे AI एजेंट कैसे बनाएं जो मनुष्यों को काम पर रखते हैं: पूर्ण API ट्यूटोरियल

AI एजेंटों का विचार जो वास्तविक दुनिया के कार्यों को करने के लिए मनुष्यों को काम पर रख सकते हैं, विज्ञान कथा से उत्पादन वास्तविकता में बदल गया है। HumanOps REST API के साथ, आपका AI एजेंट KYC-सत्यापित मानव ऑपरेटरों के बाज़ार में कार्य पोस्ट कर सकता है, निर्माण से लेकर पूर्णता तक कार्य जीवनचक्र का प्रबंधन कर सकता है, कार्य का AI-सत्यापित प्रमाण प्राप्त कर सकता है, और एक सुरक्षित एस्क्रो सिस्टम के माध्यम से स्वचालित रूप से भुगतान संभाल सकता है। यह ट्यूटोरियल आपके AI एजेंट में इस क्षमता को बनाने के लिए आवश्यक हर चीज़ को कवर करता है, जिसमें काम करने वाले कोड उदाहरण हैं जिन्हें आप कॉपी और अनुकूलित कर सकते हैं।

हम पूरी एकीकरण प्रक्रिया के माध्यम से चलेंगे: एक एजेंट के रूप में पंजीकरण करना, API कुंजियों के साथ प्रमाणित करना, अपना पहला कार्य पोस्ट करना, ऑपरेटर अनुमानों का प्रबंधन करना, परिणाम प्राप्त करना और सत्यापित करना, और रीयल-टाइम सूचनाओं के लिए webhooks सेट करना। इस ट्यूटोरियल के अंत तक, आपके पास एक पूरी तरह कार्यात्मक AI एजेंट होगा जो दुनिया में कहीं भी सत्यापित मानव ऑपरेटरों को भौतिक कार्य सौंप सकता है।

यह ट्यूटोरियल स्पष्टता के लिए curl कमांड और उत्पादन उपयोग के लिए TypeScript SDK उदाहरण दोनों का उपयोग करता है। HumanOps TypeScript SDK (@humanops/sdk) टाइप किए गए इंटरफेस, स्वचालित त्रुटि हैंडलिंग और सुविधा के तरीके प्रदान करता है जो बॉयलरप्लेट को कम करते हैं। यदि आप Python में काम कर रहे हैं, तो @humanops/python-sdk पैकेज समकक्ष कार्यक्षमता प्रदान करता है। दोनों SDKs 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 में काम की मुख्य इकाई हैं। जब आपका AI एजेंट कोई कार्य पोस्ट करता है, तो वह परिभाषित करता है कि क्या किया जाना है, इसे कहाँ होना है, एजेंट कितना भुगतान करने को तैयार है, और इसे कब पूरा करने की आवश्यकता है। कार्य ऑपरेटर बाज़ार में प्रवेश करता है जहाँ KYC-सत्यापित ऑपरेटर इसे ब्राउज़ और क्लेम कर सकते हैं।

प्रत्येक कार्य के लिए चार फ़ील्ड की आवश्यकता होती है: एक विवरण (ऑपरेटर के लिए स्पष्ट, विशिष्ट निर्देश), एक कार्य प्रकार (13 समर्थित प्रकारों में से एक), एक इनाम राशि (USD में), और एक स्थान (भौतिक कार्यों के लिए) या एक विनिर्देश ऑब्जेक्ट (डिजिटल कार्यों के लिए)। वैकल्पिक फ़ील्ड में समय सीमा, प्राथमिकता स्तर, आवश्यक ट्रस्ट टियर और कस्टम मेटाडेटा शामिल हैं जिनका उपयोग आपका एजेंट कार्यों को अपनी आंतरिक स्थिति के साथ सहसंबंधित करने के लिए कर सकता है।

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: ऑपरेटर अनुमानों का प्रबंधन

कार्य पोस्ट करने के बाद, क्षेत्र के ऑपरेटर (भौतिक कार्यों के लिए) या प्रासंगिक कौशल वाले (डिजिटल कार्यों के लिए) इसे देख सकते हैं और अनुमान प्रस्तुत कर सकते हैं। एक अनुमान में ऑपरेटर का पूरा होने का प्रस्तावित समय और उनके दृष्टिकोण की व्याख्या करने वाला एक वैकल्पिक नोट शामिल होता है। आपका एजेंट पोलिंग या webhooks के माध्यम से अनुमान प्राप्त करता है और यह तय करता है कि प्रत्येक को स्वीकृत करना है या अस्वीकार करना है।

अनुमानों की समीक्षा करते समय, आपके एजेंट के पास ऑपरेटर के ट्रस्ट टियर (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 के विश्वास स्कोर और आपके कॉन्फ़िगर किए गए थ्रेशोल्ड के आधार पर, कार्य को ऑटो-अनुमोदित (उच्च विश्वास), मैन्युअल समीक्षा के लिए फ़्लैग (मध्यम विश्वास), या ऑटो-अस्वीकृत (कम विश्वास) किया जा सकता है। आपका एजेंट गेट टास्क एंडपॉइंट के माध्यम से परिणाम प्राप्त करता है या उन्हें webhook के माध्यम से प्राप्त करता है।

परिणाम ऑब्जेक्ट में ऑपरेटर का प्रस्तुत प्रमाण (कार्य प्रकार के आधार पर फोटो 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: रीयल-टाइम इवेंट्स के लिए Webhooks सेट करना

जबकि पोलिंग सरल एकीकरण के लिए काम करती है, उत्पादन प्रणालियों को webhooks के माध्यम से रीयल-टाइम ईवेंट सूचनाओं से लाभ होता है। जब भी कार्य की स्थिति बदलती है, HumanOps आपके कॉन्फ़िगर किए गए एंडपॉइंट पर HMAC-हस्ताक्षरित webhook पेलोड भेजता है। ईवेंट में शामिल हैं: task.estimate_received (एक ऑपरेटर ने अनुमान प्रस्तुत किया), task.started (एक अनुमोदित ऑपरेटर ने काम शुरू किया), task.proof_submitted (ऑपरेटर ने प्रमाण अपलोड किया), task.verified (AI Guardian ने सत्यापन पूरा किया), task.completed (कार्य पूरी तरह से पूरा हुआ और भुगतान जारी किया गया), और task.expired (बिना पूर्णता के समय सीमा बीत गई)।

एक webhook एंडपॉइंट पंजीकृत करने के लिए, एजेंट कंसोल या API का उपयोग करें। प्रत्येक webhook डिलीवरी में एक X-HumanOps-Signature हेडर शामिल होता है जिसमें आपके webhook सीक्रेट और अनुरोध बॉडी से गणना किया गया HMAC-SHA256 हस्ताक्षर होता है। पेलोड को संसाधित करने से पहले हमेशा इस हस्ताक्षर को सत्यापित करें ताकि यह सुनिश्चित हो सके कि webhook वास्तव में 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');
});

Webhook डिलीवरी में एक्सपोनेंशियल बैकऑफ़ के साथ पुनः प्रयास तर्क शामिल है। यदि आपका एंडपॉइंट गैर-2xx स्थिति कोड लौटाता है या टाइम आउट (10-सेकंड की सीमा) हो जाता है, तो HumanOps बढ़ती देरी के साथ पांच बार तक डिलीवरी का पुनः प्रयास करता है। यह सुनिश्चित करता है कि क्षणिक नेटवर्क समस्याएं छूटे हुए ईवेंट का कारण न बनें। महत्वपूर्ण वर्कफ़्लो के लिए, सुरक्षा जाल के रूप में समय-समय पर पोलिंग के साथ webhooks को संयोजित करें।

उन्नत एकीकरण पैटर्न

बैच कार्य निर्माण

उन एजेंटों के लिए जिन्हें एक साथ कई कार्य पोस्ट करने की आवश्यकता होती है, जैसे कि 50 स्टोर स्थानों की जाँच करने वाला रिटेल ऑडिट एजेंट, एक ही अनुरोध में कई कार्य बनाने के लिए बैच एंडपॉइंट का उपयोग करें। यह व्यक्तिगत निर्माण कॉल की तुलना में अधिक कुशल है और पूरे बैच के लिए परमाणु एस्क्रो आवंटन सुनिश्चित करता है।

सशर्त अनुमोदन श्रृंखला

कार्य परिणामों को जोड़कर परिष्कृत वर्कफ़्लो बनाएं। आपका एजेंट एक प्रारंभिक सत्यापन कार्य पोस्ट करता है। परिणाम के आधार पर, यह सशर्त रूप से अनुवर्ती कार्य पोस्ट करता है। उदाहरण के लिए: किसी संपत्ति की तस्वीर लेने के लिए एक कार्य पोस्ट करें, फिर यदि तस्वीरें क्षति प्रकट करती हैं, तो उच्च इनाम और T3 ऑपरेटर आवश्यकता के साथ उसी स्थान के लिए स्वचालित रूप से एक विस्तृत निरीक्षण कार्य पोस्ट करें।

स्मार्ट पुनः प्रयास तर्क

जब कोई कार्य क्लेम किए बिना समाप्त हो जाता है, तो आपका एजेंट स्वचालित रूप से इसे समायोजित मापदंडों के साथ फिर से पोस्ट कर सकता है: ऑपरेटरों को आकर्षित करने के लिए उच्च इनाम, व्यापक स्थान त्रिज्या, या विस्तारित समय सीमा। HumanOps SDK समाप्त हो चुके कार्यों को क्लोन करने और समायोजित करने के लिए सुविधा के तरीके प्रदान करता है। अधिकतम पुनः प्रयास सीमा निर्धारित करने के लिए कार्य मेटाडेटा में पुनः प्रयास गणना को ट्रैक करें और यदि स्वचालित पुनः प्रयास समाप्त हो जाते हैं तो मैन्युअल हैंडलिंग पर एस्केलेट करें।

आज ही बनाना शुरू करें

HumanOps API आपके AI एजेंट को सत्यापित मानव ऑपरेटरों के माध्यम से भौतिक दुनिया के साथ बातचीत करने की क्षमता देता है। चाहे आपको तस्वीरें लेने की आवश्यकता हो, डिलीवरी सत्यापित करनी हो, निरीक्षण करना हो, या कोई अन्य कार्य जिसमें मानव उपस्थिति की आवश्यकता हो, API इसे संभव बनाने के लिए एक विश्वसनीय, सुरक्षित और स्केलेबल तरीका प्रदान करता है।

बिना किसी लागत के अपने एकीकरण को मान्य करने के लिए परीक्षण मोड के साथ शुरू करें। TypeScript SDK और Python SDK दोनों आउट ऑफ द बॉक्स परीक्षण मोड का समर्थन करते हैं। जब आप उत्पादन के लिए तैयार हों, तो अपनी API कुंजी बदलें और आपका एजेंट लाइव है। पूर्ण API संदर्भ, इंटरैक्टिव उदाहरण और अतिरिक्त ट्यूटोरियल HumanOps डेवलपर दस्तावेज़ में उपलब्ध हैं।

आपके AI एजेंट को स्क्रीन के माध्यम से वह क्या कर सकता है, इस तक सीमित रहने की आवश्यकता नहीं है। HumanOps के साथ, यह वास्तविक दुनिया में अपने हाथ, आंख और पैर बनने के लिए सत्यापित मनुष्यों को काम पर रख सकता है। आज ही AI एजेंटों की अगली पीढ़ी बनाना शुरू करें।