Python SDK - FailproofAI

AgentEye Python SDK cung cấp cho bạn khả năng theo dõi toàn diện hành vi của các agent (mọi lần chạy agent, lệnh gọi tool, yêu cầu mô hình, hook và can thiệp của con người) để bạn có thể gỡ lỗi, kiểm toán và đánh giá chúng. Nó khởi tạo mã agent của bạn bằng cách ghi các sự kiện có cấu trúc vào các tệp JSONL cục bộ; daemon bộ sưu tập sẽ lấy những tệp này và tự động gửi chúng đến nền tảng.

Cài đặt

Tải tệp wheel từ GitHub Releases bằng AGENTEYE_TOKEN của bạn. Nếu bạn chưa có token, hãy xem Cài đặt Token GitHub để biết các bước cài đặt và quyền cần thiết. Sử dụng gh CLI + pip:

VERSION=0.0.1b9
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "python-sdk/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-*.whl'
pip install "agenteye-${VERSION}-py3-none-any.whl"

Sử dụng gh CLI + uv:

VERSION=0.0.1b9
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "python-sdk/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-*.whl'
uv add "./agenteye-${VERSION}-py3-none-any.whl"

Sử dụng curl (không có gh CLI):

VERSION=0.0.1b9
curl -fsSL \
  -H "Authorization: Bearer $AGENTEYE_TOKEN" \
  -L \
  "https://github.com/agenteye-enterprise/releases/releases/download/python-sdk%2Fv${VERSION}/agenteye-${VERSION}-py3-none-any.whl" \
  -o "agenteye-${VERSION}-py3-none-any.whl"
pip install "agenteye-${VERSION}-py3-none-any.whl"

Bắt Đầu Nhanh

import agenteye

agenteye.configure(environment="production")

agenteye.event.agent_start(session_id="run-001", agent_id="planner", goal="answer user query")

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",
    input={"query": "latest AI research"},
)

agenteye.event.tool_result(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",
    output={"results": ["..."]},
)

agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success")

configure()

agenteye.configure(
    base_dir=None,           # Path | str | None. Mặc định: $AGENTEYE_HOME hoặc ~/.agenteye
    flush_interval=0.5,      # float, giây giữa các chu kỳ flush
    environment=None,        # str | None. Nhãn môi trường triển khai
)

Gọi một lần trước bất kỳ lệnh gọi event.* nào. An toàn nếu bỏ qua; các giá trị mặc định hoạt động không vấn đề. Tất cả các đối số chỉ dùng từ khóa; hãy truyền chúng theo tên như được hiển thị ở trên. Khi base_dir là None (mặc định), SDK đọc $AGENTEYE_HOME nếu được đặt, nếu không sẽ quay lại ~/.agenteye. Điều này phù hợp với cách phân giải của bộ sưu tập, do đó một biến env AGENTEYE_HOME duy nhất sẽ cấu hình bộ spool sự kiện dùng chung cho cả SDK và bộ sưu tập, cần thiết cho các triển khai sidecar / single-pod nơi cả hai quy trình phải thống nhất về đường dẫn bộ spool.

Môi Trường

Gắn nhãn mọi sự kiện bằng môi trường triển khai (production, staging, qa, canary, v.v.). Đặt nó một lần; SDK sẽ tự động gắn nó vào mọi sự kiện. Tùy chọn 1: qua configure():

agenteye.configure(environment="production")

Tùy chọn 2: qua biến môi trường:

export AGENTEYE_ENVIRONMENT=production

Ưu tiên: configure(environment=...) sẽ thắng biến môi trường. Nếu không có gì được đặt, mặc định là "dev". Giá trị môi trường xuất hiện như một bộ lọc hạng nhất trong bảng điều khiển và được lưu trữ dưới dạng cột được lập chỉ mục trên máy chủ để truy vấn nhanh. Ràng buộc: các giá trị môi trường không được chứa dấu phẩy , nghĩa đen. Các bộ lọc bảng điều khiển sử dụng lựa chọn đa trên dây được phân tách bằng dấu phẩy (?environment=prod,staging), do đó một môi trường được đặt tên prod,blue sẽ bị chia thành hai giá trị. Các sự kiện có môi trường chứa dấu phẩy bị từ chối trong thời gian nhập.

Tham Chiếu Sự Kiện

Tất cả các phương thức sự kiện yêu cầu hai trường này:

Trường	Loại	Mô tả
`session_id`	`str`	Xác định lần chạy agent cấp cao nhất
`agent_id`	`str`	Xác định agent nào trong phiên đã phát ra sự kiện

Tất cả các phương thức cũng chấp nhận **kwargs tùy ý cho siêu dữ liệu tùy chỉnh (xem Trường Tùy Chỉnh).

`event.agent_start()`

Được phát ra khi một agent bắt đầu công việc.

agenteye.event.agent_start(
    session_id="run-001",
    agent_id="planner",
    goal="answer user query",   # str | None
    parent_id=None,             # str | None - agent_id cha cho các agent lồng nhau
)

`event.agent_end()`

Được phát ra khi một agent kết thúc công việc.

agenteye.event.agent_end(
    session_id="run-001",
    agent_id="planner",
    outcome="success",          # str | None
    summary="Answered query",   # str | None
)

`event.tool_use()`

Được phát ra khi một agent gọi một tool. Ghép với tool_result; SDK tự động tính toán duration_ms.

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",     # str, bắt buộc
    tool_call_id="toolu_01",    # str, bắt buộc - khóa tương quan cho tool_result khớp
    input={"query": "..."},     # dict | None
)

`event.tool_result()`

Được phát ra khi một tool trả về. Tương quan với tool_use qua tool_call_id.

agenteye.event.tool_result(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",        # phải khớp với tool_use trước đó
    output={"results": ["..."]},    # Any | None
    error=None,                     # str | None - đặt nếu tool đã nâng cao lỗi
    # duration_ms được tính toán tự động - không truyền nó
)

`event.model_request()`

Được phát ra ngay trước khi gửi một lời nhắc đến LLM.

agenteye.event.model_request(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6", # str | None
    messages=[                   # list[dict] | None - các lần hội thoại
        {"role": "user", "content": "..."},
    ],
    system="You are helpful.",   # Any | None - str hoặc danh sách các khối nội dung
    tools=[                      # list[dict] | None - các lược đồ tool được cung cấp cho mô hình
        {"name": "search", "input_schema": {"type": "object"}},
    ],
)

Các mục messages chấp nhận cả nội dung đơn giản content hoặc nội dung kiểu Anthropic content là danh sách các khối. Các tham số lấy mẫu (temperature, max_tokens, v.v.) có thể được truyền dưới dạng kwargs bổ sung.

`event.model_response()`

Được phát ra khi LLM trả về một phản hồi.

agenteye.event.model_response(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6", # str | None
    stop_reason="end_turn",     # str | None
    input_tokens=1024,          # int | None
    output_tokens=256,          # int | None
    content=[                    # Any | None - str, hoặc danh sách các khối nội dung
        {"type": "text", "text": "..."},
    ],
    role="assistant",            # str | None
)

content chấp nhận một chuỗi đơn giản (các nhà cung cấp chung) hoặc một danh sách các khối nội dung kiểu Anthropic. Các lệnh gọi tool nằm bên trong content dưới dạng các khối {"type": "tool_use", ...}, không có trường tool_calls riêng biệt.

`event.hook_triggered()`

Được phát ra khi một hook kích hoạt. Ghép với hook_completed; SDK tự động tính toán duration_ms.

agenteye.event.hook_triggered(
    session_id="run-001",
    agent_id="planner",
    hook_name="pre_tool_use",   # str, bắt buộc
    hook_id="hook-abc",         # str, bắt buộc - khóa tương quan
    trigger_event="tool_use",   # str | None
    input={"tool": "search"},   # Any | None
)

`event.hook_completed()`

Được phát ra khi một hook kết thúc. Tương quan với hook_triggered qua hook_id.

agenteye.event.hook_completed(
    session_id="run-001",
    agent_id="planner",
    hook_name="pre_tool_use",
    hook_id="hook-abc",         # phải khớp với hook_triggered trước đó
    outcome="allow",            # str | None
    output=None,                # Any | None
    error=None,                 # str | None
    # duration_ms được tính toán tự động - không truyền nó
)

`event.error()`

Được phát ra khi xảy ra lỗi không được xử lý.

agenteye.event.error(
    session_id="run-001",
    agent_id="planner",
    error_type="TimeoutError",  # str, bắt buộc
    message="timed out",        # str, bắt buộc
    traceback="Traceback...",   # str | None
)

Sự Kiện Con Người Trong Vòng Lặp

Các sự kiện con người trong vòng lặp cung cấp cho bạn giám sát các thời điểm khi một người bước vào quá trình thực thi của agent (chờ phê duyệt, cung cấp đầu vào, tạm dừng hoặc dừng agent). Chúng cho phép bạn đo lường con người mất bao lâu để phản hồi (SDK tự động tính toán duration_ms trên các sự kiện ghép), kiểm toán ai đã tạm dừng hoặc ngắt agent, và xây dựng các quy trình phê duyệt và giám sát xuất hiện trong bảng điều khiển.

`event.human_wait()`

Được phát ra khi agent tạm dừng thực thi để chờ con người cung cấp đầu vào. Ghép với human_input; SDK tự động tính toán duration_ms (con người mất bao lâu để phản hồi).

agenteye.event.human_wait(
    session_id="run-001",
    agent_id="planner",
    input_id="inp-abc",                          # str, bắt buộc - khóa tương quan cho human_input khớp
    prompt="Do you approve this action?",        # str | None - câu hỏi được hiển thị cho con người
    options=["approve", "reject", "defer"],      # list[str] | None - lựa chọn được trình bày cho con người
    reason="approval_required",                  # str | None - lý do agent đang chờ đợi
)

`event.human_input()`

Được phát ra khi con người cung cấp đầu vào và agent tiếp tục. Tương quan với human_wait qua input_id. duration_ms được tính toán tự động và không được truyền bởi người gọi.

agenteye.event.human_input(
    session_id="run-001",
    agent_id="planner",
    input_id="inp-abc",    # str, bắt buộc - phải khớp với human_wait trước đó
    response="approve",    # str | None - câu trả lời của con người (văn bản tự do hoặc tùy chọn được chọn)
    # duration_ms được tính toán tự động - không truyền nó
)

`event.human_pause()`

Được phát ra khi con người chủ động tạm dừng agent (ví dụ: qua điều khiển bảng điều khiển). Agent bị tạm dừng nhưng không bị kết thúc.

agenteye.event.human_pause(
    session_id="run-001",
    agent_id="planner",
    reason="user_requested",  # str | None
    user_id="usr_42",         # str | None - ai đã tạm dừng agent
)

`event.human_interrupt()`

Được phát ra khi con người chủ động dừng agent giữa chừng. Không giống như human_pause, công việc của agent bị kết thúc chứ không bị tạm dừng.

agenteye.event.human_interrupt(
    session_id="run-001",
    agent_id="planner",
    reason="output_incorrect",       # str | None
    user_id="usr_42",                # str | None - ai đã ngắt agent
    at_step="tool_use:web_search",   # str | None - agent đang làm gì khi bị dừng
)

Trường Tùy Chỉnh

Bất kỳ đối số từ khóa bổ sung nào được nối vào sự kiện sau các trường tiêu chuẩn:

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="db_query",
    tool_call_id="toolu_02",
    tenant_id="acme",           # trường tùy chỉnh
    region="us-east-1",         # trường tùy chỉnh
)

timestamp, type và environment được dành riêng và sẽ nâng cao ValueError (Reserved field names cannot be used as custom fields: [...]) nếu được truyền dưới dạng trường tùy chỉnh. session_id và agent_id là các tham số bắt buộc trên mọi phương thức sự kiện và không thể được cung cấp lần thứ hai; Python sẽ nâng cao TypeError nếu bạn làm như vậy. Thay vào đó, hãy đặt môi trường bằng configure(environment=...) (hoặc biến AGENTEYE_ENVIRONMENT).

Cách Các Sự Kiện Được Ghi

Các sự kiện được đệm trong quy trình và xóa đến đĩa mỗi flush_interval giây (mặc định 500 ms). Mỗi lần xóa ghi một tệp JSONL:

~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl

Bộ sưu tập theo dõi thư mục này và tải các tệp lên tự động. Bạn không cần quản lý các tệp này trực tiếp.

​Cài đặt

​Bắt Đầu Nhanh

​configure()

​Môi Trường

​Tham Chiếu Sự Kiện

​event.agent_start()

​event.agent_end()

​event.tool_use()

​event.tool_result()

​event.model_request()

​event.model_response()

​event.hook_triggered()

​event.hook_completed()

​event.error()

​Sự Kiện Con Người Trong Vòng Lặp

​event.human_wait()

​event.human_input()

​event.human_pause()

​event.human_interrupt()

​Trường Tùy Chỉnh

​Cách Các Sự Kiện Được Ghi