Khả năng tác giả

Khả năng khai thác phải là những cục pin nhỏ, có thể tổng hợp được xây dựng trên Pydantic AI nguyên thủy.

Chọn sự trừu tượng

• Sử dụng AbstractCapability khi tính năng đóng góp hướng dẫn, mô hình cài đặt, bộ công cụ, công cụ gốc hoặc móc vòng đời.
• Sử dụng một WrapperToolset khi tính năng này thay đổi cách hoạt động của bộ công cụ hiện có được trình bày hoặc được gọi.
• Dùng một chiếc lá AbstractToolset khi đối tượng địa lý sở hữu một bộ sưu tập công cụ mới.
• Sử dụng hook khi hành vi thuộc về một điểm cụ thể trong vòng đời của agent.
• Chỉ sử dụng thứ tự khả năng khi ngữ nghĩa thành phần yêu cầu. Giữ lý do hiển thị trong mã hoặc chuỗi tài liệu.

Nếu tính năng này thay đổi hành vi của dây cung cấp, cấu trúc thông báo được chuẩn hóa, ngữ nghĩa thực thi công cụ, lựa chọn đầu ra hoặc các nguyên tắc thực thi bền vững, nó có lẽ thuộc về lõi AI Pydantic đầu tiên.

Hình dạng công cộng

Mỗi gói khả năng thường có:

• __init__.py với xuất khẩu công cộng
• _capability.py cho lớp năng lực công cộng
• _toolset.py chỉ khi khả năng cần hành vi của bộ công cụ
• README.md với các tài liệu sử dụng tập trung (phục vụ GitHub và PyPI)
• một trang tài liệu hợp nhất tại docs/<capability>.md (cái docs/ thư mục phẳng -- không capabilities/ hoặc experimental/ thư mục con). Nó phản ánh README đối với trang tài liệu, bỏ huy hiệu, liên kết các trang khai thác khác với họ hàng .md liên kết và tài liệu Pydantic AI với root-relative /ai/... liên kết, liên kết của nó mô-đun nguồn, và -- khi khả năng bộc lộ một lớp công khai -- có thể kết thúc với một ::: pydantic_ai_harness.<Class> khối autodoc. README và cái này trang được giữ đồng bộ (xem review-checklist.md "Tài liệu").
• kiểm tra nhân đôi dưới tests/<capability>/

Gốc pydantic_ai_harness/__init__.py nên tái xuất công ổn định khả năng. Giữ người trợ giúp triển khai ở chế độ riêng tư trừ khi người dùng cần chúng.

Các mô-đun con khả năng và xuất khẩu

các experimental cấp đã ngừng hoạt động. ACP là thử nghiệm duy nhất còn lại khả năng (pydantic_ai_harness/experimental/acp/); không thêm khả năng mới ở đó.

Các khả năng mới xuất hiện dưới dạng mô-đun con cấp cao nhất pydantic_ai_harness/<name>/ VÀ được tái xuất một cách lười biếng từ thư mục gốc pydantic_ai_harness/__init__.py — Khả năng nhập khẩu cấp cao nhất là tiêu chuẩn (quy định 13/8): mọi lớp năng lực công cộng (và các hằng số công khai như DEFAULT_ALLOWED_COMMANDS) được thêm vào __all__, đến TYPE_CHECKING khối nhập khẩu và vào __getattr__ công văn. kẻ lười biếng __getattr__ mẫu là điều làm cho điều này trở nên an toàn với các phụ thuộc tùy chọn: việc nhập gói gốc không mang lại kết quả gì và truy cập vào một tên có cổng bổ sung không được cài đặt thêm sẽ làm tăng gợi ý cài đặt tiêu chuẩn ImportError. tests/test_placeholder.py::test_all_exports_are_importable thực thi hợp đồng - một PR khả năng mới bỏ qua quá trình xuất gốc sẽ không thành công. đế ngoại lệ là experimental (ACP), chỉ tồn tại ở mô-đun con. Tài liệu và ví dụ thích nhập cấp cao nhất (from pydantic_ai_harness import <Name>).

Khả năng đặt tên

Tên lớp tuân theo một quy tắc với hai nhánh:

1. Danh từ, khi khả năng đặt tên cho một vật: thứ mà mô hình có thể sử dụng -- một công cụ, khoa hoặc sự tích hợp (Shell, Memory, PydanticAIDocs); một hệ thống con với các cửa hàng, loại hoặc công cụ riêng của nó (CodeMode, StepPersistence, RepoContext, ToolOutputLimits); hoặc một chiến lược được đặt tên (SlidingWindowCompaction, TieredCompaction). Sử dụng danh từ tính năng tài liệu sẽ sử dụng.
2. Cụm động từ mệnh lệnh, khi khả năng tác động lên đường chạy và một động từ cụm từ nêu toàn bộ hợp đồng của nó (ClearToolResults, DeduplicateFileReads, WarnNearLimits, WarnOnCacheBusts). Tên nên đọc như một câu trả lời rõ ràng cho "điều này sẽ ảnh hưởng gì đến người đại diện của tôi?". Đừng gói hành động trong một danh nghĩa hóa (ToolResultEviction): dạng danh từ thêm hình thức, không phải thông tin. Nếu cụm động từ không đầy đủ hoặc chung chung, khả năng là một vùng tính năng - sử dụng nhánh 1.

Các ràng buộc bổ sung:

• Chữ đầu tiên của tên động từ phải đọc rõ ràng như một động từ. AuthorCapabilities thất bại điều này ("tác giả" đọc như một danh từ trước); chọn một động từ khác hoặc sử dụng một tên danh từ.
• Không viết tắt: PydanticAIDocs, không PyaiDocs.
• Đặt tên cho hành vi chứ không phải vấn đề mà nó giải quyết: ToolOutputLimits, không OverflowingToolOutput.
• Nếu danh từ tự nhiên đã đặt tên cho một loại công khai (thường là có thể gọi được gói khả năng, giống như lõi HistoryProcessor), khả năng cần có cụm động từ và danh từ vẫn dành riêng cho loại.
• Tích hợp của bên thứ ba mang tên nhà cung cấp (ExaSearch, ModalSandbox, LocalStack). Các sản phẩm thuộc họ Pydantic (Logfire) không cần đến nó.
• Mối quan hệ với người đương nhiệm: nhiều khả năng có thể chấp nhận được ở cả hai hình thức. Nếu tên vận chuyển hiện có không gây nhầm lẫn thì hãy giữ nguyên tên đó.

Đặt tên mô-đun: mô-đun một khả năng là snake_case của lớp nó (tool_output_limits); một nhóm các khả năng liên quan sẽ có được một mô-đun miền (compaction, guardrails); tích hợp nhà cung cấp có được mô-đun nhà cung cấp (exa, logfire). Một mô-đun cho mỗi khả năng, dòng hoặc nhà cung cấp. Thích dài hơn tên mô tả thay vì một tên ngắn gọn (ví dụ: tool_output_limits, không overflow). Nếu bạn không chắc chắn nên đặt tên cho một khả năng là gì, hãy hỏi người dùng (thông qua phần hỏi người dùng). tool) thay vì đoán -- một cái tên là một cam kết công khai sau khi được đưa ra.

Khi một lớp hoặc mô-đun được đổi tên, hãy giữ nguyên tên cũ trong ít nhất một phát hành: mô-đun được đổi tên giữ gói shim ở đường dẫn cũ và mô-đun được đổi tên lớp giữ mức mô-đun __getattr__ bí danh, cả hai đều phát ra HarnessDeprecationWarning thông qua những người trợ giúp trong pydantic_ai_harness/_warn.py.

Tái xuất cấp cao nhất trong pydantic_ai_harness/__init__.py (CodeMode, FileSystem, Shell, ManagedPrompt) là ngoại lệ, không phải là quy luật. Một lần xuất đã được xuất xưởng dưới dạng bản phát hành đã xuất bản, đây là bản có khả năng tương thích ngược cam kết: không di chuyển, đổi tên hoặc phá vỡ nó. Không thêm cấp cao nhất mới tái xuất khẩu.

API có thể thay đổi giữa các bản phát hành; phá vỡ các thay đổi không dùng tàu cảnh báo khi thực tế.

Thiết kế API

• Ưu tiên khả năng phân loại dữ liệu nhỏ với các trường được đánh máy.
• Đặt tên trường theo khái niệm người dùng, không theo cơ chế thực hiện.
• Chấp nhận các loại đầu vào hữu ích chung nhất.
• Tránh Any trong chữ ký công khai mới.
• Tránh bó bột. Thay vào đó, hãy sửa hình dạng loại.
• Giữ các giá trị mặc định vừa phải và dễ giải thích.
• Đầu ra công cụ giới hạn khả năng thực thi từ xa mới với max_output_bytes / max_output_lines (cái modal_sandbox tên), không phải là một cái mới đánh vần. Việc phát hành max_output_chars (vỏ) và max_read_lines (hệ thống tập tin) có trước quy ước này và duy trì tính tương thích.
• Độ lệch dòng trong các công cụ tệp đối diện với mô hình được lập chỉ mục 1, khớp grep -n, trình soạn thảo và dấu vết ngăn xếp (modal_sandbox là tài liệu tham khảo; filesystem là Di chuyển đang chờ xử lý dựa trên 0).

Chính sách tồn tại trong thành phần có thể cắm được

Khi một khả năng có sự phụ thuộc đằng sau một Protocol -- PlanStore, MemoryStore, khách hàng, hộp cát -- chính sách thử lại, dự phòng và xuống cấp thuộc về việc triển khai giao thức đó, không thuộc về các trường về khả năng.

Công việc của khả năng là nêu rõ nó sẽ làm gì khi phần phụ thuộc không thành công và giữ giao thức đủ nhỏ để bọc. Một người gọi muốn hành vi xuống cấp nhưng vẫn còn sống viết một triển khai gói; đó là những gì giao thức dành cho. Giải pháp thay thế là khả năng phát triển một on_x_error= trường cho mỗi phần phụ thuộc và kết thúc là sở hữu hành vi, nó không thể kiểm tra từ đầu đến cuối.

Ví dụ hoạt động: planninglời nhắc nhở ở đuôi của nó đọc PlanStore trên mọi mô hình yêu cầu, vì vậy một cửa hàng tăng giá không thành công. Planning không có khả năng xử lý lỗi núm vặn; README ghi lại hành vi và thay vào đó phác thảo một cửa hàng gói.

Đây là ranh giới tương tự như core-boundary.md, xuống một cấp: kia, khai thác không thực hiện lại ngữ nghĩa cốt lõi; ở đây, một khả năng không thực hiện lại nó chính sách hoạt động của người phụ thuộc.

Kiểm tra thành phần

Trước khi coi một khả năng là đã hoàn tất, hãy kiểm tra xem nó kết hợp như thế nào với:

• các khả năng khác tương tự Agent(..., capabilities=[...])
• bộ công cụ và bộ công cụ bao bọc
• ToolSearch
• công cụ trì hoãn và luồng phê duyệt
• công cụ dự phòng của nhà cung cấp và công cụ dự phòng cục bộ
• hành vi truyền phát/sự kiện khi khả năng phát ra hoặc kết thúc các sự kiện
• Khả năng có trạng thái hoặc khả năng ghi đè for_run, phải thực hiện công khai Agent đường dẫn với mọi khả năng độ bền được hỗ trợ. Xác minh rằng các trình bao bọc bền vững giải quyết trạng thái và bộ công cụ chạy cục bộ. Nếu nhà nước không thể tồn tại trong ranh giới hoạt động, xử lý hoặc phát lại, thất bại trước công cụ đầu tiên gọi và ghi lại sự không tương thích.

CodeMode là một tài liệu tham khảo hữu ích cho thành phần bộ công cụ bao bọc, công cụ lựa chọn, ToolSearch tương tác, tài liệu công cộng và độ sâu kiểm tra.

Dấu chân CI và phụ thuộc

Hầu hết các khả năng đều bổ sung thêm một gói và một mô-đun thử nghiệm, giá rẻ. Một số kéo máy móc nặng hơn: hình ảnh Docker, một dịch vụ bên ngoài cần bí mật hoặc token xác thực, mã nhị phân hệ thống lớn (CL đám mây) hoặc các cuộc gọi mạng trực tiếp. Đó máy móc làm cho CI chậm hơn và dễ bị lỗi hơn, và mọi PR không liên quan sẽ nếu không thì phải trả giá cho nó trên con đường quan trọng.

Khi một khả năng cần máy móc có trọng lượng đó:

• Giữ sự phụ thuộc runtime của nó đằng sau phần bổ sung của chính khả năng đó, do đó việc nhập gói gốc không bao giờ kéo nó vào (xem "Các mô-đun con và xuất khẩu khả năng").
• Phạm vi công việc CI đắt tiền của nó theo khả năng. A changes công việc so sánh các cam kết cơ bản và đầu của sự kiện với các đường dẫn của khả năng, và công việc nặng nhọc chỉ diễn ra khi PR hoặc chi nhánh đẩy họ vào. Chạy công việc nặng nhọc vô điều kiện đối với các thẻ nên các bản phát hành vẫn thực hiện đường dẫn trực tiếp: if: always() && (github.ref_type == 'tag' || needs.changes.outputs.<name> == 'true').
• Giữ lại tổng hợp check công việc có màu xanh khi công việc nặng được bỏ qua nhưng có màu đỏ khi nó chạy và thất bại. re-actors/alls-green với allowed-skips: changes, <heavy-job> thực hiện cả hai: bỏ qua không chặn, thực thất bại vẫn bỏ phiếu.
• Cấp cho changes công việc pull-requests: read. Không cần thanh toán, bộ lọc đường dẫn liệt kê các tệp PR thông qua API GitHub, cần có phạm vi đó. Một repository công khai cho phép nó dưới contents: read, nhưng nó không thành công trên một repository riêng tư hoặc dưới thắt chặt phạm vi token mặc định.
• Phạm vi bất kỳ bí mật nào cho bước cần đến nó (không phải công việc env) và ràng buộc công việc đến một CI environment giữ bí mật nên các bước thanh toán và thiết lập không bao giờ nhìn thấy nó.

các localstack khả năng của localstack-integration công việc là tài liệu tham khảo cho hình dạng này. Liệu các khối công việc nặng có được hợp nhất hay không (được liệt kê trong check's needs) hoặc chỉ có tín hiệu là quyết định của chủ sở hữu khả năng; nêu rõ điều đó trong PR.

Giả định và làm mới dịch vụ bên ngoài

Khả năng bao bọc một dịch vụ, hình ảnh hoặc CLI bên ngoài (localstack, modal_sandbox, exa, macroscope) phụ thuộc vào các sự kiện tồn tại bên ngoài điều này repo và thay đổi theo lịch trình của nhà cung cấp: yêu cầu xác thực, kiểm soát phiên bản hành vi, cổng mặc định, điểm cuối, định dạng dây. Khi một trong số đó thay đổi khả năng có thể bị hỏng theo cách mà các thử nghiệm cục bộ bỏ lỡ (trình mô phỏng hoặc API bị chế nhạo hoặc vắng mặt). Ghi lại các giả định về khả năng chịu tải để agent trong tương lai có thể làm mới chúng một cách có chủ ý thay vì tìm lại chúng từ thất bại.

Đối với mỗi khả năng như vậy, hãy giữ một khối ngắn -- một chuỗi tài liệu mô-đun hoặc một nhận xét gần các hằng số mà nó ghim -- liệt kê từng giả định bên ngoài cùng với ngày tháng nó đã được xác minh lần cuối và một liên kết đến nguồn có thẩm quyền và cho biết cách kiểm tra lại nó. Trước khi thay đổi cách xử lý xác thực, phiên bản hoặc giao thức, hãy xác minh lại những giả định có liên quan trước tiên đối với những nguồn đó. Khi bạn xác nhận một vẫn còn giữ, va chạm ngày của nó; khi nó thay đổi, hãy cập nhật mã và ngày cùng nhau.

localstack là ví dụ hoạt động (đã được xác minh 2026-07):

• Mặc định localstack/localstack hình ảnh yêu cầu LOCALSTACK_AUTH_TOKEN để bắt đầu kể từ LocalStack 2026.03.0; thẻ trước 2026.03.0 (ví dụ: 4.x) chạy không có token. Nguồn: https://docs.localstack.cloud/aws/getting-started/auth-token/.
• Cổng cạnh 4566; sức khỏe tại /_localstack/health; localhost.localstack.cloud quyết tâm 127.0.0.1 (cần thiết cho việc đánh địa chỉ kiểu tên miền phụ S3). Nguồn: https://docs.localstack.cloud/aws/capabilities/config/configuration/.
• AWS CLI chấp nhận mọi tiền tố rõ ràng của tùy chọn chung (--endpoint cho --endpoint-url) và giá trị cuối cùng thắng nên bộ bảo vệ lệnh từ chối tiền tố của các hình cầu bị cấm, không chỉ tên chính xác. Xác minh lại đối với đã cài đặt aws CLI nếu bảo vệ đó thay đổi.

Tài liệu

Mỗi khả năng hướng tới người dùng đều cần các tài liệu gần với mã. Giải thích:

• nó giải quyết được vấn đề gì
• sử dụng tối thiểu
• tùy chọn chính
• cách nó kết hợp với các tính năng Pydantic AI có liên quan
• các ràng buộc quan trọng về an toàn hoặc thực thi

Giữ các ví dụ có thể chạy được với các tính năng bổ sung đã khai báo.