Bạn.com

YouSearch và YouResearch cung cấp cho agent các công cụ nghiên cứu web được hỗ trợ bởi Bạn.com API. YouSearch thêm vào web_search và get_page, để khảo sát trang web và đọc đầy đủ một trang. YouResearch thêm vào answer, researchvà finance_research, để trích dẫn câu trả lời cho câu hỏi a tra cứu duy nhất không thể giải quyết.

Nguồn

Mặc dù Pydantic AI Harness có trên các bản phát hành 0.x nhưng API có thể thay đổi giữa các bản phát hành nhỏ; khi đó, cảnh báo ngừng sử dụng và hướng dẫn di chuyển ghi chú phát hành sẽ cho bạn (hoặc người đại diện của bạn) biết chính xác cách nâng cấp. Xem chính sách phiên bản.

vấn đề

Một số công cụ tìm kiếm chỉ trả về tiêu đề và đoạn trích, do đó agent phải tìm nạp trang trước khi nó có thể đánh giá nguồn. Những người khác trả lại toàn bộ trang, điền vào bối cảnh bằng văn bản mà agent sẽ vứt đi. Và một số câu hỏi không phải là một tra cứu: việc trả lời chúng cần rất nhiều tìm kiếm, đọc qua các kết quả, và viết câu trả lời kèm theo trích dẫn.

YouSearch và YouResearch bao gồm các API tìm kiếm, trang và nghiên cứu của You.com dưới dạng hai khả năng. Mỗi người mang theo công cụ của mình, giới hạn về số lượng văn bản mà các công cụ đó trả về và hướng dẫn nghiên cứu ngắn cho lời nhắc của hệ thống.

Cách sử dụng

Cài đặt youdotcom thêm và thiết lập YDC_API_KEY biến môi trường (tạo khóa tại https://api.you.com; di sản YOU_API_KEY_AUTH cũng là vinh dự). Các ví dụ dưới đây sử dụng mô hình Anthropic và Agent.from_file, vậy họ cũng kéo vào anthropic nhà cung cấp và spec Hỗ trợ YAML:

uv add "pydantic-ai-harness[youdotcom,anthropic]" "pydantic-ai-slim[spec]"

Sau đó chuyển khả năng cho một Agent thông qua capabilities tham số:

from pydantic_ai import Agent
from pydantic_ai_harness import YouResearch, YouSearch

agent = Agent('anthropic:claude-sonnet-4-6', capabilities=[YouSearch(), YouResearch()])

result = agent.run_sync('What changed in the latest stable Python release?')
print(result.output)

sử dụng YouSearch riêng nếu bạn chỉ cần tìm kiếm và đọc trang.

Công cụ

web_search trả về các đoạn trích ngắn từ mỗi trang thay vì toàn bộ trang, vì vậy việc xem qua một số nguồn vẫn rẻ. Sau đó, agent sẽ đọc một trang chọn với get_page. Đặt extraction_mode='full_page' để có được từng kết quả thay vào đó, đánh dấu đầy đủ.

get_page và toàn trang web_search văn bản được giới hạn ở max_text_chars ký tự, giữ đầu (đầu trang mang nội dung); khi một trang vượt quá giới hạn, đầu ra kết thúc bằng một [... page text truncated at N characters] điểm đánh dấu. Số kết quả là giới hạn theo cách tương tự: num_results được gửi đến You.com và được áp dụng lại cho phản hồi quay lại.

A web_search truy vấn không khớp gì là câu trả lời hợp lệ, không phải là lỗi: công cụ trả về No results found for {query!r}.. Các lỗi khác đạt đến mô hình như một ModelRetry: một URL hoặc câu hỏi trả về trống, giới hạn tỷ lệ, tham số You.com bị từ chối (422) hoặc sự cố mạng hoặc API tạm thời. Cuộc chạy vẫn tiếp tục và mô hình có thể sửa URL, diễn đạt lại câu hỏi hoặc thử lại. Xác thực, lỗi thanh toán và cấp phép (401/402/403) là những lỗi bạn phải khắc phục trong thiết lập của riêng bạn, vì vậy họ dừng chạy.

Nghiên cứu

sử dụng answer đối với một câu hỏi trực tiếp, bạn mong đợi một cuộc gọi sẽ giải quyết. sử dụng research khi câu hỏi cần nhiều tìm kiếm và viết lên trên nguồn. finance_research là research điều chỉnh để phân tích tài chính.

research chờ đợi kết quả của nó thay vì giao lại một công việc để thăm dò ý kiến, và nghiên cứu sâu và toàn diện thường mất vài phút, vì vậy timeout_ms mặc định đến 10 phút. Nó hoạt động chăm chỉ như thế nào được thiết lập bởi research_effort: lite, standard, deephoặc exhaustive. You.com cũng có một frontier đẳng cấp nhưng nó chỉ chạy như một công việc nền nên khả năng này không cung cấp được nó. finance_research có cái riêng của nó finance_effort: deep hoặc exhaustive.

from pydantic_ai_harness import YouResearch

YouResearch(research_effort='deep')

Đặt output_schema vào một lược đồ JSON để có research trả về có cấu trúc đầu ra (viết dưới dạng JSON) thay vì văn xuôi. You.com từ chối một output_schema khi nào research_effort là 'lite', vì vậy yêu cầu tăng cả hai một lỗi khi bạn tạo khả năng.

Trích dẫn có cấu trúc

Mỗi công cụ đều trả về một ToolReturn. của nó return_value là văn bản mà mô hình nhìn thấy, với một Sources: khối đã thêm khi công cụ có trích dẫn. của nó metadata['sources'] nắm giữ các nguồn tương tự như YouSource hồ sơ ({'url': ..., 'title': ...}). web_search cũng đặt phản hồi của search_uuid và latency trong siêu dữ liệu, để theo dõi. mô hình không thấy siêu dữ liệu: ứng dụng của bạn đọc nó từ ToolReturnPart trong lịch sử tin nhắn, do đó bạn có thể hiển thị các trích dẫn mà không cần phân tích bất kỳ văn bản nào:

from pydantic_ai.messages import ModelRequest, ToolReturnPart

for message in result.all_messages():
    if isinstance(message, ModelRequest):
        for part in message.parts:
            if isinstance(part, ToolReturnPart) and part.metadata is not None:
                for source in part.metadata.get('sources', []):
                    print(source['url'], source['title'])

Hướng dẫn

YouSearch thêm hướng dẫn nghiên cứu ngắn vào lời nhắc hệ thống: tìm kiếm trên toàn bộ với web_search đầu tiên, hãy đọc đầy đủ những trang hứa hẹn nhất với get_page trước khi đưa ra kết luận, hãy ưu tiên các nguồn chính và trích dẫn các URL bạn đã sử dụng. YouResearch thêm hướng dẫn về thời điểm sử dụng answer, researchvà finance_research. Cả hai đều yêu cầu mô hình xử lý nội dung web mà nó tìm nạp dưới dạng dữ liệu không đáng tin cậy, không phải là hướng dẫn để làm theo. Trên một trong hai khả năng, hãy đặt guidance vào văn bản của riêng bạn để thay thế mặc định hoặc để '' không thêm gì cả.

Cấu hình

Mỗi lĩnh vực của YouSearch với mặc định của nó:

from pydantic_ai_harness import YouSearch

YouSearch(
    num_results=10,              # results per web_search call (1 to 20)
    extraction_mode='highlights',  # 'highlights' excerpts, or 'full_page' markdown
    max_text_chars=10_000,       # get_page / full-page text cap, in characters
    include_domains=[],          # only return results from these domains (allowlist)
    exclude_domains=[],          # never return results from these domains (denylist)
    boost_domains=[],            # re-rank these domains higher without excluding others
    freshness=None,              # 'day' | 'week' | 'month' | 'year' | 'YYYY-MM-DDtoYYYY-MM-DD'
    country=None,                # two-letter country code to focus results
    guidance=None,               # None = default instructions, '' = none, str = custom
    timeout_ms=60_000,           # per-request timeout for the default client
    client=None,                 # YouClient -- None builds youdotcom.You from YDC_API_KEY
)

Mỗi lĩnh vực của YouResearch với mặc định của nó:

from pydantic_ai_harness import YouResearch

YouResearch(
    research_effort='standard',  # 'lite' | 'standard' | 'deep' | 'exhaustive'
    finance_effort='deep',       # 'deep' | 'exhaustive'
    include_domains=[],          # only draw from these domains (allowlist)
    exclude_domains=[],          # never draw from these domains (denylist)
    boost_domains=[],            # re-rank these domains higher
    freshness=None,              # 'day' | 'week' | 'month' | 'year' | 'YYYY-MM-DDtoYYYY-MM-DD'
    country=None,                # two-letter country code to focus results
    output_schema=None,          # JSON schema for research structured output
    guidance=None,               # None = default instructions, '' = none, str = custom
    timeout_ms=600_000,          # per-request timeout for the default client
    client=None,                 # YouClient -- None builds youdotcom.You from YDC_API_KEY
)

include_domains là danh sách cho phép và không thể kết hợp với exclude_domains hoặc boost_domains. Việc kết hợp chúng sẽ gây ra lỗi khi bạn tạo ra khả năng, cũng như các giới hạn ngoài phạm vi và không hợp lệ freshness. Tên miền, freshnessvà country cài đặt áp dụng cho web_search, answer và research. finance_research chỉ lấy đầu vào của nó và finance_effort.

Nhiều trường hợp

Hai phiên bản có cùng khả năng đăng ký cùng một tên công cụ, đó là một lỗi. Để chạy nhiều thiết lập trong một agent -- giả sử một agent YouSearch kết thúc trang web mở và một trang web giới hạn ở một vài tên miền -- gói các trang bổ sung vào lõi của PrefixTools khả năng. Nó đặt tiền tố trước tên công cụ của họ:

from pydantic_ai import Agent
from pydantic_ai.capabilities import PrefixTools

from pydantic_ai_harness import YouSearch

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[
        YouSearch(),  # web_search, get_page
        PrefixTools(
            wrapped=YouSearch(include_domains=['sec.gov'], guidance=''),
            prefix='sec',
        ),  # sec_web_search, sec_get_page
    ],
)

Đặt guidance='' trên phiên bản được bao bọc (hoặc thay thế nó bằng văn bản cho biết mô hình khi nào nên sử dụng các công cụ có tiền tố), vì mỗi trường hợp khác đóng góp hướng dẫn nghiên cứu mặc định tương tự.

Khách hàng tùy chỉnh

Máy khách mặc định là youdotcom.You, được xây dựng từ YDC_API_KEY biến môi trường. Khi biến đó không được đặt, việc tạo ra khả năng không thành công với thông báo cho bạn biết cách khắc phục. Để tự đặt khóa API, trỏ vào một máy chủ khác hoặc sử dụng đồ giả trong các bài kiểm tra, vượt qua bất kỳ đối tượng nào có các phương pháp được liệt kê trong YouClient giao thức:

from youdotcom import You

from pydantic_ai_harness import YouSearch

YouSearch(client=You(api_key_auth='...'))

YouSearch so với WebSearch cốt lõi

Core vận chuyển một WebSearch khả năng thích ứng với mô hình: nó sử dụng tìm kiếm của chính nhà cung cấp trong đó mô hình này có một công cụ DuckDuckGo cục bộ ở mọi nơi khác. Hãy sử dụng nó khi bạn muốn tìm kiếm theo bất kỳ mô hình nào bạn chạy. sử dụng YouSearch khi bạn muốn cùng một tìm kiếm trên mọi mô hình: một nhà cung cấp, các đoạn trích với mọi kết quả, trang số lần đọc bạn yêu cầu, bộ lọc tên miền và kiểm soát độ mới.

Cung cấp cho agent một khả năng tìm kiếm trên web: cốt lõi WebSearch, khai thác ExaSearchhoặc YouSearch. Tất cả họ đều đặt tên cho công cụ của mình theo cùng một cách -- web_search, cộng get_page đối với hai harness -- và một agent không thể có hai công cụ có cùng tên nên khi tạo sẽ bị lỗi. Nếu bạn muốn dù sao thì hai cái, bọc một cái vào PrefixTools để đổi tên các công cụ của nó, như được hiển thị trong Nhiều trường hợp. Có thêm một trường hợp: trên Mô hình nhân học, tìm kiếm tích hợp còn được gọi là web_search, vậy WebSearch xung đột ở đó mặc dù cuộc tìm kiếm diễn ra theo hướng của Anthropic. Vượt qua WebSearch(native=False) để chuyển nó sang công cụ DuckDuckGo, được gọi là duckduckgo_search và không xung đột.

Thông số agent (YAML/JSON)

YouSearch và YouResearch làm việc với Pydantic AI thông số agent, vì vậy bạn có thể khai báo chúng trong một tập tin cấu hình thay vì Python:

# agent.yaml
model: anthropic:claude-sonnet-4-6
capabilities:
  - YouSearch:
      num_results: 5
      freshness: month
  - YouResearch:
      research_effort: deep

from pydantic_ai import Agent
from pydantic_ai_harness import YouResearch, YouSearch

agent = Agent.from_file('agent.yaml', custom_capability_types=[YouSearch, YouResearch])

Vượt qua custom_capability_types để trình tải thông số kỹ thuật biết cách khởi tạo khả năng. các client trường không được tuần tự hóa theo thông số kỹ thuật; được tải thông số kỹ thuật các phiên bản luôn xây dựng ứng dụng khách mặc định từ YDC_API_KEY. Trong thông số kỹ thuật, output_schema có dạng chính tả lược đồ JSON.

Đọc thêm

• Khả năng AI của Pydantic
• Bộ công cụ
• Tài liệu API You.com

Tham chiếu API

::: pydantic_ai_harness.youdotcom.YouSearch

::: pydantic_ai_harness.youdotcom.YouResearch

::: pydantic_ai_harness.youdotcom.YouSearchToolset

::: pydantic_ai_harness.youdotcom.YouResearchToolset

::: pydantic_ai_harness.youdotcom.YouSource