Lời nhắc hệ thống

SystemReminders nêu lại hướng dẫn hành vi được nhắm mục tiêu trong suốt quá trình chạy -- theo nhịp cố định hoặc phản ứng từ một điều kiện -- để chống lại sự mờ dần của lệnh diễn ra trong nhiều lượt mà không làm mất hiệu lực bộ nhớ đệm nhắc 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.

vấn đề

Các lần chạy nhiều lượt kéo dài sẽ khiến hướng dẫn bị mờ dần: sau nhiều lượt sử dụng công cụ, mô hình sẽ dần dần bỏ qua hướng dẫn mà nó đã được đưa ra khi bắt đầu. Một lời nhắc hệ thống bắt đầu phiên là không đủ cho công việc kéo dài. Cách khắc phục là nêu lại hướng dẫn được nhắm mục tiêu ở giữa quá trình -- theo nhịp cố định hoặc phản ứng khi phát hiện thấy một điều kiện.

Giải pháp

SystemReminders đưa lời nhắc vào từng yêu cầu mô hình, một cách tĩnh (Reminder, theo nhịp) hoặc động (một lệnh gọi có thể đọc ngữ cảnh chạy). Lời nhắc được thêm vào đuôi của yêu cầu dưới dạng tạm thời UserPromptPart đằng sau một CachePoint:

• Quá trình tiêm chạy sau lịch sử lâu dài được duy trì, do đó lời nhắc sẽ đến mô hình nhưng không bao giờ được ghi vào message_history. Không có lời nhắc nào được tích lũy qua các lượt.
• A CachePoint được đặt ngay lập tức trước lời nhắc, do đó, tiền tố được lưu trong bộ nhớ đệm (công cụ + hệ thống + cuộc hội thoại thực) vẫn giữ nguyên theo lượt chuyển đổi giống hệt byte. Chỉ có lời nhắc nhỏ nằm ngoài bộ đệm.

Thay vào đó, việc đưa vào lời nhắc hệ thống (hoặc bất kỳ phần nào vẫn còn tồn tại) sẽ nằm ở phía trước yêu cầu, vì vậy mọi lời nhắc sẽ phá vỡ tiền tố được lưu trong bộ nhớ đệm và các lời nhắc cũ sẽ chồng chất trong lịch sử. Khả năng này tránh được cả hai.

Cách sử dụng

Xây dựng một Agent với SystemReminders(...) trong nó capabilities:

from pydantic_ai import Agent
from pydantic_ai_harness import SystemReminders
from pydantic_ai_harness.system_reminders import Reminder

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[
        SystemReminders(
            reminders=[Reminder('Stay focused on the original request.', interval=5)],
        )
    ],
)

result = agent.run_sync('Refactor the auth module and add tests.')
print(result.output)

Lời nhắc tĩnh

A Reminder bắn theo nhịp trong một lần chạy:

Mặc định tag='system-reminder' gói gọn mọi lời nhắc trong <system-reminder>...</system-reminder>, tuân theo quy ước của Claude Code để mô hình đọc nó dưới dạng ghi chú hướng dẫn ngoài phạm vi thay vì văn bản của người dùng.

các tag gói chỉ áp dụng cho tĩnh Reminder nội dung. Có thể gọi động (bao gồm GoalReanchor và LLMReminder) chèn văn bản thô được trả về và có định dạng riêng.

Lời nhắc động

Lời nhắc động có thể gọi được (RunContext) -> str | None (đồng bộ hóa hoặc không đồng bộ), được đánh giá theo mọi yêu cầu mô hình. Trả về một chuỗi để tiêm, hoặc None bỏ qua. Đây là đường nối chung cho các điều kiện cần trạng thái chạy -- ngân sách token, sau khi nén, chuyển đổi chế độ -- không có trình phát hiện mã hóa cứng:

from pydantic_ai_harness import SystemReminders

SystemReminders(
    dynamic_reminders=[
        lambda ctx: 'Wrap up soon.' if ctx.run_step > 20 else None,
    ],
)

GoalReanchor -- neo giữ mục tiêu không tốn chi phí

GoalReanchor nêu lại yêu cầu người dùng đầu tiên của lần chạy dưới dạng mỏ neo và yêu cầu mô hình kiểm tra hành động tiếp theo để thúc đẩy nó. Không có lệnh gọi mô hình, không có phụ thuộc:

from pydantic_ai_harness import SystemReminders
from pydantic_ai_harness.system_reminders import GoalReanchor

SystemReminders(dynamic_reminders=[GoalReanchor()])

LLMReminder -- những cú hích do mô hình tạo ra

LLMReminder có một mô hình tóm tắt bản ghi ngắn gọn (mục tiêu ban đầu + hoạt động gần đây) thành một động lực ngắn để thực hiện nhiệm vụ. Nó đòi hỏi một sự rõ ràng model -- không có id mẫu mặc định -- và quay lại GoalReanchor văn bản về bất kỳ lỗi nào, do đó, thế hệ bị lỗi sẽ không bao giờ chặn quá trình chạy:

from pydantic_ai_harness import SystemReminders
from pydantic_ai_harness.system_reminders import LLMReminder

SystemReminders(dynamic_reminders=[LLMReminder(model='anthropic:claude-haiku-4-5')])

Lời nhắc động không có nhịp điệu riêng -- chúng chạy theo mọi yêu cầu của mô hình. LLMReminder do đó phát hành một lệnh gọi mô hình bổ sung mỗi lượt (cách sử dụng của nó được luồng vào lệnh chạy chính thông qua ctx.usage, vì vậy nó xuất hiện trong result.usage()). Cuộc gọi lồng nhau cũng chạy dưới lệnh gọi cha usage_limits với một yêu cầu được giữ lại cho yêu cầu mô hình trước đó, vì vậy lời nhắc không thể đẩy một lượt chạy vượt quá yêu cầu đó request_limit; một khi ngân sách eo hẹp thì thế hệ sẽ bị bỏ qua và GoalReanchor văn bản được sử dụng thay thế. Vì dự phòng không hoạt động nên liên tục bị định cấu hình sai model (id sai, thiếu key) trông vẫn hoạt động bình thường. Để giới hạn chi phí, hãy đặt nó sau một nhịp bằng trình bao bọc không đồng bộ:

_llm = LLMReminder(model='anthropic:claude-haiku-4-5')

async def every_tenth(ctx):
    return await _llm(ctx) if ctx.run_step % 10 == 0 else None

SystemReminders(dynamic_reminders=[every_tenth])

LLMReminder tạo ra bên trong wrap_model_request, do đó, trong quá trình thực thi bền vững (Tạm thời, DBOS, Tỉnh trưởng), lệnh gọi mô hình của nó chạy trong bối cảnh điều phối thay vì một bước bền vững -- không xác định khi phát lại và không được kiểm tra điểm, với các lỗi âm thầm quay trở lại GoalReanchor. Để chạy bền thích GoalReanchor (không có cuộc gọi mẫu) hoặc cổng LLMReminder tắt.

Cấu hình

from pydantic_ai_harness import SystemReminders
from pydantic_ai_harness.system_reminders import Reminder

SystemReminders(
    reminders=[Reminder('...', interval=5)],
    dynamic_reminders=[],       # callables evaluated every request
    cache_ttl='5m',             # TTL for the cache breakpoint before the reminder ('5m' | '1h')
    on_fire=None,               # optional callback invoked with each rendered reminder
)

Trạng thái mỗi lần chạy (bộ đếm yêu cầu và số lần cháy trên mỗi lần nhắc nhở) được cách ly thông qua for_run, do đó, các hoạt động đồng thời trên cùng một agent sẽ không bao giờ chia sẻ trạng thái cháy.

Đảm bảo bộ nhớ đệm

Lời nhắc không bao giờ được đưa vào lời nhắc hoặc hướng dẫn của hệ thống. Họ cưỡi cái đuôi phù du đằng sau một CachePoint, do đó qua các lượt:

• lịch sử lâu dài chỉ phát triển theo phần bổ sung và được phát lại theo từng byte, do đó toàn bộ tiền tố vẫn đủ điều kiện cho lần truy cập bộ nhớ đệm (tuân theo TTL bộ nhớ đệm của nhà cung cấp -- khoảng cách dài hơn cache_ttl hết hạn mục nhập ngay cả với tiền tố không thay đổi);
• lời nhắc nhở và nó CachePoint chỉ tồn tại trong bản sao theo yêu cầu, vì vậy chúng không thể vô hiệu hóa bất cứ điều gì và không được duy trì.

CachePoint được hỗ trợ trên Anthropic, Amazon Bedrock (API Converse) và OpenRouter (các mô hình Anthropic và Gemini); trên các nhà cung cấp không có bộ nhớ đệm nhanh chóng, nó sẽ bị bỏ qua (không có gì để phá sản). Lời nhắc dẫn đầu với CachePoint chỉ khi yêu cầu đã mang nội dung của người dùng để điểm ngắt được đính kèm -- ở lượt có nội dung duy nhất ở đuôi là lời nhắc (ví dụ: instructions-chỉ yêu cầu đầu tiên của lần chạy), lời nhắc sẽ được đưa vào mà không có điểm dừng vì không có tiền tố để bảo vệ.

Thành phần

• Kế hoạch sử dụng cơ chế đuôi phù du tương tự để hiển thị kế hoạch. Cả hai đều hợp thành một agent: mỗi agent gắn phần đuôi riêng của nó vào sau phần của nó CachePoint, và cả hai đều không được duy trì. Lưu ý rằng mỗi khả năng của đuôi phù du sẽ thêm một điểm dừng bộ đệm: Anthropic cho phép 4 (3 với bộ nhớ đệm tự động) và lõi sẽ cắt bớt phần cũ nhất vượt quá trước, do đó, xếp chồng một số khả năng chèn đuôi cùng với anthropic_cache_instructions / anthropic_cache_tool_definitions có thể loại bỏ một điểm dừng cũ hơn. Hai khả năng cộng với các giá trị mặc định vẫn nằm trong ngân sách.
• Phát hiện vòng lặp (phát hiện và ngắt bằng một cú huých bền bỉ) là một mối quan tâm riêng. SystemReminders là khả năng điều khiển nhịp/điều kiện không thay đổi; lời nhắc động có thể đọc trạng thái vòng lặp từ bộ phận phụ trách của bạn nếu bạn muốn điều khiển nó.

Lời nhắc ở đuôi chỉ được thêm vào khi tin nhắn cuối cùng trong yêu cầu là ModelRequest và ít nhất một lời nhắc sẽ kích hoạt, do đó, một lượt không kích hoạt sẽ không thêm gì vào yêu cầu. Các lượt tiếp tục của nhà cung cấp (trong đó đuôi yêu cầu bị treo ModelResponse được lặp lại nguyên văn) được bỏ qua và không sử dụng khe nhịp.

Không thể tuần tự hóa theo thông số kỹ thuật

SystemReminders.get_serialization_name() trả lại None: lời nhắc nhận các lệnh gọi tùy ý, không thể được tuần tự hóa thành thông số agent.

Đọc thêm

• Khả năng AI của Pydantic
• Móc -- wrap_model_request là điểm tiêm tạm thời được sử dụng ở đây
• Bộ nhớ đệm nhắc nhở của con người
• Kế hoạch -- một khả năng khai thác nhận biết bộ đệm nhanh khác

Tham chiếu API

::: pydantic_ai_harness.system_reminders.SystemReminders

::: pydantic_ai_harness.system_reminders.Reminder

::: pydantic_ai_harness.system_reminders.GoalReanchor

::: pydantic_ai_harness.system_reminders.LLMReminder