Custom agents

Mỗi cài đặt, phương thức và trường làm gì. Nếu bạn lần đầu tiên cấu hình, hãy bắt đầu bằng hướng dẫn — trang này dành cho việc tra cứu.

Hướng dẫn custom agents

Cài đặt, cấu hình, các phương thức sự kiện, một ví dụ chi tiết và các vấn đề thường gặp.

Đang dùng framework?

LangChain, CrewAI, LlamaIndex và Pydantic AI tự cấu hình với một lệnh gọi.

Python 3.10 hoặc mới hơn. Không có phụ thuộc thời gian chạy.

Cài đặt

pip install failproofai-sdk

Gói được cài đặt dưới dạng failproofai-sdk và nhập trong Python dưới dạng failproofai_sdk. Các tính năng bổ sung của framework như failproofai-sdk[langgraph] cài đặt framework; các adapter luôn được đi kèm trong wheel cơ bản.

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ấu hì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 environment, và mở trace được tái tạo.

Đọc khóa events:add vào shell. read -s nhận nó ở một lời nhắc không được hiển thị, do đó nó không bao giờ xuất hiện trong lệnh hoặc lịch sử shell:

read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN

Sau đó thiết lập máy và kiểm tra xem nó đã kết nối:

failproofai config
failproofai config --status

Cấu hình

import failproofai_sdk

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

Tham 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 theo 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 trường hợp nhãn thuộc về triển khai chứ không phải ứng dụng. Tham số `configure()` sẽ được ưu tiên.
`FAILPROOFAI_HOME`	Di chuyển gốc Failproof AI chứa spool.
`FAILPROOFAI_SDK_STRICT`	`1` làm cho lỗi cấu hình tăng thay vì được ghi lại.
`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 đó trên dấu phẩy để xây dựng các bộ lọc và bỏ qua bất kỳ sự kiện nào có nhãn chứa một — vì vậy toàn bộ lần chạy biến mất âm thầm. Viết prod-eu, không phải prod,eu.configure(environment="prod,eu") tăng để bạn tìm 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 ở chế độ nền mỗi flush_interval giây, với một lần xóa cuối cùng khi thoát thông dịch viên. Một quy trình bị giết hoàn toàn mất bất cứ điều gì chưa được ghi.

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 cả hai, vì vậy bạn hiếm khi chuyển chúng:

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

Chuyển session_id hoặc agent_id một cách rõ ràng vẫn hoạt động và thắng. Không có cả ràng buộc lẫn được truyền, cuộc gọi tăng TypeError chứ không phải phát thải một sự kiện Cloud sẽ yên lặng loại bỏ.

Danh tính di trên các biến ngữ cảnh. Nó theo asyncio tự động, nhưng không các luồng mới — bao quanh công nhân trong failproofai_sdk.propagate() hoặc sự kiện của nó hạ cánh không được gắn.

Danh mục sự kiện

Mười lăm phương thức. Hầu hết đi theo cặp — bạn gọi bộ mở, sau đó bộ đó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 tự đứng: error, human_pause, human_interrupt.

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

Mỗi phương thức cũng có session_id và agent_id, mà các phạm vi điền cho bạn. Bất cứ điều gì để lại là None được thả ra chứ không phải đượ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 lần chạy là thất bại, outcome phải là một trong số failed, error, timeout hoặc rejected. Bất cứ điều gì khác — kể cả gần như thất bại "failure" — đếm là thành công.

Ghép đôi và thời lượng

Một quy tắc: cho sự kiện đóng cùng id với bộ mở của nó. Đó là những gì ghép đôi chúng, và những gì cho phép SDK đo khoảng thời gian.

Cặp	Khớ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 tự truyền duration_ms. 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. Chuyển một số nguyên của mili giây — một float tăng, bởi vì cột là một số nguyên 32-bit và sẽ hạ cánh trống.

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

Id chỉ cần phải là duy nhất cho mỗi loại, mỗi phiên. Một lệnh gọi công cụ và một móc có thể chia một; hai phiên chạy cùng lúc có thể tái sử dụng cùng các id mà không va chạm.
Chúng không được phạm vi vào một agent. Một cặp mở dưới một agent và đóng dưới một agent khác vẫn khớp — đó là trường hợp bình thường trong mã đa agent.
request_id là tùy chọn nhưng được khuyến khích. 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 lệnh gọi đồng thời trong cùng một agent có thể sai lệch.
Một cặp chia tách trên các quy trình vẫn khớp trong Cloud, nhưng SDK không thể đo nó — không có gì trong quy trình nào thấy cả hai nửa.
Nhiều nhất 10,000 bộ mở chờ một bộ đóng cùng một lúc. Quá điều đó, bộ cũ nhất bị thả, vì vậy rò rỉ không thể phát triển mà không bị ràng buộc.

Trường của riêng bạn

Bất kỳ từ khóa bổ sung nào bạn chuyể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
)

Ưu tiên các 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 tập hợp, byte, 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. Các cái bổ sung đượ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 lặng ghi đè trường thực. 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 sai chính tả không bao giờ xảy ra 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, 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.

Phân phối 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, móc 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, kiểm tra $FAILPROOFAI_HOME/custom-agents/events, nếu không ~/.failproofai/custom-agents/events. Các tệp JSONL chứng minh phát thải SDK; một spool phát triển trỏ đến cấu hình daemon hoặc phân phối, trong khi một spool trống trỏ đến cấu hình hoặc thời lượng quá trình.

Chỉ kiểm tra spool khi daemon được dừng. Khi nó chạy, nó thu thập và xóa mỗi lô trong vài 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 sự kiện được phát thải.

Ngăn ngừa lỗi trong thời gian chạy tùy chỉnh

Sử dụng các phát hiện kiểm toán và các trace đượ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 hiển thị hành động trước khi thực thi, chuyển đầu vào có cấu trúc của nó đến công cụ chính sách và áp dụng quyết định cho phép, hướng dẫn hoặc từ chối 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à vòng đời của thời gian chạy của bạn tới các móc 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

Đang dùng 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à thời lượng

Trường của riêng bạn

Phân phối và xác minh

Ngăn ngừa lỗi trong thời gian chạy tùy chỉnh

Hướng dẫn custom agents

Đang dùng 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à thời lượng

​Trường của riêng bạn

​Phân phối và xác minh

​Ngăn ngừa lỗi trong thời gian chạy 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à thời lượng

Trường của riêng bạn

Phân phối và xác minh

Ngăn ngừa lỗi trong thời gian chạy tùy chỉnh