Iris

Iris — ngừng phát hành agent dựa trên cảm tính

Iris chấm điểm mọi lần chạy của agent về chất lượng, an toàn và chi phí — ngay trên máy của bạn, không cần SDK và không cần tài khoản. Hầu hết các dự án agent kiểm tra chất lượng bằng cách chạy vài prompt được nhớ sẵn rồi xem qua kết quả. Iris thay thế cách đó bằng những con số bạn có thể kiểm chứng: các lần chạy của agent được lưu vào cơ sở dữ liệu SQLite trên đĩa của bạn, 13 luật tích hợp chấm điểm chúng một cách xác định — PII, prompt injection, dấu hiệu hallucination, ngưỡng chi phí — miễn phí, không cần gọi LLM, và một LLM judge tùy chọn với giới hạn chi phí cố định cho mỗi lần đánh giá xử lý các câu hỏi về ngữ nghĩa. Mọi luật đều có thể xem xét và chỉnh sửa, bởi vì một judge mà bạn không thể kiểm chứng chỉ là cảm tính gắn thêm con số. Giấy phép MIT, không có telemetry; trace của bạn không bao giờ rời khỏi máy của bạn.

Yêu cầu Node.js 20 trở lên. Kiểm tra bằng node --version.

Một lỗi hiện lên màn hình trong 60 giây

Không cần kết nối agent, không cần cấu hình — chỉ một lệnh:

npx @iris-eval/mcp-server --demo

Lệnh này tạo một cơ sở dữ liệu demo — một vài agent nhỏ với một tuần dữ liệu chạy — và phục vụ dashboard từ đó tại http://localhost:6920 (trình duyệt của bạn tự động mở trong lần chạy đầu tiên). Dashboard mở ở mục Failures: những gì thất bại, nặng nhất và mới nhất ở đầu. Đáng để nhấp vào — một vụ rò rỉ PII bị các luật an toàn bắt được, một nỗ lực prompt-injection bị gắn cờ, và một điểm LLM-judge thất bại kèm lý do.

Dữ liệu demo nằm trong cơ sở dữ liệu riêng (demo.db trong thư mục chính Iris của bạn — ~/.iris trên macOS/Linux, %USERPROFILE%\.iris trên Windows) và không bao giờ trộn lẫn với trace thật của bạn. Xóa toàn bộ dữ liệu đó bằng một lệnh:

npx @iris-eval/mcp-server --demo-clear

Kết nối agent của riêng bạn

Thêm Iris vào cấu hình MCP của bạn. Hoạt động với Claude Desktop, Claude Code, Cursor, Windsurf, Continue, VS Code, Cline, Zed, Codex CLI, Gemini CLI — và bất kỳ agent tương thích MCP nào khác. Một khối, đã bao gồm dashboard:

{
  "mcpServers": {
    "iris-eval": {
      "command": "npx",
      "args": ["@iris-eval/mcp-server", "--dashboard"]
    }
  }
}

Agent của bạn khám phá chín công cụ của Iris khi kết nối, và dashboard phục vụ tại http://localhost:6920. Bây giờ dán lệnh này cho agent của bạn:

Ghi lại tác vụ cuối cùng đó vào Iris và đánh giá kết quả.

Trace xuất hiện trên dashboard kèm điểm số. Thích dùng MCP server ở chế độ headless? Bỏ --dashboard khỏi đối số — bạn có thể mở cùng dashboard đó bất cứ lúc nào bằng npx @iris-eval/mcp-server --dashboard.

Một điều đáng biết trước: Các công cụ MCP được gọi khi mô hình quyết định gọi chúng. Iris không chặn agent của bạn, vì vậy trace được ghi lại khi agent của bạn yêu cầu ghi chúng — hoặc vì bạn bảo nó làm vậy, hoặc vì mã của bạn gọi trực tiếp các công cụ. Hãy yêu cầu agent của bạn "ghi lại việc này vào Iris và đánh giá nó" và nó sẽ làm. Nếu bạn muốn ghi lại mà không phụ thuộc vào sự lựa chọn của mô hình, POST /api/v1/traces làm chính xác điều đó — mã của bạn gửi trace qua HTTP thông thường, không có mô hình trong vòng lặp (xem docs/http-ingest.md). CLI và SDK trong lộ trình sẽ là các client gọn nhẹ trên cùng endpoint đó.

Ghi lại qua HTTP (không có mô hình trong vòng lặp)

Khi dashboard đang chạy, bất cứ thứ gì có thể gửi yêu cầu HTTP đều có thể ghi trace — và tùy chọn chạy các đánh giá xác định trong cùng yêu cầu đó:

curl -s -X POST "http://127.0.0.1:6920/api/v1/traces" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "support-bot",
    "input": "What is the refund policy?",
    "output": "Refunds are available within 30 days of purchase.",
    "evaluate": true,
    "eval_type": "safety"
  }'

Trả về 201 với trace_id đã lưu và kết quả đánh giá. Endpoint chấp nhận cùng body như công cụ log_trace và nằm sau cùng middleware stack chỉ dành cho loopback như phần còn lại của dashboard. Toàn bộ hợp đồng, tài liệu tham chiếu trường và ngữ nghĩa lỗi: docs/http-ingest.md.

Kiểm tra cài đặt

npx @iris-eval/mcp-server --self-test

Một chẩn đoán cài đặt ngoại tuyến: kiểm tra vòng lặp lưu trữ, đánh giá xác định, dashboard + bộ bảo vệ DNS-rebinding — tất cả bên trong một thư mục home tạm biệt lập, nên cơ sở dữ liệu thật của bạn không bao giờ bị mở. Mã thoát 0 = khỏe mạnh, 1 = một kiểm tra thất bại.

claude mcp add --transport stdio iris-eval -- npx @iris-eval/mcp-server

{
  "servers": {
    "iris-eval": {
      "command": "npx",
      "args": ["@iris-eval/mcp-server"]
    }
  }
}

{
  "context_servers": {
    "iris-eval": {
      "command": {
        "path": "npx",
        "args": ["@iris-eval/mcp-server"]
      }
    }
  }
}

[mcp_servers.iris-eval]
command = "npx"
args = ["@iris-eval/mcp-server"]

Các Phương Pháp Cài Đặt Khác

# Global install (recommended for persistent data and faster startup)
npm install -g @iris-eval/mcp-server
iris-mcp --dashboard

# Docker — two servers, two ports: 3000 = MCP HTTP transport,
# 6920 = dashboard (which also serves the POST /api/v1/traces ingest endpoint)
docker run -p 3000:3000 -p 6920:6920 -v iris-data:/data ghcr.io/iris-eval/mcp-server

Mẹo: Cài đặt toàn cục (npm install -g) lưu trữ trace một cách bền vững tại ~/.iris/iris.db. Với npx, trace được lưu ở cùng vị trí, nhưng khởi động chậm hơn do phân giải package.

Những Gì Bạn Nhận Được

Hướng phát triển tiếp theo: lộ trình.

Công Cụ MCP

Iris đăng ký chín công cụ mà bất kỳ agent tương thích MCP nào cũng có thể gọi — toàn bộ vòng đời luật + trace + LLM-as-judge + xác minh trích dẫn ngữ nghĩa:

• log_trace — Ghi lại một lần thực thi agent với spans, lời gọi công cụ, mức sử dụng token và chi phí
• evaluate_output — Chấm điểm chất lượng đầu ra theo các luật về mức đầy đủ, mức liên quan, an toàn và chi phí (heuristic, xác định, miễn phí)
• get_traces — Truy vấn trace đã lưu với bộ lọc, phân trang và hỗ trợ khoảng thời gian
• list_rules — Liệt kê các luật đánh giá tùy chỉnh đang triển khai (chỉ đọc)
• deploy_rule — Đăng ký một luật đánh giá tùy chỉnh mới để nó kích hoạt trên mọi evaluate_output thuộc danh mục đó
• delete_rule — Xóa một luật tùy chỉnh đang triển khai (phá hủy, idempotent)
• delete_trace — Xóa một trace đã lưu theo ID (phá hủy, theo phạm vi tenant)
• evaluate_with_llm_judge — Đánh giá ngữ nghĩa qua LLM (Anthropic hoặc OpenAI). Năm mẫu: độ chính xác, mức hữu ích, an toàn, độ đúng, mức trung thành. Có giới hạn chi phí, giá mỗi lần đánh giá được công bố. Mang API key của riêng bạn (IRIS_ANTHROPIC_API_KEY hoặc IRIS_OPENAI_API_KEY) — Iris không proxy hoặc chuyển tiếp các lời gọi LLM.
• verify_citations — Trích xuất trích dẫn từ đầu ra (đánh số, tác giả-năm, URL, DOI), tải nguồn phía sau một bộ phân giải được bảo vệ SSRF + allowlist tên miền, và dùng LLM judge để kiểm tra xem mỗi nguồn có thực sự hỗ trợ tuyên bố được trích dẫn không. HTTP gửi đi tùy chọn. Cùng yêu cầu BYOK như evaluate_with_llm_judge.

Khi IRIS_OTEL_ENDPOINT được cấu hình, các lời gọi log_trace cũng phát ra bản xuất JSON OTLP/HTTP cố gắng hết sức đến bất kỳ collector OpenTelemetry nào (Jaeger, Grafana Tempo, Datadog OTLP, Honeycomb, v.v.). Xem docs/otel-integration.md.

Cách passed được quyết định

evaluate_output trả về cả cờ score lẫn cờ passed — chúng trả lời các câu hỏi khác nhau:

• score (0..1) là trung bình có trọng số trên các luật đã chạy — một gradient chất lượng.
• passed là phán quyết ship/không ship: true chỉ khi điểm vượt ngưỡng đạt (mặc định 0.7) và không có luật nghiêm trọng nào thất bại.

Các vi phạm an toàn thực sự sẽ thất bại cứng. no_pii, no_injection_patterns và no_blocklist_words là các luật nghiêm trọng: nếu một luật thất bại, đánh giá báo cáo passed: false bất kể các luật khác được chấm điểm tốt đến đâu, và phản hồi nêu tên thủ phạm trong critical_failures. Một SSN bị rò rỉ không thể bị trung bình hóa để biến mất. Các luật tùy chỉnh được triển khai bằng severity: "high" hoặc "critical" thất bại cứng theo cách tương tự; các mức độ nghiêm trọng low/medium chỉ ảnh hưởng đến điểm. Một ranh giới cần biết: một luật nghiêm trọng bị bỏ qua (thiếu ngữ cảnh, hoặc bất kỳ lý do bỏ qua nào khác) chưa đánh giá đầu ra và không phủ quyết — rule_results hiển thị mọi lần bỏ qua và lý do của nó, để một cổng chặn cần thất bại đóng trên các trường hợp không có phán quyết có thể làm vậy.

Một điểm cần lưu ý cho CI gates: nếu bạn bỏ qua eval_type, bộ completeness mặc định sẽ chạy — các luật an toàn không chạy. Phản hồi phản ánh lại eval_type (cộng thêm note khi nó bị mặc định) để cổng chặn của bạn có thể xác minh bộ nào thực sự đã chạy. Dựa vào passed cho phán quyết và eval_type: "safety" cho mức độ bao phủ.

Toàn bộ schema công cụ và cấu hình: iris-eval.com

Các tính năng lưu trữ

Iris chạy hoàn toàn trên máy của bạn hiện nay, và mọi thứ nó làm đều miễn phí và có giấy phép MIT, không giới hạn và không tài khoản.

Lưu trữ có chủ, lịch sử nhóm dùng chung và cảnh báo đang được cân nhắc, chưa được xây dựng. Không có giá cả, và không có gì để mua. Nếu lịch sử dùng chung hữu ích với bạn, danh sách chờ là cách chúng tôi biết liệu nó có đáng xây dựng không — nó không ràng buộc bạn điều gì.

Hai cam kết giữ nguyên trong mọi trường hợp: không thứ gì miễn phí hôm nay sẽ bị đưa sau tường phí, và không chứng nhận tuân thủ nào sẽ được công bố trước khi đạt được nó.

Ví dụ

• Thiết lập Claude Desktop — cấu hình MCP cho chế độ stdio và HTTP
• TypeScript — MCP SDK client — kết nối và gọi các công cụ
• HTTP transport (TS + Python) — mã client đầy đủ cho tích hợp kiểu REST
• LangChain instrumentation (Python, mang tính khái niệm) — bản khung cho thấy hình dạng; cần mã agent của bạn có thể chạy được
• CrewAI instrumentation (Python, mang tính khái niệm) — bản khung; cùng lưu ý trên

Cộng đồng

• GitHub Issues — Báo cáo lỗi và yêu cầu tính năng
• GitHub Discussions — Câu hỏi và ý tưởng
• Hướng dẫn đóng góp — Cách đóng góp
• HTTP Ingest — Thu thập trace xác định qua POST /api/v1/traces
• Lộ trình phát triển — Những gì sắp ra mắt

# Production deployment
iris-mcp --transport http --port 3000 --api-key "$(openssl rand -hex 32)" --dashboard

npx @iris-eval/mcp-server --self-test

npx --yes @iris-eval/mcp-server@latest

npm install -g @iris-eval/mcp-server@latest

npx @iris-eval/mcp-server --dashboard
# First log line: "Starting Iris MCP server vX.Y.Z"

# If using npx (clears cache and fetches latest)
npx --yes @iris-eval/mcp-server@latest

# If installed globally
npm update -g @iris-eval/mcp-server

node --version  # Must be v20.x or v22.x+

# Correct
claude mcp add --transport stdio iris-eval -- npx @iris-eval/mcp-server

# Wrong (causes /c to be parsed as a path)
claude mcp add --transport stdio iris-eval -- cmd /c "npx @iris-eval/mcp-server"

Nếu Iris hữu ích với bạn, hãy cân nhắc đánh dấu sao cho kho lưu trữ — điều đó giúp người khác tìm thấy nó.

Được cấp phép MIT.