Pydantic AI + Scrapeless: Cung cấp cho đại lý của bạn công cụ web trực tiếp qua MCP

Tóm tắt:

• Pydantic AI kết nối với Máy chủ MCP Scrapeless qua HTTP có thể phát và cung cấp cho một tác nhân 21 công cụ web trực tiếp, từ scrape_markdown đến bộ tự động hóa trình duyệt hoàn chỉnh.
• Kết nối sử dụng ba lớp từ pydantic_ai.mcp: một StreamableHttpTransport, một FastMCPClient và một MCPToolset mà bạn gán cho một Agent.
• Bắt tay, danh sách công cụ và một lời gọi scrape_markdown thực tế đều chạy mà không cần khóa nhà cung cấp mô hình; chỉ cần việc tạo agent.run cuối cùng cần một khóa.
• defer_model_check=True cho phép Agent được xây dựng trước khi có khóa mô hình, vì vậy bạn có thể kết nối và kiểm tra bộ công cụ trước.
• Một lời gọi scrape_markdown trả về trang mục tiêu dưới dạng Markdown sạch, sẵn sàng để đưa trở lại cho mô hình như ngữ cảnh.
• Bắt đầu với gói miễn phí Scrapeless và kết nối tác nhân đầu tiên của bạn.

Pydantic AI cung cấp cho một tác nhân cấu trúc: đầu ra có kiểu, đối số công cụ được xác thực và cách rõ ràng để kết hợp các công cụ. Điều mà nó không cung cấp cho tác nhân là cách để truy cập web trực tiếp. Khoảng trống này chính là điều mà Giao thức Ngữ cảnh Mô hình kết nối. Hướng Pydantic AI vào một máy chủ MCP và mọi công cụ mà máy chủ đó cung cấp đều trở thành công cụ mà tác nhân của bạn có thể gọi, với các lược đồ đối số được xác thực giống như phần còn lại của mã Pydantic AI của bạn.

Hướng dẫn này kết nối Pydantic AI với Máy chủ MCP Scrapeless, liệt kê các công cụ mà nó phục vụ, gọi một cái thực sự, và gán toàn bộ tập hợp cho một Agent — tất cả được xác thực với máy chủ trực tiếp. Bước duy nhất cần một khóa nhà cung cấp mô hình là cuộc gọi tạo ở cuối, và bài viết này rõ ràng về nơi mà dòng đó kết thúc.

Tại sao là Scrapeless MCP

Máy chủ MCP Scrapeless cung cấp các công cụ scrapping web và trình duyệt mà một tác nhân có thể gọi trực tiếp, vì vậy bạn không cần xây dựng hoặc lưu trữ lớp scrapping cho riêng mình. Một kết nối duy nhất phục vụ 21 công cụ: scrape_markdown và scrape_html cho nội dung trang, google_search và google_trends cho dữ liệu tìm kiếm, scrape_screenshot cho các bản chụp, và một bộ browser_* hoàn chỉnh điều khiển một trình duyệt đám mây cho cú nhấp chuột, gõ, cuộn và điều hướng. Bài viết về Máy chủ MCP Scrapeless đề cập đến máy chủ này; hướng dẫn này đề cập đến cách kết nối nó với Pydantic AI.

Vì các công cụ chạy trên cơ sở hạ tầng Scrapeless, tác nhân nhận được các trang đã được hiển thị và kết quả tìm kiếm mà không cần trình duyệt cục bộ hoặc nhóm proxy. Các công cụ browser_* điều khiển trình duyệt đám mây Scrapeless, vì vậy một tác nhân có thể điều hướng một trang tương tác và đọc nội dung hiển thị.

Các yêu cầu tiên quyết

• Python 3.10 trở lên.
• Một khóa API Scrapeless từ bảng điều khiển, được xuất với tên SCRAPELESS_API_KEY.
• Một khóa nhà cung cấp mô hình (như OPENAI_API_KEY) chỉ cho bước tạo cuối cùng. Bắt tay, danh sách công cụ và các cuộc gọi công cụ không cần một khóa.

Cài đặt

Cài đặt Pydantic AI với tùy chọn MCP, điều này kéo theo các lớp khách hàng MCP.

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

Thiết lập khóa Scrapeless của bạn trong shell. Sử dụng khóa thực trong thời gian chạy và giữ chỗ đó ra khỏi mã nguồn của bạn.

export SCRAPELESS_API_KEY="sk_your_key_here"

Kết nối và liệt kê các công cụ

Kết nối là ba đối tượng. Một StreamableHttpTransport đặt tên cho điểm cuối và mang khóa API trong tiêu đề x-api-token, một FastMCPClient nói chuyện giao thức qua giao thông đó, và một MCPToolset gói khách hàng để Pydantic AI có thể sử dụng. Bước vào bối cảnh đồng bộ của bộ công cụ thực hiện bắt tay; list_tools trả về những gì máy chủ cung cấp.

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("số công cụ:", len(names))
        print("các công cụ:", ", ".join(names))


asyncio.run(main())

Máy chủ trực tiếp trả về 21 công cụ, và chưa có khóa nhà cung cấp mô hình nào được thiết lập để đạt được điều này.

số công cụ: 21
các công cụ: 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

Tên công cụ là phẳng, không có tiền tố máy chủ, vì vậy scrape_markdown có thể được gọi bằng chính cái tên đó. Lớp truyền tải và thông điệp tuân theo bản đặc tả Giao thức Ngữ cảnh Mô hình, mà bản thân nó dựa trên bản đặc tả JSON-RPC 2.0.

Gọi một Công cụ Trực tiếp

Trước khi giao công cụ cho một tác nhân, hãy tự gọi một công cụ để xem nó trả lại kết quả gì. direct_call_tool gọi một công cụ bằng tên với các đối số của nó, đây là cách nhanh nhất để xác nhận một công cụ hoạt động và kiểm tra đầu ra của nó.

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("ký tự markdown:", len(markdown))
        print("chứa một câu trích dẫn:", "Thế giới mà chúng ta đã tạo ra" in markdown)


asyncio.run(main())

Cuộc gọi trả lại trang dưới dạng Markdown, và kiểm tra nội dung xác nhận rằng một câu trích dẫn thực sự từ trang mục tiêu có mặt.

ký tự markdown: 4308
chứa một câu trích dẫn: True

Đây là hình dạng mà tác nhân của bạn nhận được: Markdown sạch mà nó có thể lý luận, thay vì HTML thô mà nó phải loại bỏ. Tài liệu hướng dẫn sử dụng Pydantic AI MCP client bao gồm đầy đủ các phương thức của bộ công cụ.

Gắn Công Cụ vào Tác Nhân

Việc gắn kèm là một đối số: truyền bộ công cụ đến Agent trong toolsets. Vì việc xây dựng một Agent bình thường xác thực mô hình ngay lập tức, defer_model_check=True cho phép nó xây dựng trước khi một khóa mô hình được thiết lập, vì vậy bạn có thể kết nối và kiểm tra bộ công cụ trước.

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 cho phép tác nhân xây dựng trước khi khóa mô hình được thiết lập,
# vì vậy bộ công cụ có thể được kết nối và kiểm tra trước.
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("tác nhân được kết nối với", len(names), "công cụ Scrapeless")
    print("công cụ web:", web)


asyncio.run(main())

Tác nhân giờ đây mang theo tất cả các công cụ Scrapeless, và tập hợp công cụ thu thập dữ liệu web là phần mà hầu hết các tài liệu hướng dẫn hướng tới đầu tiên.

tác nhân được kết nối với 21 công cụ Scrapeless
công cụ web: ['google_search', 'google_trends', 'scrape_html', 'scrape_markdown', 'scrape_screenshot']

Để giao cho tác nhân chỉ một vài công cụ thay vì tất cả 21, MCPToolset cung cấp filtered và renamed, vì vậy bạn có thể giới hạn tác nhân chỉ đến scrape_markdown và google_search thay vì toàn bộ bộ công cụ trình duyệt.

Chạy một Lời Nhắc

Với bộ công cụ được gắn, tác nhân quyết định khi nào gọi một công cụ. Đây là bước duy nhất cần có một khóa nhà cung cấp mô hình.

Lưu ý: agent.run cần một khóa nhà cung cấp mô hình như OPENAI_API_KEY. Mọi thứ ở trên — bắt tay, danh sách 21 công cụ, cuộc gọi scrape_markdown, và việc gắn kèm — đều hoạt động mà không cần nó. Chỉ có cuộc gọi tạo ra này là một bước cần có; nó được trình bày ở đây với hình dạng chính xác mà nó lấy, không phải như một kết quả đã được ghi lại.

async def run_prompt() -> None:
    async with agent:
        result = await agent.run(
            "Sử dụng scrape_markdown để lấy https://quotes.toscrape.com/ "
            "và liệt kê ba câu trích dẫn đầu tiên cùng với tác giả của chúng."
        )
    print(result.output)


asyncio.run(run_prompt())

Tại thời điểm chạy, mô hình đọc lời nhắc, gọi scrape_markdown với URL, nhận Markdown mà cuộc gọi trước đó đã chứng minh và viết câu trả lời. Lớp công cụ là giống nhau dù bạn gọi nó trực tiếp hay để mô hình gọi nó.

Kết Luận

Pydantic AI cộng với Máy chủ MCP Scrapeless là một con đường ngắn từ một tác nhân trống cho đến một tác nhân có thể đọc web trực tiếp. Ba lớp tạo nên kết nối, list_tools hiển thị 21 công cụ, direct_call_tool chứng minh một công cụ hoạt động, và một đối số toolsets gắn tất cả chúng lại với nhau. Chỉ có bước tạo ra cần một khóa mô hình, điều này giữ cho toàn bộ tích hợp có thể khám phá trước khi bạn cam kết một nhà cung cấp. Bắt đầu từ các kịch bản ở trên, giới hạn bộ công cụ đến những công cụ mà tác nhân của bạn cần, và để mô hình làm phần còn lại.
Đăng ký tài khoản Scrapeless miễn phí để nhận một API key, và kiểm tra giá cả của Scrapeless khi bạn lên kế hoạch cho một tác nhân định kỳ.

Câu hỏi thường gặp

H: Pydantic AI có cần một khóa mô hình để liệt kê các công cụ MCP không?

Không. Quy trình bắt tay, list_tools, và direct_call_tool đều chạy chỉ với API key của Scrapeless. Một khóa nhà cung cấp mô hình chỉ được yêu cầu cho agent.run, khi chính mô hình quyết định công cụ nào sẽ được gọi, vì vậy bạn có thể khám phá và kiểm tra toàn bộ bề mặt công cụ trước khi cam kết với một nhà cung cấp.

H: Sự khác biệt giữa FastMCPClient và MCPToolset là gì?

FastMCPClient giao tiếp với giao thức MCP qua một phương tiện vận chuyển và cung cấp các thao tác cấp thấp như list_tools. MCPToolset bao bọc khách hàng đó để Pydantic AI có thể xem công cụ của máy chủ như là các công cụ của tác nhân, và nó thêm vào các tính năng bộ công cụ như filtered và renamed. Bạn gắn MCPToolset, không phải khách hàng, vào một Agent.

H: Làm thế nào để tôi kết nối với một máy chủ MCP stdio thay vì HTTP?

Đổi phương tiện vận chuyển. Sử dụng StdioTransport với lệnh máy chủ thay vì StreamableHttpTransport với một URL, sau đó bao bọc nó trong cùng một FastMCPClient và MCPToolset. Máy chủ Scrapeless MCP là một điểm cuối HTTP được lưu trữ, vì vậy hướng dẫn này sử dụng StreamableHttpTransport.

H: Tại sao sử dụng defer_model_check khi xây dựng tác nhân?

Xây dựng một Agent thường ngay lập tức xác thực nhà cung cấp mô hình, điều này sẽ thất bại nếu không có khóa nào được cài đặt. defer_model_check=True hoãn việc kiểm tra đó cho đến thời gian chạy, vì vậy bạn có thể xây dựng tác nhân, kết nối bộ công cụ, và kiểm tra các công cụ có sẵn mà không cần có khóa mô hình.

H: Làm thế nào để tôi chỉ cung cấp cho một tác nhân một số công cụ?

Sử dụng MCPToolset.filtered để hiển thị một tập hợp con, hoặc renamed để thay đổi cách các công cụ xuất hiện với mô hình. Giới hạn một tác nhân chỉ vào scrape_markdown và google_search an toàn hơn là cung cấp tất cả 21 công cụ khi nhiệm vụ chỉ cần nội dung và tìm kiếm.

H: scrape_markdown trả về cái gì?

Nó trả về trang mục tiêu được trình bày dưới dạng Markdown, mà trong cuộc gọi đã được xác minh là 4.308 ký tự cho trang trích dẫn và chứa văn bản thực của trang. Markdown dễ cho một mô hình suy luận hơn so với HTML thô, vì vậy nó là một mặc định tốt để đưa nội dung trang trở lại vào một lời nhắc.

H: Việc thu thập thông tin qua các công cụ có bị ràng buộc bởi quy tắc của mục tiêu không?

Có. Các công cụ truy xuất các trang công khai, và bạn vẫn chịu trách nhiệm cho việc tôn trọng điều khoản của mỗi mục tiêu và các chỉ thị Giao thức loại trừ Robot. Hãy giữ khối lượng trong giới hạn và dữ liệu công khai, và giới hạn tác nhân vào các công cụ mà nhiệm vụ thực sự cần.