Arquitetura de Governança de Agentes de IA: do Prompt à Ação

Uma arquitetura de governança de agentes de IA define os componentes, limites de confiança e contratos que conectam uma ação proposta pelo agente à avaliação de política, à aplicação da decisão e às evidências do que aconteceu. Ela identifica onde uma decisão pode ser tomada, qual componente pode aplicá-la e o que precisa ser transmitido entre eles.

Este guia usa uma arquitetura conceitual para examinar essas passagens. Ela não é um projeto obrigatório para todo agente nem um diagrama de um sistema KonaSense implantado. O pilar de governança de agentes de IA estabelece a questão mais ampla da autoridade delegada; a arquitetura torna essa autoridade aplicável em limites específicos.

Comece por uma mudança concreta em outro sistema

Exemplo hipotético: um funcionário pede a um assistente de service desk que adicione um profissional contratado de plantão ao workspace de resposta ao incidente atual, com perfil de leitura. O assistente propõe uma operação workspace.add_member com o identificador do workspace, o identificador da conta do contratado e o perfil viewer. O nome da ferramenta e o fluxo são ilustrativos, não uma integração real ou um caso de cliente.

O projeto proposto exige que a conta corresponda ao registro no diretório da organização, que o contratado esteja designado para o incidente e que o responsável pelo workspace aprove sua inclusão. Ele não autoriza acesso de administrador por esse fluxo. Essas são escolhas de política do exemplo, não regras universais para resposta a incidentes.

Mantenha três identidades separadas: o funcionário que faz a solicitação, o contratado que recebe acesso e a identidade de serviço usada pelo executor. A credencial do executor pode permitir tecnicamente alterações de acesso mais amplas do que essa tarefa autoriza. Nem a posse dessa credencial nem uma solicitação clara do funcionário comprovam a aprovação do responsável pelo workspace.

O problema de arquitetura é levar essas distinções até o componente que envia a alteração de acesso. Se o serviço de políticas recebe viewer, mas o executor envia administrator, uma proposta avaliada corretamente não governou a operação que veio depois.

Acompanhe a proposta antes de desenhar a ação

A sequência acompanha um usuário ou gatilho pelo runtime do agente, modelo, montagem do contexto para decisão, seleção da ferramenta, chamada proposta, decisão de política e ação permitida. As ramificações importam: Negar encerra sem a ação protegida; Exigir Aprovação deixa a ação pendente. Há evidência de decisão nesses caminhos mesmo quando nenhuma operação é tentada.

O contexto também existe antes da inferência do modelo. O runtime fornece instruções, a solicitação do usuário e outros materiais que a aplicação permite. Montagem de Contexto, nesta sequência, significa reunir fatos para decidir sobre a ação, como a conta e o workspace identificados. Isso não significa que o modelo operou sem contexto. As implementações podem reunir esses fatos antes ou enriquecê-los à medida que a proposta de ferramenta se torna concreta.

Da mesma forma, Chamada de Ferramenta antes de Decisão de Política significa uma chamada proposta ou interceptada cujo efeito protegido ainda não ocorreu. Isso não exige enviar uma solicitação a uma ferramenta remota antes de avaliar a política. Se a avaliação acontece dentro do serviço da ferramenta, a solicitação pode ter chegado até ele enquanto a inclusão no workspace continua retida.

As etapas são responsabilidades lógicas, não uma exigência de um serviço separado para cada passo. Um runtime pode combinar várias etapas ou repetir o ciclo. O que importa é localizar o limite anterior ao efeito controlado e especificar quais fatos e decisões o atravessam.

Onde a política pode ser avaliada?

A política pode ser avaliada onde a arquitetura expõe uma solicitação relevante e consegue conectar o resultado a um controle efetivo. Locais diferentes têm autoridade e contexto diferentes.

No runtime, uma verificação pode examinar a ferramenta proposta, a tarefa e os argumentos antes do envio. Isso ajuda a identificar solicitações fora da delegação, como acesso de administrador no fluxo hipotético de acesso de leitura. Ela governa somente os caminhos que passam por essa verificação.

Em uma camada intermediária ou no serviço da ferramenta, a avaliação pode usar o recurso identificado e a identidade que chamará o destino. Esse local pode conhecer mais detalhes da solicitação real do que o modelo. Seu contrato ainda precisa identificar se o serviço consegue reter a alteração externa e se outros chamadores passam por fora dele.

No destino, os controles de acesso determinam se a identidade executora pode alterar aquele recurso. O Authorization Cheat Sheet da OWASP, em inglês recomenda validar permissões a cada solicitação e posicionar as verificações de acesso onde a manipulação no cliente não possa decidir o acesso ao recurso. Um resultado de política em runtime não substitui essas verificações no destino.

No exemplo do workspace, o runtime pode limitar o perfil proposto, o serviço da ferramenta pode verificar a conta e a aprovação, e o destino pode autorizar a identidade de serviço. Essa distribuição é uma opção de projeto. Documente qual componente responde por cada verificação e qual resultado o próximo componente precisa respeitar; não presuma que verificações distribuídas por vários locais sejam consistentes entre si.

Que contexto uma decisão deve usar?

Use os fatos necessários para decidir sobre a ação específica, junto com suas fontes e limitações. Uma conversa completa não substitui a identificação da conta que receberia acesso.

Atravessar um limite de confiança muda aquilo em que um componente pode se apoiar. Um nome de conta gerado pelo modelo ainda precisa ser conferido, não é uma identidade verificada no diretório. Uma nota dizendo “aprovado pelo responsável” não é um registro de aprovação. Defina como o componente receptor verifica cada afirmação, incluindo comunicação autenticada quando apropriado; o nome de um campo, por si só, não oferece garantia.

Vincule a avaliação à solicitação que o executor usará. Se a identificação da conta, o workspace, o perfil ou a identidade executora mudar, determine se a decisão anterior continua aplicável. A governança de IA em runtime aprofunda esse contrato de validade. Um identificador de solicitação compartilhado ajuda a localizar registros, mas não impede, por si só, que a solicitação mude.

O que muda quando há MCP?

O MCP introduz host, cliente e servidor no caminho usado para obter contexto ou chamar uma ferramenta. Sua documentação de arquitetura, em inglês separa o protocolo da forma como a aplicação usa modelos e gerencia contexto. As responsabilidades de política e execução ainda precisam ser implementadas.

Para uma versão MCP do fluxo hipotético, identifique o servidor configurado, a ferramenta selecionada, os argumentos concretos e a identidade apresentada àquele servidor. O nome de uma ferramenta não identifica completamente o destino. A especificação de ferramentas do MCP, em inglês limita a unicidade dos nomes ao servidor e orienta tratar as anotações das ferramentas como não confiáveis, a menos que venham de servidores confiáveis. Metadados descritivos não comprovam a autorização do responsável pelo workspace.

A especificação de autorização do MCP, em inglês define um fluxo de autorização para transportes HTTP; o suporte à autorização é opcional nas implementações MCP, e esse fluxo não se aplica a STDIO. Acesso a um servidor MCP protegido e autoridade para uma alteração específica de acesso continuam sendo questões separadas. Revise a credencial usada pelo servidor no sistema de destino e seus controles de acesso, em vez de inferi-los a partir da conexão.

A especificação de ferramentas também exige validação de entradas e controles de acesso no servidor. No exemplo, o serviço precisa avaliar o workspace e a conta solicitados antes de realizar a alteração protegida. Quer avalie a política diretamente, quer se apoie em uma decisão anterior de outro componente, especifique como recebe e valida a autorização aplicável. Não posicione a única verificação efetiva depois da atualização de acesso.

O que é visível antes da execução e o que vem depois?

Antes da execução, uma integração pode ver a ferramenta solicitada, os argumentos, o contexto da tarefa, a identidade selecionada, o resultado da política e o estado de aprovação. Sua visibilidade real depende de onde ela está. Esses fatos descrevem uma proposta e as condições para tentá-la; não comprovam que o destino aceitou a mudança.

Para a solicitação do workspace, o registro anterior à execução pode identificar o contratado e o perfil pretendidos. Somente observações após uma tentativa podem estabelecer a resposta àquela tentativa e qualquer estado resultante. Uma resposta do serviço da ferramenta pode informar erro da API, sucesso ou ausência de resposta. O receptor precisa entender o significado desse relato antes de transformá-lo em uma conclusão sobre o acesso.

Uma consulta autorizada ao workspace pode mostrar depois que o contratado possui perfil de leitura. Isso estabelece o estado observado naquele momento. Sem evidência que vincule a alteração à solicitação tentada, não comprova qual tentativa criou o acesso nem se ele já existia. Mantenha distintas as observações de estado e as conclusões de causalidade.

O reporte de erros de ferramentas do MCP, em inglês distingue erros de protocolo de erros de execução da ferramenta. Preserve a diferença entre uma solicitação rejeitada, um erro de execução relatado e um resultado ausente. Nenhum deles deve ser silenciosamente convertido em “a mudança solicitada não ocorreu” sem evidência que sustente essa conclusão.

Quando a aprovação humana é útil?

A aprovação humana é útil quando uma pessoa designada tem o julgamento relevante e a autoridade que a política vigente não oferece. Neste exemplo, o responsável pelo workspace decide se o contratado deve receber acesso para o incidente. Uma confirmação genérica do funcionário que solicitou o acesso não atenderia a esse requisito.

A revisão deve mostrar a conta identificada do contratado, o workspace, o perfil proposto, a designação para o incidente e a identidade que realizará a mudança. Identifique qualquer fato ausente. Uma interface de aprovação que pergunta apenas se o agente pode continuar esconde a decisão que o responsável precisa tomar.

Enquanto a revisão está pendente, o executor retém a alteração de acesso. A rejeição encerra aquela proposta. Uma aprovação válida permite uma tentativa posterior somente se ainda cobrir a solicitação e as demais condições de política continuarem atendidas. Mudar o perfil para administrador gera outra proposta, não uma continuação autorizada pela aprovação de acesso de leitura.

O caminho de aprovação também precisa especificar como o executor recebe o resultado. Não se pode presumir a aplicação de uma aprovação gravada em um repositório de dados, mas nunca recebida pelo componente que aguarda. Da mesma forma, receber uma mensagem de aprovação não comprova que o destino aceitou a alteração de acesso. Mantenha separados a conclusão da revisão, a permissão para tentar e o resultado da execução.

Projete para falhas entre componentes

O significado de uma falha depende do limite que ela atravessa. Se a avaliação de política falha antes do envio, o executor precisa de uma resposta de falha definida. No fluxo hipotético, a autorização exigida do responsável continua sendo necessária; um timeout não a cria. Registre a verificação indisponível e o que o executor fez.

Se uma decisão foi emitida, mas sua resposta se perdeu, o componente que aguarda pode não saber qual foi o resultado. A correlação pode ajudar a recuperar a decisão, mas essa recuperação precisa estabelecer que ela se aplica à mesma solicitação. Um plano de controle de IA pode coordenar decisões sem tornar impossível uma perda de comunicação.

A perda de uma resposta após o envio é outro problema. Suponha que a API de gestão de membros receba a solicitação, mas o serviço da ferramenta exceda o tempo de espera. O acesso pode ter mudado. Antes de tentar novamente, determine o que pode ser estabelecido por consultas autorizadas de status ou estado e quais garantias a API oferece para solicitações repetidas. Não presuma que repetir seja inofensivo, atômico ou idempotente apenas porque a operação se chama add_member.

Mudanças feitas durante a recuperação também precisam ser avaliadas. Trocar credenciais, escolher outro workspace ou usar outro servidor pode mudar a autoridade sob a qual a tentativa opera. A aprovação do caminho que falhou não deve autorizar implicitamente uma solicitação com mudanças relevantes.

O que deve ser registrado nas passagens entre componentes?

Registre o suficiente para conectar a ação proposta, a decisão, o comportamento do executor e o resultado observado. Defina quem emite cada registro e o que ele comprova. Um evento de decisão vem do avaliador; um evento de envio precisa vir de um componente que realmente observou esse envio.

Neste exemplo, preserve uma referência à tarefa inicial, as identidades relevantes, o workspace, o perfil, as fontes de contexto, a política aplicável, a decisão e o estado de aprovação. Se houver uma tentativa, conecte o tratamento dado pelo executor à resposta do destino e a qualquer observação posterior de estado. Solicitações negadas e pendentes ainda precisam de suas próprias evidências de decisão, sem um evento de ação inventado.

Mantenha segredos fora do registro. Identifique a credencial executora por uma referência apropriada, em vez de copiar seu token, e retenha somente o conteúdo de entrada necessário à revisão. Restrinja o acesso aos registros de aprovação e atividade. Defina retenção e proteção contra alterações não autorizadas sem afirmar que um log comum é imutável.

Registre timestamps com sua origem e correlacione solicitações entre componentes. Ordenar apenas pelo horário de relógio não recupera eventos ausentes nem comprova a ordem causal entre sistemas não sincronizados. Quando o resultado não for conhecido, preserve esse estado e o motivo. Um trace que termina na resposta de um adaptador não deve sugerir confirmação de recebimento pelo destino.

Use o guia de trilha de auditoria de agentes de IA para especificar a origem, as relações e os limites de cada registro para a investigação.

Revise a arquitetura com resultados explícitos

Use um ambiente controlado e contas sintéticas para examinar as passagens antes de confiar nelas. Para o workspace hipotético, a revisão deve incluir uma solicitação de acesso de leitura com aprovação válida do responsável, uma solicitação de administrador fora do fluxo, uma aprovação pendente, uma falha de avaliação e a perda de um resultado após o envio. Esses são casos de validação propostos; nenhum desses testes foi executado para este guia.

Em cada caso, examine o que o executor realmente enviou ou reteve e compare com a solicitação proposta e a decisão. Estabeleça quais caminhos alternativos foram examinados. Um caso bem-sucedido sustenta a configuração e a operação testadas, não o controle universal de toda ferramenta ou agente.

Como a KonaSense se conecta a esses limites

O caminho Claude Code PreToolUse revisado para o Kona for Agents conecta uma operação de ferramenta proposta à avaliação de política. O adaptador pode retornar uma negação do uso da ferramenta, um pedido de aprovação ao usuário ou argumentos de ferramenta alterados. Essas são respostas do adaptador, não provas de que o host as aplicou ou de que uma ação externa teve sucesso.

A implementação revisada retorna Allow quando a avaliação falha. Outros hooks mapeiam decisões de forma diferente: uma decisão de escalonamento nem sempre se torna um pedido de aprovação, e contexto adicional não substitui necessariamente a entrada ou saída original. A revisão do responsável pelo workspace neste guia é um requisito conceitual, não uma afirmação sobre um fluxo de aprovação disponível na KonaSense.

Os caminhos revisados de submissão pelo Browser e ingestão OTLP ocupam limites diferentes. Um caminho compatível do Browser pode participar antes da submissão, sujeito ao modo e ao comportamento em falhas. Os caminhos OTLP revisados analisam a atividade exportada sem retornar uma decisão de intervenção à aplicação emissora. O pilar de governança em runtime explica esses limites por mecanismo.

Para revisar uma implementação, identifique a versão instalada, o evento, o contrato da resposta, a autorização no destino e a evidência de aplicação.