SDK Đại lý OpenAI + Scrapeless: Công cụ Web cho Đại lý của bạn qua MCP

Tóm tắt:

• SDK OpenAI Agents kết nối với Máy chủ MCP Scrapeless thông qua một đối tượng, MCPServerStreamableHttp, mang theo điểm đầu cuối và tiêu đề x-api-token.
• await server.list_tools() trả về tất cả 21 công cụ — scrape_markdown, scrape_html, google_search, google_trends, scrape_screenshot, và một bộ 16 công cụ browser_* — chỉ với khóa Scrapeless được thiết lập.
• Không giống như các khung công tác chuyển đổi công cụ MCP thành các đối tượng độc lập, SDK giữ cho máy chủ là một kết nối hạng nhất: bạn đưa toàn bộ server cho tác nhân, và nó gọi list_tools và call_tool cho bạn.
• Bạn có thể gọi bất kỳ công cụ nào trực tiếp với await server.call_tool("scrape_markdown", {"url": ...}) trước khi một tác nhân tham gia — không cần khóa mô hình để tải hoặc gọi công cụ.
• Chỉ Runner.run cần một khóa nhà cung cấp mô hình, vì đó là bước mà mô hình quyết định công cụ nào được gọi.
• Bắt đầu với gói miễn phí của Scrapeless và cung cấp cho các tác nhân SDK OpenAI Agents của bạn những công cụ web thực sự.

SDK OpenAI Agents là khung nhẹ của OpenAI để xây dựng các ứng dụng tác nhân trong Python, và một tác nhân trong đó chỉ hữu ích bằng các công cụ bạn cung cấp cho nó. Không có gì trong cài đặt cơ sở tiếp cận web trực tiếp. Giao thức Ngữ cảnh Mô hình khắc phục điều đó: chỉ định SDK vào một máy chủ MCP và mọi công cụ mà máy chủ đó cung cấp đều có thể được tác nhân của bạn gọi thông qua cùng một giao diện như một công cụ hàm viết tay.

Hướng dẫn này kết nối SDK với Máy chủ MCP Scrapeless, liệt kê 21 công cụ của nó, gọi một công cụ thực sự, và sau đó gắn toàn bộ máy chủ vào một Agent — được xác nhận so với điểm đầu cuối 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 sinh tác nhân, và bài viết này đánh dấu chính xác nơi dòng đó ngồi.

Những gì Máy chủ MCP Scrapeless cung cấp cho một tác nhân

Máy chủ MCP Scrapeless cung cấp các công cụ web-scraping và trình duyệt mà một tác nhân có thể gọi trực tiếp, vì vậy lớp scraping không phải là thứ bạn xây dựng hoặc lưu trữ. Một kết nối 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ộ 16 công cụ browser_* điều khiển một trình duyệt đám mây thông qua các cú nhấp chuột, đánh máy, cuộn, và chờ.

Các công cụ browser_* chạy trê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 những gì thực sự được hiển thị mà không cần trình duyệt trên máy của bạn. Nếu bạn muốn máy chủ giống nhau được kết nối vào một ngăn xếp khác, hướng dẫn LangChain + Scrapeless MCP đề cập đến phần đó, và MCP là gì giải thích về giao thức này.

Các yêu cầu

• Python 3.10 trở lên.
• Một khóa API Scrapeless từ bảng điều khiển, xuất ra dưới dạng SCRAPELESS_API_KEY.
• Một khóa nhà cung cấp mô hình như OPENAI_API_KEY chỉ cho cuộc chạy của tác nhân. Việc tải và gọi các công cụ không cần một cái nào.

Cài đặt

Cài đặt SDK. Khách hàng MCP được cung cấp bên trong nó, vì vậy không cần thêm một phần riêng biệt.

pip install "openai-agents==0.18.3"

Đặt khóa Scrapeless của bạn trong shell, và giữ nguyên placeholder bên ngoài mã nguồn của bạn.

export SCRAPELESS_API_KEY="sk_your_key_here"

Kết nối và tải các công cụ

MCPServerStreamableHttp nhận một dict params với điểm đầu cuối và các tiêu đề, và nó là một quản lý ngữ cảnh asynchronous, vì vậy kết nối mở và đóng xung quanh một khối with. list_tools thực hiện việc bắt tay và trả về các công cụ của máy chủ.

import asyncio
import os

from agents.mcp import MCPServerStreamableHttp


async def main() -> None:
    params = {
        "url": "https://api.scrapeless.com/mcp",
        "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    }
    async with MCPServerStreamableHttp(
        params=params, name="scrapeless", client_session_timeout_seconds=60
    ) as server:
        tools = await server.list_tools()
        names = sorted(tool.name for tool in tools)
        print("số lượng công cụ:", len(names))
        print("công cụ:", ", ".join(names))


asyncio.run(main())

Máy chủ trực tiếp trả về 21 công cụ, được tải với chỉ khóa Scrapeless được thiết lập.

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

Lớp vận chuyển và lớp thông điệp tuân theo đặc tả Giao thức Ngữ cảnh Mô hình, mà dựa trên đặc tả JSON-RPC 2.0. SDK cũng cung cấp MCPServerStdio cho một máy chủ quy trình con địa phương; máy chủ Scrapeless là một điểm cuối HTTP được lưu trữ, vì vậy lớp HTTP có thể stream là lớp phù hợp trong trường hợp này.

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

Trước khi một tác nhân tồn tại, bạn có thể gọi bất kỳ công cụ nào trên máy chủ một mình. call_tool lấy tên công cụ và một từ điển đối số và trả về một CallToolResult mà content là một danh sách các khối; văn bản nằm trong các khối văn bản.

import asyncio
import os

from agents.mcp import MCPServerStreamableHttp


async def main() -> None:
    params = {
        "url": "https://api.scrapeless.com/mcp",
        "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    }
    async with MCPServerStreamableHttp(
        params=params, name="scrapeless", client_session_timeout_seconds=60
    ) as server:
        result = await server.call_tool("scrape_markdown", {"url": "https://quotes.toscrape.com/"})
        text = "".join(block.text for block in result.content if block.type == "text")
        print("ký tự markdown:", len(text))
        print("có chứa một câu trích dẫn:", "Einstein" in text)


asyncio.run(main())

Cuộc gọi trả về trang dưới dạng Markdown, và kiểm tra nội dung xác nhận văn bản thực đã được trả về.

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

Đó là hình dạng mà một tác nhân nhận được từ cùng một công cụ: nội dung trang mà nó có thể lý luận. Tài liệu Tài liệu SDK MCP của OpenAI Agents đề cập đến list_tools, call_tool, và tùy chọn cache_tools_list mà bỏ qua các cuộc bắt tay lặp lại khi tập hợp công cụ ổn định.

Gửi các công cụ cho một tác nhân

Tại đây, SDK khác với các khung công cụ-adapter. Bạn không chuyển đổi các công cụ và gửi một danh sách; bạn gửi toàn bộ server cho tham số mcp_servers của tác nhân, và tác nhân gọi list_tools và call_tool trên nó trong quá trình chạy. Đây là bước cần một chìa khóa nhà cung cấp mô hình.

Lưu ý: Runner.run cần một chìa khóa nhà cung cấp mô hình như OPENAI_API_KEY, điều này chưa được thiết lập ở đây. Việc tải 21 công cụ và cuộc gọi trực tiếp scrape_markdown ở trên chạy mà không cần nó. Khối này được hiển thị với hình dạng chính xác của nó; chỉ cần việc đi vòng mô hình là một khoảng cách cần thiết.

import asyncio
import os

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp


async def main() -> None:
    params = {
        "url": "https://api.scrapeless.com/mcp",
        "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    }
    async with MCPServerStreamableHttp(
        params=params, name="scrapeless", client_session_timeout_seconds=60
    ) as server:
        agent = Agent(
            name="web_agent",
            instructions="Sử dụng các công cụ Scrapeless để lấy và đọc các trang.",
            mcp_servers=[server],
        )
        result = await Runner.run(
            agent,
            "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 với các tác giả.",
        )
        print(result.final_output)


asyncio.run(main())

Tại thời gian chạy, mô hình đọc nhiệm vụ, gọi scrape_markdown với URL, nhận được Markdown mà cuộc gọi trực tiếp đã trả về, và viết câu trả lời. Các công cụ là như nhau theo cả hai cách — thành phần mới duy nhất là mô hình quyết định thời điểm gọi chúng.

Kết luận

SDK OpenAI Agents cộng với Máy chủ Scrapeless MCP là một con đường ngắn từ một tác nhân trần trụi đến một tác nhân có khả năng đọc web trực tiếp. Một đối tượng MCPServerStreamableHttp mở kết nối, list_tools trả về tất cả 21 công cụ, call_tool chứng minh một công cụ hoạt động, và một tham số duy nhất mcp_servers=[server] đưa tập hợp đến tác nhân. Chỉ bước tạo ra mới cần một chìa khóa mô hình, vì vậy bạn có thể kết nối và thử nghiệm toàn bộ bề mặt công cụ trước. Bắt đầu từ các kịch bản ở trên, xác định các công cụ theo yêu cầu của nhiệm vụ, và để cho mô hình điều khiển.

Tạo một tài khoản Scrapeless miễn phí để lấy chìa khóa API, và kiểm tra giá của Scrapeless khi bạn lập kế hoạch cho một tác nhân định kỳ.

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

H: SDK OpenAI Agents có cần một chìa khóa mô hình để tải các công cụ MCP không?

Không. MCPServerStreamableHttp thực hiện cuộc bắt tay và list_tools trả về các công cụ chỉ với chìa khóa API Scrapeless được thiết lập, và call_tool trực tiếp gọi bất kỳ công cụ nào trong số đó. Một chìa khóa nhà cung cấp mô hình chỉ yêu cầu khi bạn truyền máy chủ cho một Agent và gọi Runner.run, bởi vì đó là khi mô hình quyết định công cụ nào để gọi.
H: Làm thế nào để tôi gọi một công cụ MCP mà không cần xây dựng một tác nhân?

Mở máy chủ như một trình quản lý ngữ cảnh bất đồng bộ và gọi await server.call_tool(name, arguments). Nó trả về một CallToolResult mà nội dung của nó là một danh sách các khối; đọc văn bản từ các khối văn bản. Đây là cách nhanh nhất để xác nhận kết nối và kiểm tra đầu ra của một công cụ trước khi bất kỳ mô hình nào được tham gia.

H: Tại sao lại truyền máy chủ thay vì một danh sách các công cụ?

SDK giữ máy chủ MCP như một kết nối trực tiếp và truy vấn nó trong suốt quá trình chạy, vì vậy bạn gán nó với mcp_servers=[server] thay vì chuyển đổi từng công cụ. Nếu bộ công cụ ổn định, hãy đặt cache_tools_list=True trên máy chủ để nó không thực hiện lại quá trình bắt tay ở mỗi lượt.

H: Tôi có thể kết nối với một máy chủ MCP cục bộ thay thế không?

Có. Thay thế MCPServerStreamableHttp bằng MCPServerStdio và cung cấp lệnh khởi động máy chủ cục bộ của bạn, sau đó truyền nó cho tác nhân theo cách tương tự. Máy chủ MCP không có scrapeless là một điểm cuối HTTP được lưu trữ, vì vậy hướng dẫn này sử dụng lớp HTTP có thể phát.

H: Việc lấy dữ liệu thông qua các công cụ có bị ràng buộc bởi các quy tắc của đối tượng không?

Có. Các công cụ lấy các trang công khai, và bạn vẫn chịu trách nhiệm tuân thủ các điều khoản của từng đối tượng và các chỉ thị của Giao thức Loại trừ Robots. Giữ cho khối lượng có giới hạn, dữ liệu công khai, và tác nhân chỉ được giới hạn trong các công cụ mà nhiệm vụ thực sự cần.