Tại sao keo dán dụng cụ đặt làm riêng lại không hiệu quả?

Các đại lý cần những công cụ web thực sự, chứ không phải các lớp bọc Python tùy chỉnh

Mỗi đội đều xây dựng cùng một bộ công cụ cơ bản: một công cụ Python cho mỗi nguồn thu thập dữ liệu, một kho lưu trữ phiên làm việc hoạt động không ổn định, và một trình điều phối tự phát triển thường mất bối cảnh sau mỗi lần gọi. Ba tuần sau, tác nhân hoạt động được một lần, gặp sự cố hai lần, và không ai còn nhớ proxy nào đã hết hạn. Chúng tôi cung cấp sẵn bốn thành phần cần thiết cho mỗi vòng lặp tác nhân — thông qua MCP, với một điểm cuối HTTP duy nhất.

Nếu trình thu thập dữ liệu của bạn từng bị hết thời gian chờ ở bước thứ ba của quá trình thu thập dữ liệu nhiều bước — thì bài viết này dành cho bạn.

Một công cụ Python tùy chỉnh cho từng nguồn

Vấn đề nằm ở chỗ: Mỗi tính năng mới của agent lại là một @tool trình trang trí: một cho Amazon, một cho eBay, một cho wiki của công ty. Sự thay đổi cấu trúc dữ liệu, sự lệch phiên bản và một kho lưu trữ công cụ mà không ai chịu trách nhiệm quản lý. Việc tích hợp một mô hình mới đồng nghĩa với việc phải triển khai lại các trình bao bọc từ đầu.

Cách Yozh Scraper khắc phục vấn đề này. Mỗi điểm cuối HTTP MCP localhost:8000/mcp tự động hiển thị mọi tính năng — scrape_page, scrape_batch, crawl, sessions, presets. Chỉ cần thêm một dòng vào cấu hình của Claude / Cursor / Cline là mô hình sẽ tự động phát hiện các công cụ trong quá trình chạy. Cùng một điểm cuối, cho mọi khách hàng.

Một endpoint MCP
Tự động phát hiện
Không cần glue code

Các lệnh gọi công cụ không có trạng thái sẽ mất bối cảnh đăng nhập

Vấn đề. Các lệnh gọi công cụ không lưu trạng thái — mỗi lệnh gọi đều khởi chạy một trình duyệt mới, xóa cookie và khiến bước xác thực hai yếu tố (2FA) thứ hai thất bại. Các tác nhân bị kẹt trong vòng lặp đăng nhập lại sẽ tiêu tốn hết các mã thông báo và từ bỏ sau lần thử lại thứ ba. Việc lưu trữ cookie thủ công rất dễ bị hỏng và thông tin bị rò rỉ giữa các lần chạy.

Cách Yozh Scraper khắc phục vấn đề này. Giao diện lập trình ứng dụng (API) phiên làm việc với một session_id mà tác nhân truyền giữa các lần gọi. Ngôn ngữ kịch bản đăng nhập (DSL) (goto / fill / click / wait) hoặc dán cookie đã xuất một lần — storageState tồn tại trong 24 giờ. Mỗi lần gọi công cụ tiếp theo sẽ tái sử dụng phiên làm việc, không cần xác thực lại.

session_id cố định
Đăng nhập khai báo
TTL 24h

Xác thực thủ công và cấu hình proxy trong mã đại lý

Vấn đề nằm ở chỗ: Mỗi tác nhân cuối cùng đều phải xử lý các khóa API, luân phiên proxy, mã quốc gia, số lần thử lại — những thiết lập hoàn toàn không liên quan đến nhiệm vụ của mô hình. Các thông tin bí mật bị rò rỉ vào các lời nhắc, tác nhân đưa ra những quyết định “sáng tạo” về số lần thử lại, và ngân sách dành cho proxy tăng vọt chỉ trong vòng một tuần.

Cách Yozh Scraper khắc phục vấn đề này. CYBERYOZH_API_KEY Trong mã đại lý .env — mã của agent không bao giờ tiếp xúc với thông tin đăng nhập. Khi proxy: {country: "us", type: "mobile"} trong lệnh gọi công cụ, Yozh sẽ xử lý việc luân phiên, nhận dạng và thử lại ở phía máy chủ. Trình đại lý vẫn tập trung vào việc suy luận.

Xác thực phía server
Proxy khai báo
Không secret trong prompt

Quá trình thu thập dữ liệu nhiều bước bên trong vòng lặp tác nhân

Vấn đề nằm ở chỗ: “Tìm tất cả các trang sản phẩm trên trang web này và trích xuất giá” chỉ là một ý định của người dùng — nhưng trong mã của tác nhân, điều này lại tương đương với 200 lần gọi công cụ, một hàng đợi, một lớp loại bỏ trùng lặp và việc phải liên tục theo dõi thời gian chờ. Mô hình này lãng phí một cửa sổ bối cảnh cho việc quản lý URL — điều mà nó lẽ ra không bao giờ nên phải làm.

Cách Yozh Scraper khắc phục vấn đề này. Yozh Crawler quét trang web từ phía máy chủ, truyền các URL đã phát hiện qua SSE và kết nối với trình trích xuất dữ liệu mỗi khi tìm thấy kết quả phù hợp. Trình trích xuất dữ liệu sẽ được kích hoạt crawl_and_scrape một lần, nhận được một luồng duy nhất chứa các kết quả được cấu trúc. Máy chủ duy trì hàng đợi, trong khi mô hình duy trì bối cảnh của nó.

Streaming qua SSE
Hàng đợi phía server
Một lệnh gọi tool

Cách thức hoạt động

Từ `docker compose up` đến các công cụ gọi điện cho đại lý — chỉ trong 3 bước

Một điểm cuối MCP, một dòng cấu hình trong ứng dụng khách của bạn, không cần mã kết nối. Quy trình này cũng áp dụng cho Claude Desktop, Cursor, Cline hoặc vòng lặp tác nhân của riêng bạn.

1 Khởi động điểm cuối MCP

Sao chép kho lưu trữ và docker compose up. Máy chủ MCP đang hoạt động tại localhost:8000/mcp — các công cụ thu thập dữ liệu, trình thu thập thông tin, phiên làm việc và cài đặt sẵn đều được tự động hiển thị dưới dạng các công cụ.

# one-time setup
git clone 
  github.com/CyberYozh-data/yozh-scraper
cd yozh-scraper
docker compose up -d

2 Kết nối nó với máy khách của bạn

Một dòng trong claude_desktop_config.json (hoặc tương đương với Cursor / Cline). Khởi động lại máy khách — các công cụ được tự động phát hiện, không cần các trình bao bọc riêng cho từng nguồn.

{
  "mcpServers": {
    "yozh": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

3 Hãy để các công cụ gọi điện cho đại lý

Mô hình này sẽ chọn công cụ, điền các tham số và nhận lại dữ liệu JSON có cấu trúc. Các phiên làm việc được duy trì qua các lần gọi. Các quá trình thu thập dữ liệu nhiều bước được truyền qua SSE.

// claude calls scrape_page autonomously
{
  "tool":   "scrape_page",
  "input":  {"url": "…",
              "preset": "amazon_product"},
  "result": { /* structured JSON */ }
}

Ví dụ trực tiếp

Lợi ích bạn nhận được — một mẫu thiết kế, phù hợp với mọi nền tảng thương mại điện tử

Hãy chọn một cài đặt sẵn để xem phản hồi trông như thế nào. Bộ trường có thể khác nhau tùy theo nguồn, nhưng cấu trúc yêu cầu là giống hệt nhau.

Công thức

Cách các đại lý kết nối hệ thống — mỗi cách chỉ trong 10 dòng

Ba cấu hình đại lý cụ thể, sẵn sàng để chèn vào. Từ các lệnh một dòng trên Claude Desktop đến một vòng lặp LangChain hoàn chỉnh — tất cả đều sử dụng cùng một điểm cuối MCP.

1 Công cụ nghiên cứu Claude Desktop

Kết nối Yozh với Claude Desktop một lần. Yêu cầu mô hình nghiên cứu một chủ đề — nó sẽ tự động scrape_page / crawl một cách tự động và tổng hợp câu trả lời.

# claude_desktop_config.json (~/Library/...)
{
  "mcpServers": {
    "yozh": {
      "type": "http",
      "url":  "http://localhost:8000/mcp"
    }
  }
}

# restart Claude · prompt:
# "compare ssd prices on amazon vs walmart"
# → claude calls scrape_page on each PDP

Truyền tải qua HTTP tự động phát hiện tool không cần glue code

2 Cursor Copilot với các công cụ web

Thêm cùng một máy chủ MCP vào Cursor — giờ đây, trình đại lý IDE của bạn có thể truy xuất tài liệu thời gian thực, kiểm tra giá cả của đối thủ cạnh tranh hoặc trích xuất câu trả lời từ Stack Overflow ngay trong khi nhập lời nhắc.

# .cursor/mcp.json (project root)
{
  "mcpServers": {
    "yozh": {
      "type": "http",
      "url":  "http://localhost:8000/mcp"
    }
  }
}

# prompt in Cmd+L composer:
# "fetch the latest pricing from acme.com/plans
#  and update PricingTable.tsx"

cấu hình theo project cùng một endpoint MCP gọi tool trong chat

3 Vòng lặp LangChain / Anthropic SDK

Trình đại lý Python thuần túy — SDK Anthropic với mcp_servers danh sách. Chỉ cần một URL HTTP, mô hình sẽ nhận được tất cả các công cụ Yozh. Hoạt động tương tự với bộ điều hợp MCP của LangChain.

# anthropic SDK · plain python
client = Anthropic()
resp   = client.messages.create(
  model="claude-sonnet-4-5",
  mcp_servers=[{
    "type": "url",
    "url":  "https://your-host/mcp"
  }],
  messages=[{
    "role": "user",
    "content": "crawl docs.x.com, summarize"
  }],
)

Streaming qua SSE tự động đa tool orchestrator của bạn

FAQ

Các câu hỏi thường gặp về MCP và tích hợp đại lý

Những khách hàng MCP nào được hỗ trợ?

Bất kỳ thành phần nào hỗ trợ giao thức Model Context Protocol (MCP) qua kênh truyền tải HTTP: Claude Desktop, Cursor, Cline, Continue, Zed, nút MCP của n8n, bộ điều hợp MCP của LangChain và tham số mcp_servers param. Điểm cuối tại localhost:8000/mcp là một URL duy nhất — bạn chỉ cần trỏ bất kỳ ứng dụng nào trong số đó đến đó. Không cần duy trì các trình bao bọc riêng cho từng ứng dụng khách hay các lớp trung gian stdio.

Các công cụ được đăng ký với tác nhân như thế nào?

Tự động phát hiện qua MCP. Khi máy khách kết nối với /mcp, máy chủ sẽ liệt kê tất cả các công cụ có sẵn kèm theo lược đồ JSON của chúng: scrape_page, scrape_batch, crawl, create_session, list_presets, generate_preset. Mô hình nhận diện chúng như các công cụ gốc trong quá trình chạy — không cần decorator, không cần định nghĩa lược đồ thủ công. Các tính năng mới từ phiên bản nguồn yozh-scraper sẽ tự động xuất hiện sau lần cập nhật tiếp theo.

Đại lý của tôi có thể phát trực tuyến quá trình thu thập dữ liệu nhiều bước không?

Đúng vậy — Yozh Crawler quét trang web ở phía máy chủ và truyền các URL được phát hiện qua SSE. Trình thu thập dữ liệu sẽ được kích hoạt crawl một lần, nhận được một luồng sự kiện duy nhất chứa các kết quả có cấu trúc ngay khi chúng đến. Mỗi lần thu thập dữ liệu hỗ trợ phạm vi (cùng miền / cùng máy chủ / danh sách cho phép), RPS theo miền và khả năng kết nối tùy chọn vào trình trích xuất dữ liệu để mỗi URL được tìm thấy sẽ được phân tích trước khi được đưa vào luồng. Hủy bằng DELETE /scrape/{id} — dừng mềm cho phép các trang đang được thu thập hoàn tất; dừng ép buộc là một cuộc gọi thứ hai.

Làm thế nào để các phiên làm việc được duy trì giữa các lần gọi công cụ?

API Sessions. Tạo một phiên duy nhất bằng DSL đăng nhập theo kiểu khai báo (goto / fill / click / wait) hoặc bằng cách dán các cookie đã xuất ra. Yozh lưu trữ cookie + Playwright storageState ở phía máy chủ và cung cấp cho bạn một ID phiên cố định session_id. Mỗi lần gọi công cụ tiếp theo truyền ID đó sẽ tái sử dụng cùng trạng thái trình duyệt — bao gồm các cổng thông tin được bảo vệ bằng xác thực hai yếu tố (2FA), LinkedIn và các hệ thống quản trị của đối tác. Thời gian tồn tại (TTL) mặc định là 24 giờ và có thể được làm mới. Trình đại lý không bao giờ tiếp xúc với thông tin đăng nhập; nó chỉ chuyển tiếp ID phiên mà nó nhận được.

Làm thế nào để mở rộng chức năng bằng các công cụ tùy chỉnh?

Ba tùy chọn. (1) Cài đặt sẵn tùy chỉnh — thả tệp JSON vào src/presets/custom/ hoặc gọi POST /api/v1/presets/generate với một URL mẫu và để LLM suy luận lược đồ. Cài đặt sẵn này sẽ xuất hiện dưới dạng tham số trên scrape_page . (2) Công cụ MCP tùy chỉnh — đăng ký trình xử lý của riêng bạn trong src/mcp/tools/, nó sẽ được thêm vào danh sách được tự động phát hiện. (3) Tạo nhánh — kho lưu trữ được cấp phép theo giấy phép MIT, máy chủ MCP nằm trong một mô-đun Python (src/mcp/server.py) và rất dễ mở rộng.

Các công cụ mà đại lý của bạn thực sự có thể sử dụng

Các đại lý cần những công cụ web thực sự, chứ không phải các lớp bọc Python tùy chỉnh

Một công cụ Python tùy chỉnh cho từng nguồn

Các lệnh gọi công cụ không có trạng thái sẽ mất bối cảnh đăng nhập

Xác thực thủ công và cấu hình proxy trong mã đại lý

Quá trình thu thập dữ liệu nhiều bước bên trong vòng lặp tác nhân

Từ `docker compose up` đến các công cụ gọi điện cho đại lý — chỉ trong 3 bước

Lợi ích bạn nhận được — một mẫu thiết kế, phù hợp với mọi nền tảng thương mại điện tử

Cách các đại lý kết nối hệ thống — mỗi cách chỉ trong 10 dòng

Các câu hỏi thường gặp về MCP và tích hợp đại lý

Bạn đã sẵn sàng cung cấp cho đại lý của mình những công cụ thực sự hữu ích chưa?

Được các đội ngũ phân tích dữ liệu và các nhà phát triển AI yêu thích

Các công cụ mà đại lý của bạn thực sự có thể sử dụng

Các đại lý cần những công cụ web thực sự, chứ không phải các lớp bọc Python tùy chỉnh

Một công cụ Python tùy chỉnh cho từng nguồn

Các lệnh gọi công cụ không có trạng thái sẽ mất bối cảnh đăng nhập

Xác thực thủ công và cấu hình proxy trong mã đại lý

Quá trình thu thập dữ liệu nhiều bước bên trong vòng lặp tác nhân

Từ docker compose up đến các công cụ gọi điện cho đại lý — chỉ trong 3 bước

Lợi ích bạn nhận được — một mẫu thiết kế, phù hợp với mọi nền tảng thương mại điện tử

Cách các đại lý kết nối hệ thống — mỗi cách chỉ trong 10 dòng

Các câu hỏi thường gặp về MCP và tích hợp đại lý

Bạn đã sẵn sàng cung cấp cho đại lý của mình những công cụ thực sự hữu ích chưa?

Được các đội ngũ phân tích dữ liệu và các nhà phát triển AI yêu thích

Từ `docker compose up` đến các công cụ gọi điện cho đại lý — chỉ trong 3 bước