Lời nhắc được quản lý

ManagedPrompt hỗ trợ các hướng dẫn của agent bằng một Lời nhắc do logfire quản lý, để bạn có thể lặp lại lời nhắc hệ thống của mình từ Giao diện người dùng Logfire -- được lập phiên bản, gắn nhãn và cuộn out -- mà không cần chạm vào mã hoặc triển khai lại. Đó là khả năng AI Pydantic, vậy bạn nối dây nó qua capabilities= tham số trên Agent.

Nguồn

Cài đặt logfire thêm:

uv add "pydantic-ai-harness[logfire]"

!!! lưu ý "Bên thứ nhất Managed khả năng đang bay" Bên thứ nhất, rộng hơn Managed khả năng đang được xây dựng trong pydantic-ai#5107 và cuối cùng sẽ là có thể nhập khẩu như pydantic_ai.managed.logfire.Managed -- bao gồm các hướng dẫn, cài đặt mô hình, và các biến toàn bộ thông số kỹ thuật. Cho đến lúc đó, ManagedPrompt là đường dẫn được hỗ trợ để sao lưu một hướng dẫn của agent với lời nhắc do Logfire quản lý.

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 đề nó giải quyết

Lời nhắc rất quan trọng đối với hành vi của tổng đài viên nhưng việc lặp lại chúng theo cách thông thường chỉnh sửa -> xem lại -> vòng triển khai chậm. Bạn không thể dễ dàng kiểm tra A/B một thay đổi và bạn không thể thực hiện nó quay lại thời điểm nó hoạt động sai trong quá trình sản xuất mà không vận chuyển bản dựng mới.

ManagedPrompt di chuyển lời nhắc ra khỏi cơ sở mã của bạn và vào repository biến được quản lý của Logfire. Nó khai báo biến được quản lý hỗ trợ cho bạn và giải quyết nó một lần mỗi lần chạy, cung cấp cho giá trị được giải quyết vào hướng dẫn của agent. Độ phân giải xảy ra bên trong quá trình chạy wrap_run móc, sử dụng ResolvedVariable dưới dạng trình quản lý bối cảnh luôn mở trong toàn bộ quá trình chạy -- để nhãn và phiên bản đã chọn được đính kèm như hành trang cho mỗi đứa con của agent chạy. Bạn nhận được mối tương quan trực tiếp giữa một lần chạy hành vi và phiên bản nhắc nhở chính xác đã tạo ra nó, cộng với việc lặp lại và khôi phục ngay lập tức từ giao diện người dùng Logfire.

Cách sử dụng

Truyền tên lời nhắc và giá trị mặc định. Tên support_agent được khai báo là được quản lý biến prompt__support_agent -- cách đặt tên mà tính năng quản lý Lời nhắc của Logfire sử dụng (dấu gạch nối trong tên trở thành dấu gạch dưới). các default giữ cho agent hoạt động cho đến khi một giá trị từ xa được công bố, vì vậy mã của bạn luôn chạy ngay cả trước khi bạn tạo lời nhắc trong Logfire.

import logfire
from pydantic_ai import Agent

from pydantic_ai_harness import ManagedPrompt

logfire.configure()

agent = Agent(
    'openai:gpt-5',
    capabilities=[
        ManagedPrompt(
            'support_agent',
            default='You are a helpful customer support agent. Be friendly and concise.',
            label='production',
        )
    ],
)

result = agent.run_sync('My order never arrived.')
print(result.output)

Ghim label='production' là giá trị mặc định được đề xuất: giá trị đã giải quyết chỉ thay đổi trên một triển khai nhắc nhở có chủ ý, giúp giữ cho bộ nhớ đệm nhắc nhở của nhà cung cấp luôn nóng (xem Đánh đổi bộ đệm nhắc nhở bên dưới).

Nhắm mục tiêu

Đối với việc gán A/B xác định (cùng một người dùng luôn nhìn thấy cùng một nhãn), hãy chuyển một targeting_key. Nó có thể là một chuỗi tĩnh hoặc một chuỗi có thể gọi được lấy từ khóa từ RunContext -- tiện dụng khi chìa khóa sống trong agent của bạn deps:

from dataclasses import dataclass

from pydantic_ai import Agent

from pydantic_ai_harness import ManagedPrompt


@dataclass
class Deps:
    user_id: str


agent = Agent(
    'openai:gpt-5',
    deps_type=Deps,
    capabilities=[
        ManagedPrompt(
            'support_agent',
            default='You are a helpful customer support agent.',
            targeting_key=lambda ctx: ctx.deps.user_id,
        ),
    ],
)

Vượt qua attributes (một ánh xạ hoặc một ánh xạ trả về có thể gọi được) cho các quy tắc nhắm mục tiêu dựa trên điều kiện. Khi nào label bị bỏ qua, các quy tắc nhắm mục tiêu và triển khai của biến sẽ chọn nhãn. Khi cả hai targeting_key và attributes bị bỏ qua, Logfire sẽ quay trở lại bối cảnh nhắm mục tiêu của chính nó và sau đó đến id theo dõi đang hoạt động.

Đối với nhắm mục tiêu phía Logfire nằm bên ngoài agent (ví dụ: được đặt một lần cho mỗi trình xử lý yêu cầu), hãy sử dụng Đăng nhập của targeting_context trong một phạm vi bên ngoài; ManagedPrompt chỉ cần targeting_key / attributes khi chìa khóa đến từ của agent RunContext.

Tạo khuôn mẫu với deps

Theo mặc định, lời nhắc đã giải quyết được sử dụng nguyên văn. Vượt qua render_template=True để hiển thị nó dưới dạng Mẫu ghi đông so với agent deps - cơ chế tương tự như TemplateStr -- vậy {{field}} được lấp đầy từ deps:

from dataclasses import dataclass

from pydantic_ai import Agent

from pydantic_ai_harness import ManagedPrompt


@dataclass
class Deps:
    customer_name: str


agent = Agent(
    'openai:gpt-5',
    deps_type=Deps,
    capabilities=[
        ManagedPrompt(
            'support_agent',
            default='You are helping {{customer_name}}. Be friendly and concise.',
            render_template=True,
        ),
    ],
)

Yêu cầu kết xuất pydantic-handlebars (cài đặt pydantic-ai-slim[spec]). Nó được tắt theo mặc định.

Trao đổi bộ nhớ đệm nhanh chóng

Giá trị được giải quyết nằm trong hướng dẫn hệ thống của tổng đài viên. Bộ nhớ đệm nhắc nhở của nhà cung cấp (Anthropic, Khóa OpenAI, v.v.) hoàn toàn theo tiền tố -- tools -> system -> messages -- vì vậy bất kỳ thay đổi nào đối với hệ thống khối làm mất hiệu lực tiền tố được lưu trong bộ nhớ cache cho các lần chạy bị ảnh hưởng.

Tóm lại: ghim một label giữ cho bộ đệm luôn nóng; sử dụng ManagedPrompt vì nền tảng A/B được chọn tham gia chi phí bộ nhớ đệm. Nếu bạn không cần triển khai, label='production' là mặc định được đề xuất.

Mang biến của riêng bạn

Khai báo cùng một tên nhiều lần cũng được -- mỗi lần ManagedPrompt xây dựng sự ủng hộ của riêng mình biến, vì vậy việc chia sẻ lời nhắc giữa một số tổng đài viên chỉ có tác dụng. Vượt qua một hiện có logfire.variables.Variable làm đối số đầu tiên thay vì tên khi bạn muốn tự khai báo biến -- ví dụ ví dụ một biến mẫu hoặc một biến được đăng ký variables_push:

import logfire
from pydantic_ai import Agent

from pydantic_ai_harness import ManagedPrompt

logfire.configure()

support_prompt = logfire.var(
    name='prompt__support_agent',
    type=str,
    default='You are a helpful customer support agent. Be friendly and concise.',
)

agent = Agent('openai:gpt-5', capabilities=[ManagedPrompt(support_prompt, label='production')])

Khi nào name là tên nhắc nhở (không phải là Variable), vượt qua logfire_instance= để khai báo biến trên một phiên bản Logfire cụ thể thay vì mặc định ở cấp mô-đun. default được yêu cầu khi name là tên nhắc nhở và bị bỏ qua khi bạn chuyển một Variable (vốn đã mang theo riêng của nó mặc định và phiên bản).

Nó sáng tác như thế nào

• Giải quyết một lần mỗi lần chạy. Thay đổi về việc lật hoặc triển khai nhãn xảy ra trong quá trình chạy của Logfire thì không được chọn cho đến khi lần chạy tiếp theo bắt đầu -- sự đánh đổi để có được các lệnh chạy ổn định và một phạm vi hành lý trên tất cả các nhịp trẻ em.
• Chạy ngoài cùng. Khả năng bao trùm Instrumentation do đó, hành lý của biến đã giải quyết bao gồm khoảng runtime agent cũng như các phần tử con của nó. Trên gần đây Phiên bản logfire cả nhãn đã chọn và phiên bản đều được phân phối dưới dạng hành lý riêng biệt thuộc tính.
• An toàn đồng thời. Độ phân giải được tách biệt trên mỗi lần chạy thông qua một biến ngữ cảnh, do đó, một biến duy nhất phiên bản khả năng là an toàn để chia sẻ trên các lần chạy đồng thời.
• Có thể kiểm tra giữa quá trình chạy. ManagedPrompt.resolved để lộ hoạt động đang hoạt động ResolvedVariable (value, label, version, reason) để kiểm tra -- ví dụ: từ bên trong một công cụ. Đó là None bên ngoài một cuộc chạy.

Tham chiếu API

Lời nhắc được giải quyết là một str. Truyền tên dấu nhắc trần ( prompt__ tiền tố và chuẩn hóa từ dấu gạch nối sang dấu gạch dưới được áp dụng cho bạn) và một default, sau đó sử dụng label, targeting_key, attributes, render_templatevà logfire_instance để kiểm soát độ phân giải.

::: pydantic_ai_harness. ManagedPrompt