cố vấn

Cung cấp cho một mô hình thực thi một cách để tham khảo ý kiến của một mô hình cố vấn riêng trước khi nó trả lời hoặc cam kết đưa ra quyết định.

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.

Cách sử dụng

Truyền mô hình cố vấn làm đối số đầu tiên. Mô hình có thể là bất kỳ tên mô hình hoặc phiên bản mô hình nào được Pydantic AI chấp nhận:

from pydantic_ai import Agent
from pydantic_ai_harness import Advisor

agent = Agent(
    'openai:gpt-5.4',
    capabilities=[
        Advisor(
            'anthropic:claude-opus-4-8',
            max_uses=1,
            max_tokens=4096,
        )
    ],
)

result = agent.run_sync(
    'Design a zero-downtime database migration. Consult the advisor before choosing a plan.'
)
print(result.output)

Người thi hành quyết định khi nào cần tham khảo ý kiến. Hãy hỏi nó một cách rõ ràng trong lời nhắc của người dùng hoặc hướng dẫn của agent khi cần tư vấn.

Sự thích ứng của nhà cung cấp

Advisor hiển thị một công cụ logic thông qua hai đường dẫn thực thi:

• Bản địa: khi người thực thi và cố vấn đều sử dụng nhà cung cấp Anthropic tương thích hoặc cả hai đều sử dụng OpenRouter, nhà cung cấp gốc của Pydantic AI AdvisorTool tiến hành tư vấn.
• Dự phòng cục bộ: mọi cặp đôi khác đều có một advisor công cụ chức năng. Gọi nó là chạy một AI agent Pydantic riêng biệt với mô hình cố vấn đã được định cấu hình.

Trong mặc định auto chế độ, lựa chọn gốc là bảo thủ. Khả năng này chỉ sử dụng lại tên mô hình đủ điều kiện của nhà cung cấp rõ ràng khi người thực thi và cố vấn chia sẻ một nhà cung cấp, do đó, nó không đoán được cách ID mô hình Anthropic ánh xạ tới sên danh mục OpenRouter. Ví dụ:

from pydantic_ai_harness import Advisor

# Native for an Anthropic executor; local for OpenAI, Google, and other executors.
anthropic_advisor = Advisor('anthropic:claude-opus-4-8')

# Native for an OpenRouter executor.
openrouter_advisor = Advisor('openrouter:anthropic/claude-opus-4.8')

Vượt qua một Model dụ chọn thực thi cục bộ trong auto chế độ. Điều này bảo tồn nhà cung cấp, ứng dụng khách, thông tin xác thực, URL cơ sở và công cụ đo lường của phiên bản đó. Tên mô hình chuỗi chỉ được giải quyết nếu thực thi cục bộ được chọn, do đó, tư vấn gốc sử dụng cấu hình hiện có của nhà cung cấp thực thi.

Hồ sơ mô hình người thực thi đã giải quyết của Pydantic AI đưa ra quyết định hỗ trợ cuối cùng. Máy khách hoặc mô hình không hỗ trợ công cụ gốc sẽ sử dụng dự phòng cục bộ.

Tùy chọn

sử dụng mode='native' khi việc tư vấn phải ở bên trong nhà cung cấp dịch vụ thi hành, hoặc mode='local' khi nhà cung cấp cố vấn đã định cấu hình phải nhận được một yêu cầu riêng. Chế độ gốc yêu cầu anthropic:<model> hoặc openrouter:<model> chuỗi và một người thực thi trên cùng một nhà cung cấp đó. Nó không bị lùi lại khi người thực thi thiếu sự hỗ trợ.

max_uses có cùng phạm vi theo yêu cầu với công cụ gốc của Anthropic. Chỉ những cuộc gọi có đối số xác thực mới sử dụng khoản phụ cấp này. Nó đặt lại khi người thực thi đưa ra yêu cầu mô hình tiếp theo. OpenRouter bỏ qua bản địa max_uses, vậy auto chế độ chọn dự phòng cục bộ khi tùy chọn này được đặt. Kết hợp OpenRouter, mode='native'và max_uses bị từ chối.

caching là một sự tối ưu hóa mang tính cơ hội của người gốc Anthropic. OpenRouter và dự phòng cục bộ không có quyền kiểm soát tương đương.

forward_history chỉ ảnh hưởng đến đường dẫn thực thi cục bộ, cho dù được chọn rõ ràng hay dưới dạng auto dự phòng. Nó không làm thay đổi cấu hình công cụ gốc hoặc lựa chọn gốc so với cục bộ. Khi được bật, cố vấn cục bộ sẽ nhận được lịch sử thông báo của người thực thi đã hoàn thành trước phản hồi hiện tại. Phản hồi hiện tại, bao gồm một phần văn bản và các cuộc gọi công cụ chưa được giải quyết, không được chuyển tiếp, vì vậy lời nhắc tư vấn vẫn cần chứa câu hỏi hiện tại hoàn chỉnh.

Cấu hình mô hình chuỗi có thể được tải từ thông số agent YAML hoặc JSON bằng cách chuyển Advisor trong custom_capability_types. runtime Model các phiên bản vẫn chỉ dành cho Python.

Bối cảnh được chuyển đến cố vấn

Bối cảnh phụ thuộc vào đường dẫn thực hiện:

Cố vấn địa phương sử dụng các hướng dẫn cố định của riêng mình. Nó không kế thừa các phụ thuộc, công cụ hoặc bộ công cụ của người thực thi. forward_history chỉ thêm các tin nhắn đã hoàn thành; nó không bao gồm phản hồi một phần hiện tại của người thi hành.

Đối với hành vi di động, hãy yêu cầu người thi hành đặt câu hỏi và tất cả bằng chứng liên quan vào phần gợi ý tư vấn. Mô tả công cụ cục bộ củng cố yêu cầu này.

Dự phòng cục bộ sẽ gửi lời nhắc đó đến nhà cung cấp và mô hình cố vấn đã định cấu hình. Việc thực thi gốc sử dụng cấu hình nhà cung cấp của người thi hành. Hãy coi sự khác biệt này như một lựa chọn định tuyến dữ liệu khi xem xét thông tin xác thực, chia sẻ bản ghi và chính sách của nhà cung cấp.

Cách sử dụng, lỗi và khả năng quan sát

Yêu cầu cố vấn địa phương chia sẻ điều hành của cha mẹ RunUsage và UsageLimits, do đó các yêu cầu và token của họ được tính vào giới hạn thông thường của cây agent. Các nhà cung cấp bản địa báo cáo việc sử dụng cố vấn theo giao thức riêng của họ. Anthropic ghi lại các giá trị cụ thể của cố vấn trong RequestUsage.details, trong khi OpenRouter hiển thị số lượng công cụ máy chủ tổng hợp trong thông tin chi tiết về nhà cung cấp phản hồi.

Sự kết hợp tùy chọn không hợp lệ không thành công khi Advisor được xây dựng. Khả năng tương thích của người thực thi và nhà cung cấp được xác thực khi quá trình chạy chuẩn bị yêu cầu mô hình của nó. Anthropic báo cáo lỗi cố vấn gốc dưới dạng kết quả của công cụ để người thực thi có thể tiếp tục. Nếu một cố vấn cục bộ tạo ra hành vi mô hình không hợp lệ, thì người thực thi sẽ nhận được một lần thử lại công cụ bình thường, khớp với các công cụ được hỗ trợ bởi subagent khác của Pydantic AI. Các lỗi về độ phân giải, xác thực, nhà cung cấp, yêu cầu và giới hạn sử dụng của mô hình cục bộ sẽ lan truyền và có thể dừng quá trình chạy. Khi cuộc gọi nội hạt vượt quá max_uses, công cụ sẽ trả về một thông báo có giới hạn yêu cầu người thực thi tiếp tục mà không cần thêm lời khuyên nào.

Thành phần

Khả năng không cần ràng buộc về thứ tự. Nó kết hợp với các khả năng khác và bộ công cụ thông thường thông qua lựa chọn công cụ gốc hoặc cục bộ của Pydantic AI.

Công cụ cố vấn luôn hiển thị và không bị trì hoãn thông qua Tìm kiếm công cụ. Nó bảo lưu tên công cụ và ID bộ công cụ advisor. một Advisor phiên bản được hỗ trợ cho mỗi agent vì công cụ gốc có một danh tính ổn định.

Trong quá trình phát trực tuyến, luồng người thực thi sẽ tạm dừng trong khi tư vấn cố vấn chạy và tiếp tục lại khi có lời khuyên hoàn chỉnh. Dự phòng cục bộ không ghép các đồng bằng token của mô hình cố vấn vào luồng thực thi.

Tham vấn địa phương có thể diễn ra song song. Khi nào max_uses được đặt, các cuộc gọi yêu cầu trợ cấp theo yêu cầu trước khi bắt đầu yêu cầu mô hình cố vấn, vì vậy các cuộc gọi song song không thể vượt quá mức đó.

Lời khuyên gốc tương thích với việc thực thi lâu dài vì nó vẫn là một phần của yêu cầu mô hình người thực thi. Việc thực thi cục bộ chưa thể duy trì cùng một ngữ nghĩa trên mọi chương trình phụ trợ lâu dài. Temporal và Prefect có thể kiểm tra lời khuyên được trả về nhưng thay đổi đối với hoạt động cục bộ hoặc nhiệm vụ cục bộ RunUsage không hợp nhất trở lại lần chạy bên ngoài. DBOS không kiểm tra các cuộc gọi công cụ chức năng thông thường, do đó, yêu cầu cố vấn cục bộ có thể chạy lại trong quá trình phát lại quy trình công việc.

sử dụng mode='native' với một nhà cung cấp được hỗ trợ khi chạy agent một cách lâu dài. Khai thác không kiểm tra tích hợp độ bền vì lõi AI Pydantic chưa đưa ra hợp đồng bối cảnh lâu bền công khai. Thực thi cục bộ, bao gồm cả auto dự phòng, do đó không được hỗ trợ trong các lần chạy lâu dài thay vì bị khả năng này từ chối.

Tham chiếu API

::: pydantic_ai_harness.advisor.Advisor