पायडांटिक एआई + स्क्रेपलेस: अपने एजेंट को एमसीपी के माध्यम से लाइव वेब टूल्स दें

संक्षेप में:

• Pydantic AI Scrapeless MCP सर्वर से स्ट्रीम करने योग्य HTTP पर कनेक्ट करता है और एक एजेंट को scrape_markdown से लेकर एक पूर्ण ब्राउज़र-स्वचालन सेट तक 21 लाइव वेब टूल्स प्रदान करता है।
• कनेक्शन pydantic_ai.mcp से तीन वर्गों का उपयोग करता है: एक StreamableHttpTransport, एक FastMCPClient, और एक MCPToolset जिसे आप एक Agent से संलग्न करते हैं।
• हैंडशेक, टूल सूची, और एक वास्तविक scrape_markdown कॉल बिना मॉडल-प्रदाता कुंजी के चलती है; केवल अंतिम agent.run निर्माण के लिए एक की आवश्यकता होती है।
• defer_model_check=True एजेंट को एक मॉडल कुंजी मौजूद होने से पहले निर्माण करने की अनुमति देता है, ताकि आप पहले टूलसेट को वायर और निरीक्षण कर सकें।
• एक scrape_markdown कॉल लक्षित पृष्ठ को साफ Markdown के रूप में लौटाती है, जिसे संदर्भ के रूप में मॉडल को वापस देने के लिए तैयार किया जाता है।
• Scrapeless मुफ्त योजना पर शुरू करें और अपने पहले एजेंट को कनेक्ट करें।

Pydantic AI एक एजेंट को संरचना देता है: प्रकारित आउटपुट, मान्य टूल तर्क, और टूल्स को संयोजित करने का एक साफ तरीका। जो चीज़ यह एजेंट को नहीं देती, वह लाइव वेब तक पहुंचने का एक तरीका है। यही अंतर मॉडल कंटेक्स्ट प्रोटोकॉल द्वारा बंद किया जाता है। Pydantic AI को एक MCP सर्वर पर इंगित करें और उस सर्वर द्वारा प्रवाहित प्रत्येक टूल एक टूल बन जाता है जिसे आपका एजेंट कॉल कर सकता है, तर्क स्कीमा को उसी तरह मान्य किया जाता है जैसे आपके बाकी Pydantic AI कोड को।

यह गाइड Pydantic AI को Scrapeless MCP सर्वर से जोड़ती है, उन टूल्स की सूची बनाती है जो यह प्रदान करता है, एक का वास्तविक कॉल करती है, और पूरे सेट को एक Agent से संलग्न करती है — सभी को लाइव सर्वर के खिलाफ सत्यापित किया गया। एकमात्र कदम जिसे मॉडल-प्रदाता कुंजी की आवश्यकता होती है, वह अंतिम पीढ़ी कॉल है, और यह पोस्ट स्पष्ट है कि वह रेखा कहाँ गिरती है।

Scrapeless MCP क्यों

Scrapeless MCP सर्वर वेब-सक्रैपिंग और ब्राउज़र टूल्स को उजागर करता है जिन्हें एक एजेंट सीधे कॉल कर सकता है, इसलिए आप खुद से स्क्रैपिंग परत का निर्माण या होस्ट नहीं करते। एकल कनेक्शन 21 टूल्स की सेवा करता है: पृष्ठ सामग्री के लिए scrape_markdown और scrape_html, खोज डेटा के लिए google_search और google_trends, कैप्चर के लिए scrape_screenshot, और क्लिक, टाइप, स्क्रॉल और नेविगेशन के लिए एक पूर्ण browser_* सेट जो एक क्लाउड ब्राउज़र को चलााता है। Scrapeless MCP Server पोस्ट सर्वर के बारे में है; यह गाइड इसे Pydantic AI में वायर्ड करने के बारे में है।

क्योंकि टूल्स Scrapeless इन्फ्रास्ट्रक्चर पर चलते हैं, एजेंट बिना स्थानीय ब्राउज़र या प्रॉक्सी पूल के प्रस्तुत पृष्ठ और खोज परिणाम प्राप्त करता है। browser_* टूल्स Scrapeless क्लाउड ब्राउज़र को संचालित करते हैं, ताकि एक एजेंट एक इंटरएक्टिव पृष्ठ पर नेविगेट कर सके और जो प्रस्तुत किया जाता है उसे पढ़ सके।

पूर्वापेक्षाएँ

• Python 3.10 या उसके बाद का संस्करण।
• डैशबोर्ड से एक Scrapeless API कुंजी, जो SCRAPELESS_API_KEY के रूप में निर्यात की जाती है।
• एक मॉडल-प्रदाता कुंजी (जैसे OPENAI_API_KEY) केवल अंतिम जनन चरण के लिए। हैंडशेक, टूल सूची, और टूल कॉल्स को इसकी आवश्यकता नहीं होती है।

स्थापित करें

Scrapeless MCP अतिरिक्त के साथ Pydantic AI स्थापित करें, जो MCP क्लाइंट कक्षाएँ खींचता है।

pip install "pydantic-ai-slim[mcp]"

शेल में अपनी Scrapeless कुंजी सेट करें। वास्तविक कुंजी का उपयोग रन समय पर करें और अपने स्रोत से प्लेसहोल्डर को बाहर रखें।

export SCRAPELESS_API_KEY="sk_your_key_here"

कनेक्ट और टूल्स की सूची बनाएं

कनेक्शन तीन वस्तुएं हैं। एक StreamableHttpTransport एंडपॉइंट का नाम देता है और x-api-token हेडर में API कुंजी ले जाता है, एक FastMCPClient उस ट्रांसपोर्ट के जरिए प्रोटोकॉल बोलता है, और एक MCPToolset क्लाइंट को लपेटता है ताकि Pydantic AI इसका उपयोग कर सके। टूलसेट के असिंक्रोनस संदर्भ में प्रवेश करना हैंडशेक चलाता है; list_tools सर्वर द्वारा प्रदान की जाने वाली वस्तुओं को लौटाता है।

import asyncio
import os

from pydantic_ai.mcp import FastMCPClient, MCPToolset, StreamableHttpTransport

transport = StreamableHttpTransport(
    url="https://api.scrapeless.com/mcp",
    headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
)
scrapeless = MCPToolset(FastMCPClient(transport))


async def main() -> None:
    async with scrapeless:
        tools = await scrapeless.list_tools()
        names = sorted(t.name for t in tools)
        print("tool count:", len(names))
        print("tools:", ", ".join(names))


asyncio.run(main())

लाइव सर्वर 21 टूल्स लौटाता है, और यहाँ पहुँचने के लिए कोई मॉडल-प्रदाता कुंजी सेट नहीं की गई थी।

tool count: 21
tools: browser_click, browser_close, browser_create, browser_get_html, browser_get_text, browser_go_back, browser_go_forward, browser_goto, browser_press_key, browser_screenshot, browser_scroll, browser_scroll_to, browser_snapshot, browser_type, browser_wait, browser_wait_for, google_search, google_trends, scrape_html, scrape_markdown, scrape_screenshot

The tool नाम सपाट हैं, बिना सर्वर प्रीफिक्स के, इसलिए scrape_markdown को ठीक उसी नाम से संबोधित किया जा सकता है। परिवहन और संदेश स्तर मॉडल संदर्भ प्रोटोकॉल विशिष्टता का पालन करते हैं, जो स्वयं JSON-RPC 2.0 विशिष्टता पर निर्भर है।

सीधे एक टूल कॉल करें

एजेंट को टूल सौंपने से पहले, एक को स्वयं कॉल करें यह देखने के लिए कि यह क्या लौटाता है। direct_call_tool एक टूल को नाम और उसके तर्कों के साथ कॉल करता है, जो यह पुष्टि करने का सबसे तेज़ तरीका है कि एक टूल काम करता है और इसके आउटपुट का निरीक्षण करना।

import asyncio
import os

from pydantic_ai.mcp import FastMCPClient, MCPToolset, StreamableHttpTransport

transport = StreamableHttpTransport(
    url="https://api.scrapeless.com/mcp",
    headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
)
scrapeless = MCPToolset(FastMCPClient(transport))


async def main() -> None:
    async with scrapeless:
        result = await scrapeless.direct_call_tool("scrape_markdown", {"url": "https://quotes.toscrape.com/"})
        markdown = result if isinstance(result, str) else str(result)
        print("markdown characters:", len(markdown))
        print("contains a quote:", "The world as we have created it" in markdown)


asyncio.run(main())

कॉल पृष्ठ को मार्कडाउन के रूप में लौटाता है, और सामग्री जांच पुष्टि करती है कि लक्षित पृष्ठ से एक वास्तविक उद्धरण मौजूद है।

markdown characters: 4308
contains a quote: True

यह वह रूप है जो आपका एजेंट प्राप्त करता है: साफ मार्कडाउन जिसे वह तर्क कर सकता है, रॉ HTML के बजाय जिसे उसे स्ट्रिप करना होता है। Pydantic AI MCP क्लाइंट दस्तावेज़ीकरण टूलसेट विधियों को पूरी तरह से कवर करता है।

एजेंट को टूल संलग्न करें

संलग्न करना एक तर्क है: toolsets में Agent को टूलसेट पास करें। क्योंकि सामान्य Agent निर्माण तुरंत मॉडल को मान्य करता है, defer_model_check=True इसे एक मॉडल कुंजी सेट होने से पहले बनाने की अनुमति देता है, ताकि आप पहले टूलसेट को वायर और निरीक्षण कर सकें।

import asyncio
import os

from pydantic_ai import Agent
from pydantic_ai.mcp import FastMCPClient, MCPToolset, StreamableHttpTransport

transport = StreamableHttpTransport(
    url="https://api.scrapeless.com/mcp",
    headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
)
scrapeless = MCPToolset(FastMCPClient(transport))

# defer_model_check एजेंट को मॉडल कुंजी सेट होने से पहले निर्माण करने की अनुमति देता है,
# ताकि टूलसेट को पहले वायर और निरीक्षण किया जा सके।
agent = Agent("openai:gpt-4o", toolsets=[scrapeless], defer_model_check=True)


async def main() -> None:
    async with scrapeless:
        names = sorted(t.name for t in await scrapeless.list_tools())
    web = [n for n in names if n.startswith(("scrape_", "google_"))]
    print("एजेंट को", len(names), "Scrapeless टूल्स से वायर किया गया")
    print("वेब टूल्स:", web)


asyncio.run(main())

अब एजेंट हर Scrapeless टूल को ले जाता है, और वेब-स्क्रैपिंग उपसेट वही हिस्सा है जिसे अधिकांश ट्यूटोरियल पहले पहुंचते हैं।

एजेंट को 21 Scrapeless टूल्स से वायर किया गया
वेब टूल्स: ['google_search', 'google_trends', 'scrape_html', 'scrape_markdown', 'scrape_screenshot']

एजेंट को केवल कुछ टूल देने के लिए, MCPToolset filtered और renamed का उपयोग करता है, ताकि आप एजेंट को केवल scrape_markdown और google_search तक सीमित कर सकें, न कि पूरे ब्राउज़र सेट तक।

एक प्रॉम्प्ट चलाएँ

टूलसेट संलग्न होने के साथ, एजेंट तय करता है कि कब एक टूल कॉल करना है। यह एकमात्र चरण है जिसे एक मॉडल-प्रदाता कुंजी की आवश्यकता होती है।

नोट: agent.run को एक मॉडल-प्रदाता कुंजी की आवश्यकता होती है जैसे कि OPENAI_API_KEY। उपरोक्त सब कुछ - हैंडशेक, 21-टूल की सूची, scrape_markdown कॉल, और संलग्नता - इसके बिना चलता है। केवल यह जनरेशन कॉल एक पूर्वापेक्षा अंतर है; इसे यहां ठीक उसके आकार के साथ दिखाया गया है, न कि एक कैप्चर किए गए परिणाम के रूप में।

async def run_prompt() -> None:
    async with agent:
        result = await agent.run(
            "scrape_markdown का उपयोग करें ताकि https://quotes.toscrape.com/ को लाया जा सके "
            "और पहले तीन उद्धरणों को उनके लेखकों के साथ सूचीबद्ध करें।"
        )
    print(result.output)


asyncio.run(run_prompt())

चलाने के समय मॉडल प्रॉम्प्ट पढ़ता है, URL के साथ scrape_markdown कॉल करता है, पहले की कॉल में पहले ही प्रदर्शित मार्कडाउन प्राप्त करता है, और उत्तर लिखता है। टूल लेयर समान है चाहे आप इसे सीधे कॉल करें या मॉडल को इसे कॉल करने दें।

निष्कर्ष

Pydantic AI प्लस Scrapeless MCP सर्वर एक नंगे एजेंट से एक ऐसे एजेंट के लिए एक छोटा रास्ता है जो लाइव वेब पढ़ता है। तीन कक्षाएं कनेक्शन बनाती हैं, list_tools 21 टूल दिखाती है, direct_call_tool यह प्रमाणित करता है कि एक काम करता है, और एक toolsets तर्क उन्हें सभी संलग्न करता है। केवल निर्माण चरण को एक मॉडल कुंजी की आवश्यकता होती है, जो संपूर्ण एकीकरण को खोजने योग्य बनाता है इससे पहले कि आप एक प्रदाता को प्रतिबद्ध करें। ऊपर दिये गए स्क्रिप्ट से शुरू करें, टूलसेट को उन टूल्स तक सीमित करें जिनकी आपके एजेंट को आवश्यकता है, और मॉडल को बाकी करने दें।
एक मुफ्त Scrapeless खाता बनाएं एक API कुंजी प्राप्त करने के लिए, और जब आप एक आवर्ती एजेंट की योजना बनाते हैं तो Scrapeless मूल्य निर्धारण देखें।

FAQ

प्रश्न: क्या Pydantic AI को MCP उपकरणों को सूचीबद्ध करने के लिए एक मॉडल कुंजी की आवश्यकता है?

नहीं। हैंडशेक, list_tools, और direct_call_tool सभी केवल Scrapeless API कुंजी के साथ चलते हैं। एक मॉडल-प्रदाता कुंजी केवल agent.run के लिए आवश्यक होती है, जब मॉडल स्वयं यह तय करता है कि कौन से उपकरणों को कॉल करना है, इसलिए आप पूरे उपकरण सतह की खोज और परीक्षण कर सकते हैं इससे पहले कि आप एक प्रदाता को प्रतिबद्ध करें।

प्रश्न: FastMCPClient और MCPToolset में क्या अंतर है?

FastMCPClient MCP प्रोटोकॉल को एक परिवहन के माध्यम से बोलता है और list_tools जैसी निम्न-स्तरीय कार्यविधियों को उजागर करता है। MCPToolset उस क्लाइंट को लपेटता है ताकि Pydantic AI सर्वर के उपकरणों को एजेंट उपकरणों के रूप में मान सके, और यह filtered और renamed जैसी उपकरण सेट सुविधाएँ जोड़ता है। आप Agent से क्लाइंट नहीं, बल्कि MCPToolset को जोड़ते हैं।

प्रश्न: मैं HTTP के बजाय stdio MCP सर्वर से कैसे कनेक्ट करूँ?

परिवहन को बदलें। StreamableHttpTransport के बजाय सर्वर कमांड के साथ StdioTransport का उपयोग करें, फिर इसे उसी FastMCPClient और MCPToolset में लपेटें। Scrapeless MCP सर्वर एक होस्टेड HTTP अंतिम बिंदु है, इसलिए यह गाइड StreamableHttpTransport का उपयोग करता है।

प्रश्न: एजेंट का निर्माण करते समय defer_model_check का उपयोग क्यों करें?

Agent का निर्माण सामान्यतः तुरंत मॉडल प्रदाता का सत्यापन करता है, जो विफल हो जाता है यदि कोई कुंजी सेट नहीं की गई है। defer_model_check=True उस जांच को रन टाइम पर स्थगित कर देता है, ताकि आप एजेंट का निर्माण कर सकें, उपकरण सेट को कनेक्ट कर सकें, और उपलब्ध उपकरणों का परीक्षण कर सकें बिना किसी मॉडल कुंजी के।

प्रश्न: मैं एक एजेंट को केवल कुछ उपकरण कैसे दूं?

MCPToolset.filtered का उपयोग करके एक उपसमुच्चय खोलें, या renamed का उपयोग करके उपकरणों के दिखने के तरीके को बदलें। एक एजेंट को केवल scrape_markdown और google_search तक सीमित करना सभी 21 उपकरणों को सौंपने से अधिक सुरक्षित है जब कार्य केवल सामग्री और खोज की आवश्यकता हो।

प्रश्न: scrape_markdown क्या लौटाता है?

यह लक्षित पृष्ठ को Markdown के रूप में प्रस्तुत करता है, जो सत्यापित कॉल में उद्धरण पृष्ठ के लिए 4,308 वर्ण थे और पृष्ठ का असली पाठ शामिल था। Markdown एक मॉडल के लिए कच्चे HTML की तुलना में अधिक उचित है, इसलिए इसे पृष्ठ की सामग्री को प्रॉम्प्ट में वापस फीड देने के लिए एक अच्छा डिफ़ॉल्ट माना जाता है।

प्रश्न: क्या उपकरणों के माध्यम से स्क्रैपिंग लक्षित के नियमों द्वारा बाधित है?

हाँ। उपकरण सार्वजनिक पृष्ठों को लाते हैं, और आप प्रत्येक लक्षित के नियमों और उसके Robots Exclusion Protocol निर्देशों का सम्मान करने के लिए जिम्मेदार रहते हैं। वॉल्यूम को सीमित रखें और डेटा को सार्वजनिक रखें, और एजेंट को उन उपकरणों तक सीमित करें जिनकी कार्य को वास्तव में आवश्यकता है।