Construa uma Ferramenta de Análise Somente para Leitura Antes de Dar Ações ao Seu Agente

A maneira mais rápida de tornar um agente de análise impressionante é deixá-lo responder a perguntas amplas em linguagem natural. A maneira mais rápida de torná-lo perigoso é dar a mesma autoridade de exportação, mutação ou implantação de caminho.

Envie primeiro um pequeno segmento somente leitura.

type MetricRequest = {
  tenantId: string;
  metric: "daily_active_users" | "activation_rate";
  from: string;
  to: string;
  dimensions: Array<"plan" | "country">;
  requestId: string;
};

type MetricResponse = {
  definitionVersion: string;
  dataThrough: string;
  rows: Array<Record<string, string | number>>;
  sourceQueryId: string;
  warnings: string[];
};

Valide datas, intervalo máximo, dimensões e nomes de métricas. Derive tenantId do contexto do servidor autenticado em vez de confiar no modelo. A camada de consulta mapeia enums para SQL pré-revisado ou um modelo semântico; nunca aceita SQL gerado pelo modelo.

Faça a evidência viajar de ponta a ponta

O backend retorna versão da definição, frescor dos dados, ID da consulta e avisos. O adaptador da ferramenta os preserva. A interface do usuário os renderiza ao lado da resposta e oferece um link para o gráfico de origem ou registro da consulta.

Os estados de UI necessários são carregando, resultado parcial, dados obsoletos, sem dados, proibido, limite de taxa, cancelado e evidência indisponível. “Sem linhas” é diferente de “o armazém falhou.”

Cache somente após autorização e canonização. Inclua inquilino, métrica, dimensões, intervalo de datas e versão da definição na chave de cache. Não armazene em cache linhas de nível de usuário em infraestrutura compartilhada.

Teste as costuras

Escreva testes de contrato para métricas desconhecidas, um inquilino não autorizado, datas invertidas, intervalo excessivo, dimensões não suportadas, dados obsoletos, ID de solicitação duplicado, tempo limite e uma mudança na definição da métrica durante a vida útil do cache. Verifique se o navegador não pode alterar a identidade do inquilino editando os argumentos da ferramenta.

Somente após o caminho de leitura ser observável e corretamente autorizado você deve considerar ações. Coloque gravações em ferramentas separadas com credenciais separadas, pré-visualizações, chaves de idempotência e aprovações explícitas.

O repositório MonkeyCode público descreve gerenciamento de modelo, tarefas de IA, ambientes de desenvolvimento e colaboração em equipe. Ele pode ser avaliado como um espaço de trabalho de desenvolvimento para esse tipo de integração, mas este artigo não afirma uma integração de análise ou MCP com o MonkeyCode.

Divulgação: Eu contribuo para o projeto MonkeyCode. A arquitetura é independente da ferramenta; o contexto do produto vem da documentação pública.

Somente leitura não é um marco de brinquedo. É onde a equipe prova identidade, evidência, frescor e semântica de falha antes que efeitos colaterais tornem cada erro mais caro.