Custom agents

Tất cả những gì mỗi thiết lập, phương thức và trường làm. Nếu bạn đang điều chỉnh lần đầu tiên, hãy bắt đầu với hướng dẫn — trang này dành cho việc tra cứu.

Hướng dẫn Custom agents

Cài đặt, điều chỉnh, các phương thức sự kiện, ví dụ thực tế và các vấn đề phổ biến.

Sử dụng một framework?

LangChain, CrewAI, LlamaIndex và Pydantic AI tự điều chỉnh với một cuộc gọi.

Python 3.10 trở lên. Không có phụ thuộc runtime.

Cài đặt

pip install failproofai-sdk

Gói được cài đặt dưới tên failproofai-sdk và được nhập trong Python dưới tên failproofai_sdk. Các add-on framework như failproofai-sdk[langgraph] cài đặt chính framework; các adapter luôn được đi kèm trong wheel cơ sở.

Kết nối daemon Failproof

Dashboard
CLI

Đi tới Admin → Keys và tạo một khóa với events:add.
Kết nối daemon Failproof với Cloud trên máy agent.
Chạy một phiên được điều chỉnh, sau đó tìm ID chính xác của nó trong Observe → Events.
Đi tới Observe → Sessions, chọn cùng một môi trường và mở trace được tái tạo.

failproofai config \
  --connect https://app.befailproof.ai \
  --token <events-add-key>
failproofai config --status

Cấu hình

import failproofai_sdk

failproofai_sdk.configure(
    base_dir=None,
    flush_interval=0.5,
    environment="production",
)

Đối số	Chức năng
`environment`	Nhãn trên mỗi sự kiện — `production`, `staging`, `prod-eu`. Mặc định là `dev`.
`flush_interval`	Tần suất luồng nền ghi vào đĩa, tính bằng giây. Mặc định là `0.5`.
`base_dir`	Nơi ghi. Mặc định là spool của daemon, đó là những gì bạn muốn trừ khi bạn biết cách khác.

Đặt bằng biến môi trường thay thế:

Biến	Chức năng
`AGENTEYE_ENVIRONMENT`	Đặt `environment` mà không thay đổi mã, cho khi nhãn thuộc về triển khai hơn là ứng dụng. Một đối số `configure()` sẽ ghi đè nó.
`FAILPROOFAI_HOME`	Chuyển gốc Failproof AI giữ spool.
`FAILPROOFAI_SDK_STRICT`	`1` làm cho lỗi điều chỉnh tăng thay vì được ghi nhật ký.
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1` làm cho vấn đề tương thích framework tăng thay vì cảnh báo và tiếp tục.

Không có dấu phẩy trong environment. Ingest chia trường đó thành dấu phẩy để xây dựng các bộ lọc của nó, và bỏ qua bất kỳ sự kiện nào có nhãn chứa một sự kiện — vì vậy toàn bộ chạy im lặng biến mất. Viết prod-eu, không phải prod,eu.configure(environment="prod,eu") tăng để bạn phát hiện ra ngay lập tức. AGENTEYE_ENVIRONMENT không thể tăng — không có gì gọi bạn — vì vậy nó cảnh báo một lần và quay lại dev.

Các sự kiện được xếp hàng trong bộ nhớ và được ghi trong nền mỗi flush_interval giây, với một lần xóa cuối cùng khi thoát trình thông dịch. Một quá trình bị giết hoàn toàn sẽ mất bất cứ điều gì chưa được viết.

Danh tính

Mỗi sự kiện thuộc về một phiên và một agent. Các phạm vi điền vào cả hai, vì vậy bạn hiếm khi vượt qua chúng:

with failproofai_sdk.session():
    with failproofai_sdk.agent("planner"):
        failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1")

Truyền session_id hoặc agent_id rõ ràng vẫn hoạt động và chiến thắng. Khi không có liên kết cũng không truyền, cuộc gọi tăng TypeError thay vì phát hành một sự kiện Cloud sẽ yên tĩnh loại bỏ.

Danh tính đi trên các biến bối cảnh. Nó theo dõi các tác vụ asyncio tự động, nhưng không luồng mới — bọc một worker trong failproofai_sdk.propagate() hoặc các sự kiện của nó hạ cánh không được đính kèm.

Danh mục sự kiện

Mười lăm phương thức. Hầu hết đều có cặp — bạn gọi phần mở, sau đó phần đóng, và SDK đo khoảng thời gian.

	Mở	Đóng
Agents	`agent_start`	`agent_end`
	`agent_pause`	`agent_resume`
Models	`model_request`	`model_response`
Tools	`tool_use`	`tool_result`
Hooks	`hook_triggered`	`hook_completed`
Humans	`human_wait`	`human_input`

Ba người đứng một mình: error, human_pause, human_interrupt.

Mọi trường, theo phương thức

Mỗi phương thức cũng lấy session_id và agent_id, được các phạm vi điền cho bạn. Bất cứ điều gì để lại là None được thả bỏ thay vì được gửi dưới dạng JSON null, và mỗi phương thức trả về None.

Phương thức	Bắt buộc	Tùy chọn
`agent_start`	—	`goal`, `parent_id`
`agent_end`	—	`outcome`, `summary`
`agent_pause`	`pause_id`	`reason`, `user_id`
`agent_resume`	`pause_id`	`reason`, `user_id`
`model_request`	—	`model`, `messages`, `system`, `tools`, `request_id`
`model_response`	—	`model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`, `request_id`, `duration_ms`
`tool_use`	`tool_name`, `tool_call_id`	`input`
`tool_result`	`tool_name`, `tool_call_id`	`output`, `error`
`hook_triggered`	`hook_name`, `hook_id`	`trigger_event`, `input`
`hook_completed`	`hook_name`, `hook_id`	`outcome`, `output`, `error`
`error`	`error_type`, `message`	`traceback`
`human_wait`	`input_id`	`prompt`, `options`, `reason`
`human_input`	`input_id`	`response`
`human_pause`	—	`reason`, `user_id`
`human_interrupt`	—	`reason`, `user_id`, `at_step`

Để đánh dấu một chạy là thất bại, outcome phải là một trong failed, error, timeout hoặc rejected. Bất cứ điều gì khác — bao gồm cả lần gần phát hiểu "failure" — đếm là thành công.

Ghép đôi và khoảng thời gian

Một quy tắc: cung cấp cho sự kiện đóng cùng id với phần mở của nó. Đó là điều ghi đôi chúng, và điều cho phép SDK đo khoảng thời gian.

Cặp	Phù hợp với
`tool_use` → `tool_result`	`tool_call_id`
`hook_triggered` → `hook_completed`	`hook_id`
`agent_pause` → `agent_resume`	`pause_id`
`human_wait` → `human_input`	`input_id`
`model_request` → `model_response`	`request_id`

Không truyền duration_ms chính mình. SDK đo nó, và truyền nó tăng ValueError. Ngoại lệ duy nhất là model_response, nơi chỉ bạn biết độ trễ nhà cung cấp thực tế. Truyền toàn bộ số mili giây — một float tăng, vì cột là một số nguyên 32-bit và sẽ khác không hạ cánh trống.

Các trường hợp cạnh

Ids chỉ cần duy nhất cho mỗi loại, mỗi phiên. Một cuộc gọi công cụ và một hook có thể chia sẻ một; hai phiên chạy cùng một lúc có thể tái sử dụng cùng một ids mà không va chạm.
Chúng không được phạm vi để một agent. Một cặp mở dưới một agent và đóng dưới một agent khác vẫn phù hợp — đó là trường hợp bình thường trong mã multi-agent.
request_id là tùy chọn nhưng được khuyến nghị. Không có nó, các sự kiện mô hình ghép đôi theo thứ tự họ tới, vì vậy hai cuộc gọi đồng thời trong cùng một agent có thể ghép đôi sai.
Một cặp chia nhỏ trên các quá trình vẫn khớp trong Cloud, nhưng SDK không thể đo nó — không có gì trong quá trình nào thấy cả hai nửa.
Tối đa 10.000 openers chờ đợi một closer cùng một lúc. Quá mức, người già nhất bị thả, vì vậy một rò rỉ không thể phát triển mà không bị ràng buộc.

Các trường riêng của bạn

Bất kỳ từ khóa bổ sung nào bạn truyền được lưu trữ với sự kiện:

failproofai_sdk.event.tool_use(
    tool_name="search", tool_call_id="c1",
    fw_tenant="acme", fw_region="eu-west-1",     # của bạn riêng
)

Thích loại JSON nếu bạn muốn truy vấn chúng sau này. Bất cứ điều gì khác — một UUID, một datetime, một Decimal, một set, bytes, một đối tượng mô hình — được lưu trữ dưới dạng chuỗi.

Tiền tố tên trường của bạn. Extras được áp dụng cuối cùng, vì vậy một trường được gọi là model, tool_name hoặc outcome yên tĩnh ghi đè lên một thực tế. Các adapter framework sử dụng fw_; làm như vậy và không có gì có thể va chạm.Đây cũng là lý do tại sao một trường tùy chọn được viết sai không bao giờ lỗi — nó chỉ trở thành một trường tùy chỉnh mới. Nếu một trường tiêu chuẩn bị thiếu trong Cloud, hãy kiểm tra chính tả trước tiên.

Năm tên này được dành riêng và bị từ chối hoàn toàn: timestamp, session_id, agent_id, type, environment.

Gửi dữ liệu và xác minh

Dashboard
CLI

Trong Observe → Events, xác minh agent_start tồn tại trước tiên và agent_end tồn tại cuối cùng. Sau đó mở Observe → Sessions và xác nhận các sự kiện mô hình, công cụ, con người, hook và lỗi xuất hiện theo thứ tự dự định. Sử dụng ID phiên làm khóa khắc phục sự cố chính.

failproofai flush --wait --timeout 60
failproofai config --status
fp sessions --since 1h --env production --session-id <session-id>
fp events --since 1h --session-id <session-id> --full

Nếu Cloud trống, hãy kiểm tra $FAILPROOFAI_HOME/custom-agents/events, nếu không thì ~/.failproofai/custom-agents/events. Các tệp JSONL chứng minh phát hành SDK; một spool phát triển chỉ đến cấu hình daemon hoặc gửi dữ liệu, trong khi một spool trống chỉ đến điều chỉnh hoặc thời lượng quá trình.

Chỉ kiểm tra spool khi daemon bị dừng. Khi nó chạy, nó thu thập và xóa từng batch trong vòng mili giây, vì vậy danh sách thư mục đua với bộ sưu tập và hiển thị ít sự kiện hơn nhiều so với những gì được phát hành.

Ngăn chặn lỗi trong runtime tùy chỉnh

Sử dụng các phát hiện kiểm tra và dấu vết được liên kết để xác định hành động không an toàn, bằng chứng bắt buộc và phản ứng dự định. Một tích hợp thực thi tùy chỉnh phải tiếp xúc hành động trước khi thực thi, chuyển đầu vào có cấu trúc của nó cho công cụ chính sách và áp dụng quyết định allow, instruct hoặc deny kết quả. Liên hệ Failproof AI và chúng tôi sẽ giúp bạn ánh xạ các ranh giới mô hình, công cụ và chu kỳ sống của runtime của bạn với các hook chính sách, sau đó xác thực tích hợp với bạn.

Connect your agents

Reference

Hướng dẫn Custom agents

Sử dụng một framework?

Cài đặt

Kết nối daemon Failproof

Cấu hình

Danh tính

Danh mục sự kiện

Ghép đôi và khoảng thời gian

Các trường riêng của bạn

Gửi dữ liệu và xác minh

Ngăn chặn lỗi trong runtime tùy chỉnh

Hướng dẫn Custom agents

Sử dụng một framework?

​Cài đặt

​Kết nối daemon Failproof

​Cấu hình

​Danh tính

​Danh mục sự kiện

​Ghép đôi và khoảng thời gian

​Các trường riêng của bạn

​Gửi dữ liệu và xác minh

​Ngăn chặn lỗi trong runtime tùy chỉnh

Cài đặt

Kết nối daemon Failproof

Cấu hình

Danh tính

Danh mục sự kiện

Ghép đôi và khoảng thời gian

Các trường riêng của bạn

Gửi dữ liệu và xác minh

Ngăn chặn lỗi trong runtime tùy chỉnh