Tạo khả năng runtime

Việc tạo khả năng trong runtime cho phép agent viết, xác thực và duy trì các khả năng của Pydantic AI trong một lần chạy để kích hoạt ở lần tiếp theo. CapabilityCreation đưa ra các công cụ cho phép mô hình viết một AbstractCapability phân lớp vào đĩa dưới dạng nguồn Python và xác thực nó ngay lập tức; người điều phối tải các khả năng được biên soạn đang hoạt động vào phần tiếp theo agent.run(...).

CapabilityCreation dành cho các khả năng do agent tạo ra dưới dạng nguồn Python. Để biết các khả năng được viết hoặc chọn theo mã ứng dụng, hãy xem Xây dựng khả năng tùy chỉ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 đề

Một coding agent thường phát hiện ra giữa nhiệm vụ rằng nó muốn một hành vi mà máy chủ của nó chưa có: một lan can bảo vệ, một hướng dẫn bổ sung, một công cụ, một móc yêu cầu. Bề mặt khả năng để thể hiện đã tồn tại -- nhưng thông thường chỉ nhà phát triển mới có thể viết một lớp khả năng, nối nó vào agent và khởi động lại. Nếu không tạo khả năng runtime, agent không thể tạo phần mở rộng đó trong quá trình chạy và cung cấp phần mở rộng đó cho lần chạy tiếp theo.

Giải pháp

CapabilityCreation trưng bày ba công cụ:

• author_capability(name, code) -- viết code để <directory>/<name>.py, nhập nó và xác thực nó. Việc xác nhận yêu cầu chính xác một pydantic_ai.capabilities.AbstractCapability lớp con xây dựng không có đối số; các getters tĩnh không có tác dụng phụ (get_instructions, get_toolset, get_native_tools, get_model_settings, get_serialization_name) được thực hiện. Các móc vòng đời không đồng bộ không được chạy -- chúng cần có một vòng đời trực tiếp RunContext.
• list_authored_capabilities() -- liệt kê các khả năng được tạo cùng với trạng thái của chúng và bất kỳ lỗi xác thực nào.
• disable_authored_capability(name) -- dừng việc đưa một khả năng vào lần chạy tiếp theo.

"Móc" không phải là một đối tượng độc lập trong pydantic-ai -- nó là một phương pháp trên một khả năng. Vì vậy, việc tạo ra một hook có nghĩa là tạo ra một khả năng ghi đè một phương thức trong vòng đời. Một hook bị ghi đè duy nhất là một khả năng hợp lệ.

Cách sử dụng

xây dựng CapabilityCreation với một directory đối với các tệp được tạo, sau đó thêm nó vào agent capabilities:

from pathlib import Path

from pydantic_ai import Agent
from pydantic_ai_harness import CapabilityCreation

creation = CapabilityCreation(directory=Path('.authored'))
agent = Agent('anthropic:claude-sonnet-4-6', capabilities=[creation])

Các agent bây giờ có thể gọi author_capability, list_authored_capabilitiesvà disable_authored_capability. CapabilityCreation cũng đóng góp hướng dẫn nhắc hệ thống tĩnh, ổn định trong bộ đệm, giải thích các công cụ này. Rời khỏi guidance=None đối với văn bản mặc định hoặc chuyển chuỗi của riêng bạn; đặt guidance='' để bỏ qua nó hoàn toàn.

Ranh giới kích hoạt

Việc ghi và xác thực diễn ra trong lần chạy hiện tại; kích hoạt xảy ra trong lần chạy tiếp theo. Một khả năng không thể được thêm vào một lần chạy đang hoạt động. pydantic-ai giải quyết khả năng hiệu quả được thiết lập một lần khi bắt đầu mỗi lần chạy (khả năng gốc của lần chạy là cố định; không có trình thiết lập). Vì vậy, khả năng được tác giả sẽ có sẵn trên tiếp theo agent.run(...), không phải hoạt động đã tạo ra nó. Tác giả viết và xác thực khả năng ngay lập tức, nhưng các công cụ và móc nối của nó chỉ tồn tại khi bộ công cụ và chuỗi khả năng của lần chạy tiếp theo được tập hợp khi bắt đầu chạy.

Hợp đồng tích hợp

Bộ điều phối điều khiển vòng lặp, do đó nó sở hữu hợp đồng một dòng: xâu chuỗi các khả năng hoạt động của cửa hàng vào mỗi lần chạy thông qua agent.run(..., capabilities=...). Với điều đó, khả năng được tạo sẽ hoạt động ở vòng lặp tiếp theo -- không cần khởi động lại quy trình:

from pathlib import Path

from pydantic_ai import Agent
from pydantic_ai_harness import CapabilityCreation

creation = CapabilityCreation(directory=Path('.authored'))
agent = Agent('anthropic:claude-sonnet-4-6', capabilities=[creation])

history = None
done = False
next_prompt = 'Start the task.'
while not done:
    extra = creation.store.load_active()
    result = await agent.run(next_prompt, message_history=history, capabilities=extra)
    history = result.all_messages()
    # ... decide `next_prompt` and `done` from `result` ...

creation.store được hỗ trợ bằng đĩa CapabilityStore trên cùng directory. store.load_active() nhập lại và xây dựng lại mọi khả năng được cấp phép đang hoạt động để đưa vào lần chạy tiếp theo. Các mục không tải được (nguồn bị hỏng, lỗi xây dựng) sẽ bị bỏ qua, không được nâng lên, vì vậy một khả năng kém sẽ không bao giờ chặn các mục còn lại.

Kiên trì

Các khả năng được ủy quyền vẫn tồn tại trên đĩa: mỗi khả năng là một <directory>/<name>.py tập tin, được lập chỉ mục bởi anh chị em manifest.json. Một quy trình mới sẽ chọn chúng bằng cách xây dựng một quy trình mới CapabilityCreation trên cùng directory và gọi store.load_active().

manifest.json ghi lại tên của từng khả năng, tệp mô-đun, tên lớp, trạng thái (active hoặc disabled) và lỗi xác thực cuối cùng. Đó là bề mặt mà UI có thể đọc để hiển thị những gì agent đã viết. Tệp kê khai được viết nguyên tử (tệp tạm thời cộng với os.replace), do đó, sự cố khi ghi giữa chừng không bao giờ để lại một phần tệp được đọc lại là "không có khả năng".

Tên khả năng phải là chữ cái viết thường, chữ số và dấu gạch dưới, bắt đầu bằng một chữ cái. Việc sử dụng lại tên sẽ thay thế khả năng trước đó của tên đó. Mã được nhập nhưng xác thực không thành công vẫn được ghi vào đĩa (để có thể kiểm tra) và được ghi bằng mã của nó. last_error thiết lập; load_active() bỏ qua nó.

Ranh giới tin cậy

CapabilityCreation thực thi Python tùy ý trong quá trình nhập, xây dựng và chạy. Đó chính là ranh giới tin cậy mà một agent đã chạy các lệnh shell và chỉnh sửa các tệp hoạt động theo đó, đây là sự lựa chọn có chủ ý ở đây. Đừng trỏ nó vào một thư mục có nội dung mà bạn không tự chạy và coi các khả năng được tác giả là mã mà agent đang thực thi trên máy chủ của bạn.

Bởi vì các khả năng được tạo ra giữ mã trực tiếp nên chúng không thể được tuần tự hóa theo thông số kỹ thuật (get_serialization_name() trả lại None) và được duy trì dưới dạng nguồn chứ không phải dưới dạng thông số agent.

đánh máy

Mã tác giả được nhập là động nhưng không được nhập Any quay trở lại harness: mọi giá trị được lấy từ mô-đun được tạo sẽ được thu hẹp bằng isinstance/issubclass trước khi sử dụng và các phiên bản đã tải sẽ được nhập AbstractCapability[object]. Bởi vì AgentDepsT là trái ngược nhau, một AbstractCapability[object] được chấp nhận bởi bất kỳ agent nào capabilities= tham số.

Tham chiếu API

::: pydantic_ai_harness.capability_creation.CapabilityCreation

::: pydantic_ai_harness.capability_creation.CapabilityStore