Iris

Iris — pare de lançar agentes na base do achismo

O Iris pontua cada execução de agente por qualidade, segurança e custo — na sua máquina, sem SDK e sem conta. A maioria dos projetos de agentes verifica qualidade rodando alguns prompts memorizados e avaliando a saída no olho. O Iris substitui isso por números que você pode auditar: as execuções do seu agente vão para um banco SQLite no seu disco, 13 regras embutidas as pontuam de forma determinística — PII, injeção de prompt, marcadores de alucinação, limites de custo — grátis, sem chamadas de LLM, e um avaliador LLM opcional com teto rígido de custo por avaliação cuida das questões semânticas. Cada regra é inspecionável e editável, porque um avaliador que você não pode auditar é só achismo com número. Licença MIT, sem telemetria; seus traces nunca saem da sua máquina.

Requer Node.js 20 ou posterior. Verifique com node --version.

Uma falha na tela em 60 segundos

Sem conexão com agente, sem configuração — um comando:

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

Isso popula um banco de demonstração — alguns agentes pequenos com uma semana de execuções — e serve o dashboard apontando para ele em http://localhost:6920 (seu navegador abre automaticamente na primeira execução). O dashboard cai direto em Failures: o que falhou, do pior para o mais recente. Vale clicar — um vazamento de PII capturado pelas regras de segurança, uma tentativa de injeção de prompt sinalizada e uma pontuação de avaliador LLM reprovada com sua justificativa.

Os dados de demonstração ficam em um banco separado (demo.db no seu diretório home do Iris — ~/.iris no macOS/Linux, %USERPROFILE%\.iris no Windows) e nunca se misturam com seus traces reais. Remova tudo com um comando:

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

Conecte seu próprio agente

Adicione o Iris à sua configuração MCP. Funciona com Claude Desktop, Claude Code, Cursor, Windsurf, Continue, VS Code, Cline, Zed, Codex CLI, Gemini CLI — e qualquer outro agente compatível com MCP. Um bloco, dashboard incluído:

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

Seu agente descobre as nove ferramentas do Iris ao conectar, e o dashboard serve em http://localhost:6920.. Agora cole isto no seu agente:

Registre essa última tarefa no Iris e avalie a saída.

O trace aparece no dashboard com suas pontuações. Prefere o servidor MCP sem interface? Remova --dashboard dos argumentos — você pode abrir o mesmo dashboard a qualquer momento com npx @iris-eval/mcp-server --dashboard.

Uma coisa que vale saber desde já: ferramentas MCP são chamadas quando o modelo decide chamá-las. O Iris não intercepta seu agente, então os traces são registrados quando seu agente pede para registrá-los — seja porque você pediu, seja porque seu código chama as ferramentas diretamente. Peça ao seu agente para "registrar isso no Iris e avaliar" e ele fará. Se você quiser captura que não dependa da escolha do modelo, o POST /api/v1/traces faz exatamente isso — seu código envia o trace via HTTP puro, sem modelo no meio (veja docs/http-ingest.md). A CLI e os SDKs no roadmap serão clientes leves sobre o mesmo endpoint.

Captura via HTTP (sem modelo no meio)

Com o dashboard em execução, qualquer coisa que possa enviar uma requisição HTTP pode registrar um trace — e opcionalmente rodar as avaliações determinísticas na mesma requisição:

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"
  }'

Retorna 201 com o trace_id armazenado e o resultado da avaliação. O endpoint aceita o mesmo corpo da ferramenta log_trace e fica atrás do mesmo middleware restrito a loopback do restante do dashboard. Contrato completo, referência de campos e semântica de erros: docs/http-ingest.md.

Verifique a instalação

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

Um diagnóstico offline da instalação: round-trip de armazenamento, avaliações determinísticas, dashboard + proteção contra DNS rebinding — tudo dentro de um home temporário isolado, então seu banco real nunca é aberto. Código de saída 0 = saudável, 1 = alguma verificação falhou.

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"]

Outros métodos de instalação

# 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

Dica: A instalação global (npm install -g) armazena traces persistentemente em ~/.iris/iris.db. Com npx, os traces persistem no mesmo local, mas a inicialização é mais lenta devido à resolução de pacotes.

O que você ganha

Para onde isso está indo: o roadmap.

Ferramentas MCP

O Iris registra nove ferramentas que qualquer agente compatível com MCP pode invocar — ciclo de vida completo de regras + traces + LLM-como-avaliador + verificação semântica de citações:

• log_trace — Registra uma execução de agente com spans, chamadas de ferramenta, uso de tokens e custo
• evaluate_output — Pontua a qualidade da saída contra regras de completude, relevância, segurança e custo (heurística, determinística, grátis)
• get_traces — Consulta traces armazenados com filtragem, paginação e suporte a intervalos de tempo
• list_rules — Enumera as regras de avaliação personalizadas implantadas (somente leitura)
• deploy_rule — Registra uma nova regra de avaliação personalizada para que ela seja aplicada em todo evaluate_output daquela categoria
• delete_rule — Remove uma regra personalizada implantada (destrutivo, idempotente)
• delete_trace — Remove um único trace armazenado por ID (destrutivo, com escopo por tenant)
• evaluate_with_llm_judge — Avaliação semântica via LLM (Anthropic ou OpenAI). Cinco templates: precisão, utilidade, segurança, correção, fidelidade. Com teto de custo e preço por avaliação divulgado. Traga sua própria chave de API (IRIS_ANTHROPIC_API_KEY ou IRIS_OPENAI_API_KEY) — o Iris não faz proxy nem retransmite chamadas de LLM.
• verify_citations — Extrai citações da saída (numeradas, autor-ano, URLs, DOIs), busca as fontes por trás de um resolvedor protegido contra SSRF e com allowlist de domínios, e usa um avaliador LLM para verificar se cada fonte realmente sustenta a afirmação citada. HTTP de saída opt-in. Mesmo requisito BYOK que o evaluate_with_llm_judge.

Quando IRIS_OTEL_ENDPOINT está configurado, chamadas de log_trace também emitem uma exportação OTLP/HTTP JSON best-effort para qualquer coletor OpenTelemetry (Jaeger, Grafana Tempo, Datadog OTLP, Honeycomb, etc.). Veja docs/otel-integration.md.

Como o passed é decidido

evaluate_output retorna tanto um score quanto uma flag passed — eles respondem perguntas diferentes:

• score (0..1) é a média ponderada das regras que foram executadas — um gradiente de qualidade.
• passed é o veredito liberar/não liberar: true somente quando a pontuação ultrapassa o limite de aprovação (padrão 0,7) e nenhuma regra crítica falhou.

Violaçõões reais de segurança reprovam automaticamente. no_pii, no_injection_patterns e no_blocklist_words são regras críticas: se uma falhar, a avaliação reporta passed: false não importa quão bem as outras regras pontuaram, e a resposta nomeia os culpados em critical_failures. Um SSN vazado não pode ser diluído pela média. Regras personalizadas implantadas com severity: "high" ou "critical" reprovam da mesma forma; severidades low/medium afetam apenas a pontuação. Um limite que vale conhecer: uma regra crítica que pulou (contexto ausente ou qualquer outra causa de skip) não julgou a saída e não tem poder de veto — rule_results mostra cada skip e seu motivo, para que um gate que precise falhar fechado em não-vereditos possa fazer isso.

Uma pegadinha para gates de CI: se você omitir eval_type, o bundle padrão completeness é executado — as regras de segurança não são. A resposta ecoa eval_type (mais um note quando foi aplicado o padrão) para que seu gate possa verificar qual bundle realmente rodou. Use passed para o veredito e eval_type: "safety" para a cobertura.

Esquemas completos das ferramentas e configuração: iris-eval.com

Recursos hospedados

O Iris roda inteiramente na sua máquina hoje, e tudo o que ele faz é gratuito e licenciado sob MIT, sem limites e sem conta.

Armazenamento hospedado, histórico compartilhado de equipe e alertas estão em consideração, não em construção. Não há preço, e nada para comprar. Se histórico compartilhado fosse útil para você, a lista de espera é como descobrimos se vale a pena construir — ela não compromete você a nada.

Dois compromissos valem independentemente: nada que é gratuito hoje será colocado atrás de paywall, e nenhuma certificação de conformidade será reivindicada antes de ser obtida.

Exemplos

• Configuração do Claude Desktop — configuração MCP para modos stdio e HTTP
• TypeScript — cliente SDK MCP — conecte e invoque ferramentas
• Transporte HTTP (TS + Python) — código completo de cliente para integração estilo REST
• Instrumentação LangChain (Python, conceitual) — scaffold mostrando a forma; precisa do seu código de agente executável
• Instrumentação CrewAI (Python, conceitual) — scaffold; mesma ressalva

Comunidade

• GitHub Issues — Relatórios de bugs e solicitações de recursos
• GitHub Discussions — Perguntas e ideias
• Contributing Guide — Como contribuir
• HTTP Ingest — Captura determinística de traces via POST /api/v1/traces
• Roadmap — O que vem a seguir

# 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"

Se o Iris for útil para você, considere dar uma estrela no repositório — isso ajuda outras pessoas a encontrá-lo.

Licenciado sob MIT.