Cài đặt
Công cụ hóa
session_id và agent_id. Các phạm vi liên kết danh tính trên các biến ngữ cảnh và mỗi lệnh gọi sự kiện đọc lại nó, vì vậy bạn không bao giờ phải điều phối các id thông qua các hàm của bạn.
Cả ba đều hoạt động dưới async with cũng như with.
Lồng các agent xây dựng cây. parent_id và độ sâu được tính từ ngăn xếp:
Cách một phạm vi đóng lại
agent() xử lý ngoại lệ cho bạn:
agent_end, bởi vì bảng điều khiển đóng span tại agent_end và bất cứ điều gì sau đó được quy cho không có gì. Hủy bỏ không phải là thất bại, vì vậy các lần chạy bị hủy không làm ô nhiễm bề mặt lỗi. Ngoại lệ luôn được nâng lại: một phạm vi không bao giờ nuốt chửng.
Các phương thức sự kiện
Mười năm phương thức trong sáu gia đình. Hầu hết đều đi thành cặp — bạn phát ra phần mở, sau đó là phần đóng, và SDK đo khoảng thời gian giữa chúng.Ví dụ
Một vòng lặp gọi công cụ trên API OpenAI, không có framework agent:docs/manual/examples/.
Luồng và async
Các biến ngữ cảnh lan truyền vào các tác vụ asyncio một cách tự động. Họ không lan truyền vào các luồng mới, bởi vì một luồng bắt đầu với một ngữ cảnh trống.propagate(), sự kiện của worker sẽ tăng lên một TypeError đặt tên cho phần sửa chữa chứ không là đếm không có session. Điều này cố ý: một sự kiện không có session bị bỏ qua bằng cách nhập và trả lời 200, đó là lỗi im lặng mà lớp danh tính tồn tại để ngăn chặn.
Công cụ hóa một framework mà không có adapter
Mỗi framework agent cung cấp cho bạn ba đường nối tương tự. Ánh xạ chúng và bạn có một dấu vết hoàn chỉnh — bốn adapter được gửi không làm gì nhiều hơn thế.Dấu ngoặc lần chạy
Dấu ngoặc mỗi công cụ
Ghép mỗi lệnh gọi mô hình
Tại sao không có adapter AutoGen
Tại sao không có adapter AutoGen
autogen-coređã không được bảo trì kể từ tháng 9 năm 2025.- AG2 không cung cấp điểm đăng ký toàn bộ quy trình tương đương với các hook của các framework khác, vì vậy công cụ hóa nó có nghĩa là bao bọc mỗi agent ở mỗi trang xây dựng.
Đi sâu hơn
Cách ghi âm thực sự hoạt động. Không cần thiết phải bắt đầu.Một bản ghi trông như thế nào, trên mỗi framework
Một bản ghi trông như thế nào, trên mỗi framework
- LangGraph
- CrewAI
- LlamaIndex
- Pydantic AI
- Custom agents
Cách một phiên bắt đầu và kết thúc
Cách một phiên bắt đầu và kết thúc
session_id.Trạng thái được lấy từ hình dạng của dấu vết:agent_end cho bạn, và khi phân hủy chúng đóng bất cứ thứ gì vẫn mở và đánh dấu nó không đầy đủ — một lần chạy bị lỗi giải quyết dưới dạng done với một khoảng trống có thể nhìn thấy chứ không phải treo mãi mãi.interrupt() LangGraph tạm dừng lần chạy, span gốc cố ý để mở, và lệnh gọi tiếp tục đóng nó. Cả hai lệnh gọi là một phiên.Danh tính: session_id, agent_id, và ai tạo ra chúng
Danh tính: session_id, agent_id, và ai tạo ra chúng
session_id và agent_id là tùy chọn trên mỗi phương thức sự kiện. Bỏ qua, chúng giải quyết từ phạm vi bao quanh:TypeError đặt tên cho phần sửa chữa chứ không phải phát ra sự kiện không có phiên, cái mà ingest sẽ bỏ qua trong khi trả lời 200.Phạm vi liên kết danh tính trên các biến ngữ cảnh. Những cái đó lan truyền vào các tác vụ asyncio một cách tự động nhưng không vào các luồng mới — bao một worker trong failproofai_sdk.propagate().Ai tạo ra id nào
Cách các adapter giải quyết session_id
Trận đấu đầu tiên thắng:- Một
session_idtùy chọn rõ ràng - Siêu dữ liệu trên mỗi cuộc gọi
- Phạm vi
session()bao quanh - Siêu dữ liệu framework
- Id chạy của riêng framework
Giữ agent_id cardinality thấp
Đó là khía cạnh chính trên mỗi bề mặt bảng điều khiển, và một cột LowCardinality(String). Một giá trị trên mỗi lần chạy làm giảm cột và lấp đầy thả xuống bộ lọc với một mục nhập trên mỗi lần chạy.Các adapter bảo vệ cột đó cho bạn:fw_agent_id / fw_run_id, nơi nó vẫn có thể truy vấn được mà không là một khía cạnh.Loại sự kiện, được nhóm — và framework nào ghi lại cái gì
Loại sự kiện, được nhóm — và framework nào ghi lại cái gì
human_pause và human_interrupt mô tả một người hành động trên agent, mà không có framework nào báo hiệu — tự phát ra những cái đó.Cặp, tương quan và khoảng thời gian
Cặp, tương quan và khoảng thời gian
Quy tắc tương quan
- Tái sử dụng cùng
tool_call_id,hook_id,pause_id, hoặcinput_idcho sự kiện hoàn thành phù hợp. - SDK tính toán
duration_mschotool_result,hook_completed,agent_resume, vàhuman_input. Chuyển nó cho những phương thức đó tăngValueError. duration_msđược chấp nhận trênmodel_response, bởi vì chỉ người gọi biết độ trễ nhà cung cấp thực sự. Nó phải là một số nguyên — một float tăngValueErrortại trang gọi, bởi vì máy chủ đọc cột dưới dạng số nguyên 32-bit không dấu và sẽ lưu trữ NULL cho bất cứ điều gì khác.- Khóa tương quan được phạm vi theo loại và phiên, vì vậy lệnh gọi công cụ và một hook có thể an toàn chia sẻ một id, và hai phiên đồng thời có thể tái sử dụng các id giống nhau mà không va chạm. Chúng không được phạm vi bởi agent: một cặp mở dưới một agent và đóng dưới một agent khác vẫn tương quan, đó là trường hợp thông thường trong các framework đa agent.
request_idghépmodel_requestvớimodel_response. Nếu không có nó, các sự kiện mô hình ghép theo thứ tự trên mỗi agent, vì vậy các lệnh gọi đồng thời bị ghép sai.- Một cặp phân tách qua các quy trình vẫn tương quan xuôi dòng, nhưng SDK không thể tính toán khoảng thời gian trong quy trình của nó.
- Bản đồ chờ đợi giữ tối đa 10.000 bắt đầu và loại bỏ mục nhập cũ nhất khi đầy.
Cái gì trong gói, và cách instrument() tìm framework của bạn
Cái gì trong gói, và cách instrument() tìm framework của bạn
failproofai-sdk cài đặt mọi thứ, cả bốn adapter được bao gồm. Các extras kéo framework, không phải adapter.import failproofai_sdk được hợp đồng không phụ thuộc, được thực thi bởi một bài kiểm tra cài đặt bánh xe xây dựng với --no-deps và một bài kiểm tra khác chứng minh không có framework nào đến sys.modules.sys.modules, không phải danh sách gói được cài đặt, vì vậy một framework bạn đã cài đặt nhưng không bao giờ nhập không được công cụ hóa và không bao giờ được nhập thay bạn. Để xem những gì được kết nối:instrument("crewai") trên máy không có CrewAI không tăng. Nó ghi một cảnh báo và trả về (), vì vậy một framework bị thiếu không bao giờ hạ một quy trình cũng công cụ hóa những cái khác.Cảnh báo mang theo ImportError cơ bản, và tin nhắn đó đặt tên cho lệnh cài đặt chính xác — vì vậy bản sửa chữa nằm trong nhật ký của bạn, không bị ẩn.FAILPROOFAI_SDK_STRICT=1 để làm cho nó tăng thay thế. Cờ đó được đọc một lần và được lưu trong bộ đệm, vì vậy xuất khẩu nó trước khi quy trình của bạn bắt đầu chứ không phải đặt nó giữa cuộc chạy.Cách sự kiện đạt tới Cloud
Cách sự kiện đạt tới Cloud
.tmp đầu tiên, sau đó fsync, sau đó một đổi tên nguyên tử:.jsonl, vì vậy nó không bao giờ có thể đọc một tệp nửa viết. Thân phần mang một dấu thời gian, id quy trình và số thứ tự, vì vậy hai quy trình xóa trong cùng một mili giây không thể va chạm. Hàng đợi bị giới hạn ở 10.000 sự kiện; quá điểm đó, nó bỏ cái cũ nhất và ghi nhật ký.Daemon tàu lô của bạn. Nó không mở hoặc viết lại chúng.ls đua với bộ sưu tập và cho thấy một phần nhỏ những gì bạn phát ra — không thể phân biệt với một SDK không ghi lại được gì.Để xác nhận các sự kiện thực sự hạ cánh, kiểm tra bảng điều khiển. Để xem spool lấp đầy, dừng daemon trước tiên.Khi công cụ hóa thất bại
Khi công cụ hóa thất bại
try và mọi thứ SDK làm xảy ra bên ngoài nó.FAILPROOFAI_SDK_STRICT=1 để làm cho một thất bại bị nuốt chửng trở nên ồn ào.Vấn đề phổ biến
Một span không bao giờ kết thúc
Một span không bao giờ kết thúc
model_request không có model_response, hoặc một tool_use không có tool_result. Sử dụng các phạm vi, chúng đảm bảo cặp ngay cả khi phần nội dung tăng. Nếu bạn gọi các phương thức sự kiện trực tiếp, sử dụng try và finally.Chuyển duration_ms tăng ValueError
Chuyển duration_ms tăng ValueError
tool_result, hook_completed, agent_resume, và human_input. Nó được chấp nhận trên model_response, bởi vì chỉ bạn biết độ trễ nhà cung cấp thực sự, và nó phải là một số nguyên.Sự kiện từ luồng worker tăng TypeError
Sự kiện từ luồng worker tăng TypeError
callable trong failproofai_sdk.propagate(). Xem Luồng và async.Một trường bổ sung biến mất hoặc ghi đè cái gì đó
Một trường bổ sung biến mất hoặc ghi đè cái gì đó
model hoặc outcome sẽ ghi đè nó và thay đổi một cột được lưu trữ. Không gian tên của bạn; các adapter sử dụng tiền tố fw_.Bộ lọc agent có hàng nghìn mục
Bộ lọc agent có hàng nghìn mục
agent_id là một khía cạnh cardinality thấp và bạn để một id chạy vào nó. Sử dụng một vai trò hoặc tên nút và để id thực vào một trường tải trọng.
