Evaluation Suite

Lưu ý: Bạn xác định các chiều chấm điểm. Evaluator của bạn có thể trả về bất kỳ khóa số nào mà nó muốn; Observability sẽ lưu trữ, xu hướng và hiển thị bất kỳ thứ gì bạn gửi lại.

​

Tổng quan

1. Viết một bộ chấm điểm. Thiết lập một dịch vụ HTTP nhỏ đọc bản ghi phiên làm việc và trả về điểm số. Observability cung cấp một tài liệu tham khảo hoạt động mà bạn có thể sao chép. Xem Viết một evaluator với SDK.
2. Hướng Observability đến nó. Đặt EVALUATOR_ENDPOINT (và một EVALUATOR_TOKEN được chia sẻ) trên quá trình máy chủ.
3. Theo dõi điểm số. Mọi phiên hoàn thành được chấm điểm tự động; kết quả xuất hiện trên trang chi tiết phiên, lưới phiên và các bảng điều khiển đã lưu.

​

Cách hoạt động

• Trả về kết quả ngay lập tức với {"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}. Kết quả được thêm vào dòng thời gian đánh giá của phiên. reasoning và summary là tùy chọn.
• Hoãn lại với {"status":"pending", "job_id":"abc-123"}. Observability sau đó gọi GET {EVALUATOR_ENDPOINT}/evaluate/abc-123 cho đến khi evaluator của bạn trả về {"status":"done", ...} hoặc {"status":"error", "error":"..."}. Tần suất thăm dò là dựa trên từng công việc: phản hồi pending có thể bao gồm next_poll_secs để ghi đè; nếu không Observability sử dụng giá trị default_poll_interval_secs từ GET /config; nếu không máy chủ sẽ quay lại EVALUATOR_POLLING_INTERVAL_SECS (mặc định 10 giây). Tất cả giá trị được giới hạn trong [1 giây, 1 giờ].

​

Hợp đồng HTTP

• Máy chủ Observability: biến env EVALUATOR_TOKEN
• Dịch vụ Evaluator: được cấu hình cùng cách (SDK agenteye-evaluator đọc EVALUATOR_TOKEN theo quy ước)

​

Các tuyến đường mà evaluator phải phục vụ

​

Nội dung EvalRequest được gửi bởi máy chủ

{
  "schema_version": "1",
  "session_id":     "session-abc123",
  "agent_id":       "planner",
  "environment":    "production",
  "started_at":     "2026-05-10T12:00:00Z",
  "ended_at":       "2026-05-10T12:05:00Z",
  "events": [
    { "id": 1234, "ts": "...", "event_type": "agent_start", "payload": { ... } },
    ...
  ]
}

​

Hình dạng phản hồi

{
  "status": "done",
  "scores": { "helpfulness": 0.85, "tool_efficiency": 0.6 },
  "reasoning": {
    "helpfulness": "answered the question directly with citations",
    "tool_efficiency": "called list_files three times when one would have done"
  },
  "summary": "strong answer quality, weak tool selection"
}

{ "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 }

{ "status": "error", "error": "model service unavailable" }

​

Viết một evaluator với SDK

import os
from agenteye_evaluator import Evaluator, EvalRequest, EvalResponse

app = Evaluator(token=os.environ["EVALUATOR_TOKEN"])

@app.evaluator
def run(req: EvalRequest) -> EvalResponse:
    # Inspect req.events (the full session transcript) and return scores.
    tool_calls = sum(1 for e in req.events if e.event_type == "tool_use")
    return EvalResponse(
        scores={"tool_calls": float(tool_calls)},
        reasoning={"tool_calls": f"{tool_calls} tool invocations in the transcript"},
        summary="tight tool loop" if tool_calls < 5 else "agent looped on tools",
    )

​

Chạy evaluator của bạn

​

Cấu hình máy chủ

​

Tham chiếu API

​

Lọc theo phạm vi điểm: score_filters

# helpfulness in [0.5, 0.8]
GET /evaluations?score_filters=helpfulness:0.5..0.8

# tool_efficiency at most 0.3 (no lower bound)
GET /evaluations?score_filters=tool_efficiency:..0.3

# helpfulness >= 0.5 AND factuality >= 0.9
GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9..

​

Quyền hạn

​

Xem kết quả

• /sessions/<id>: dòng thời gian sự kiện + thanh bên phải hiển thị điểm của phiên và bất kỳ lỗi nào từ lần cố gắng gửi. Nếu khóa của bạn có evaluations:trigger, nút re-evaluate sẽ xuất hiện cạnh nút xuất, hữu ích cho các phiên chưa bao giờ phát ra agent_end hoặc để làm mới các điểm sau khi triển khai một evaluator mới. Bảng điều khiển thăm dò kết quả mới và cập nhật thanh bên phải khi nó đến.
• /sessions: lưới phiên có thể lọc; cột điểm hiển thị trạng thái đánh giá và điểm của mỗi phiên một cách nhanh chóng.
• /dashboards: các chế độ xem sức khỏe đánh giá đã lưu (xem Bảng điều khiển bên dưới).

​

Bảng điều khiển

• Bộ lọc: các điều khiển giống như trang phiên: môi trường, trạng thái, agent, cửa sổ thời gian rolling và các bộ lọc phạm vi điểm (key:min..max).
• Cấu hình hiển thị: các khóa điểm nào để tính năng, ngưỡng sức khỏe xanh lá cây/hổ phách/đỏ, bảng nào để hiển thị và có nên thu gọn đến đánh giá mới nhất trên mỗi phiên.

​

Khắc phục sự cố

​

Các bước tiếp theo

• Evaluator agent skill: có một coding agent thiết kế các chiều của bạn so với các phiên thực tế và xây dựng dịch vụ này cho bạn.
• Python SDK: phát ra các sự kiện agent_end kích hoạt chấm điểm.
• Khóa API: các quyền evaluations:read và evaluations:trigger.
• Kiểm toán: tính năng chất lượng tự động khác của Observability, để xem xét dựa trên chính sách.