Controlar e operar agentes – observabilidade, ferramentas, MCP, segredos, ganchos e confiabilidade

  • 5 minutos

Nesta unidade, você aprenderá:

  • Descobrir as evidências e artefatos necessários para o trabalho do agente

  • Como controlar ferramentas, integrações mcp e segredos com segurança

  • Como os ganchos impõem guardrails e log de auditoria

  • Como projetar garantindo confiabilidade usando mecanismos de repetição, escalonamento e privilégios mínimos

Evidências e artefatos necessários para agentes

Um sistema de agente deve produzir artefatos visíveis para cada ação significativa. Sem artefatos, você não pode revisar de forma confiável o comportamento, depurar falhas ou realizar análise pós-hoc.

Em GitHub, a observabilidade é obtida por meio de artefatos como:

  • solicitações pull request e cronogramas de PR,

  • commits e histórico da ramificação

  • execuções de fluxo de trabalho e logs de tarefas

  • verificações necessárias e resultados de escaneamento, e

  • artefatos de fluxo de trabalho carregados (por exemplo, relatórios de teste).

Conjunto mínimo de observabilidade

Uma tarefa de agente bem projetada deve produzir evidências visíveis e revisáveis usando artefatos nativos de GitHub:

  • um plano estruturado, normalmente incluído em uma descrição ou discussão de pull request

  • um histórico de confirmação e pull request limitado

  • links de execução de fluxo de trabalho para verificações necessárias

  • artefatos carregados (por exemplo, registros ou relatórios)

  • examinar resultados (aprovações ou alterações solicitadas)

Carregar artefatos de fluxo de trabalho para revisão e debug

Carregar artefatos torna as evidências duráveis e revisáveis, mesmo quando os logs desaparecem da tela.

Recomendamos a prática recomendada de incluir links para execuções de fluxo de trabalho e artefatos relevantes no PR em uma seção "Evidência" para que os revisores possam validar rapidamente os resultados.

- name: Upload test results
  uses: actions/upload-artifact@v4
  with:
    name: test-results
    path: results/

A confiabilidade pressupõe falha

Os sistemas confiáveis pressupõem que a falha ocorrerá. Os agentes entenderão mal as tarefas, os testes falharão e as alterações entrarão em conflito com o comportamento existente. Sua arquitetura deve detectar falhas antecipadamente e fornecer caminhos de recuperação seguros.

Um padrão prático de confiabilidade inclui:

  • Novas tentativas: o agente pode atualizar a ramificação quando as verificações falham.

  • Escalonamento: falhas persistentes são resumidas e entregues a um humano.

  • Prontidão para reversão: alterações de alto risco incluem notas de reversão e limites de escopo.

Política de iteração segura

Use uma política previsível para iteração:

  • Se uma verificação necessária falhar, o agente poderá revisar a ramificação de PR e executar novamente as verificações.

  • Se a mesma verificação necessária falhar duas vezes, escalone para um revisor humano com:

    • o que falhou,

    • o que foi tentado,

    • que evidência existe, e

    • qual é a próxima etapa sugerida.

Essa política ajuda a evitar loops infinitos e torna as falhas acionáveis.

Observabilidade como um recurso de arquitetura necessário

Um conjunto mínimo de observabilidade para trabalho autônomo deve incluir:

  • um artefato visível do plano de projeto

  • um pr + histórico de confirmação,

  • links de execução de fluxo de trabalho para verificações necessárias,

  • artefatos duráveis (logs/relatórios/rastreamentos),

  • revisar resultados e aprovações.

Tornar as evidências rastreáveis para execução e estado de código

Ensinar um princípio de nomenclatura/metadados:

  • As evidências devem ser rastreáveis para uma execução específica de fluxo de trabalho e um commit específico.

Isso ajuda nas auditorias e na depuração: você pode responder "qual execução produziu esse artefato e em que estado do código?"

Compartilhar evidências em trabalhos usando artefatos

Ensinar o padrão:

  • Carregar artefatos onde eles são produzidos

  • Baixe-os nos locais onde são revisados ou implantados.

Isso mantém as saídas inspecionáveis e utilizáveis sem confirmar arquivos gerados de volta para o repositório.

Como controlar ferramentas, integrações mcp e segredos com segurança

A configuração de perfil do agente fornece três tipos de controle:

  • Limite de funcionalidade: quais ferramentas são permitidas (prefira listas de permissões)
  • Limite de visibilidade: se o agente é selecionável pelo usuário na interface do usuário interativa
  • Limite de delegação: quais subagentes podem ser invocados e como as entregas ocorrem Diretrizes de design:
  • Use conjuntos de ferramentas somente leitura para agentes de planejamento e revisão.
  • Restrinja as ferramentas de implementação aos agentes de execução.
  • Trate as alterações nas listas de permissões da ferramenta como uma alteração sensível à governança.

Servidores MCP: estender as ferramentas com segurança

Os servidores MCP estendem a funcionalidade da ferramenta. Ensine estes padrões:

  • Forma de transporte: alguns servidores MCP são pontos de extremidade remotos; outros são processos locais.
  • Autenticação: os tokens devem ser injetados em runtime por meio de limites secretos protegidos.
  • Controle de namespace: dê preferência a habilitar um subconjunto restrito de ferramentas em vez de caracteres curingas amplos.

Diretrizes operacionais:

  • Adicionar ou expandir ferramentas MCP aumenta o raio de explosão e deve ser revisado como uma dependência de alto risco.

Segredos e restrições de ambiente (manter segredos fora do conteúdo do repositório)

Não coloque segredos em:

  • arquivos de instruções,
  • arquivos de configuração comprometidos
  • ou YAML de fluxo de trabalho em texto simples.

Em vez disso:

  • Usar limites secretos protegidos destinados à injeção de runtime,
  • Passe segredos apenas para os componentes que precisam deles,
  • Escopar a disponibilidade de segredos (por exemplo, por ambiente) de modo a reduzir a exposição.

Ensine o princípio:

  • "O ambiente de runtime do agente tem seu próprio limite secreto; não suponha que herda automaticamente os segredos de CI do repositório."

Como os ganchos impõem guardrails e log de auditoria

Nos agentes do GitHub Copilot, os ganchos são definidos como arquivos de configuração armazenados no repositório (por exemplo, em .github/hooks/). Cada gancho especifica quando ele é executado e qual ação ele executa.

Os ganchos executam comandos personalizados em pontos específicos durante a execução do agente. Isso permite que as equipes imponham políticas, validem ações e capturem dados de auditoria automaticamente.

Um exemplo simplificado:

{
  "name": "block-high-risk-command",
  "trigger": "pre-tool-use",
  "run": "if [[ \"$TOOL\" == \"delete\" ]]; then echo 'Blocked unsafe command'; exit 1; fi"
}

Como isso funciona

  • O gancho é executado antes de uma ferramenta ser usada (antes do uso da ferramenta).

  • Verifica a ação solicitada

  • Se a ação corresponder a um padrão bloqueado, a execução será interrompida

Padrões comuns de gancho

  • Ganchos de pré-ação Validar ou bloquear ações não seguras antes da execução

  • Ganchos pós-ação Registram o uso, as saídas ou decisões de ferramentas para auditoria

  • Ganchos de erro Capturar falhas e disparar escalonamento ou alertas

Quais ganchos habilitam

  • Impor políticas de segurança (por exemplo, bloquear comandos não seguros)

  • Adicionando logs de auditoria para conformidade e depuração

  • Integração com sistemas externos (alertas, monitoramento, aprovações)

  • Os ganchos fornecem pontos de controle aplicáveis que operam independentemente do raciocínio do modelo. Em vez de depender de instruções, eles garantem que determinadas regras sejam sempre aplicadas durante a execução.

Como projetar para confiabilidade usando tentativas, escalonamento e o princípio do menor privilégio

Como falamos anteriormente, os agentes eventualmente falharão, mas podemos criar sistemas que possam capturar essas falhas e garantir que a intervenção humana a capture, por exemplo, aqui estão algumas maneiras de garantir que as falhas sejam capturadas:

  • Tentativas limitadas para falhas transitórias

  • Caminhos de escalonamento para falhas repetidas

  • Preparação para reversão de alterações de alto risco

  • Permissões de privilégio mínimo para reduzir o raio da explosão

Padrão seguro de reversão para ensinar:

  • Opere em referências explícitas (confirmação/marca) ao implantar uma configuração confidencial, em vez de "mais recente em um branch".

Lembrete de privilégios mínimos:

  • Restrinja as permissões de fluxo de trabalho por padrão e eleve-as somente quando necessário.

Permissões de fluxo de trabalho com privilégios mínimos

O privilégio mínimo reduz o risco quando algo dá errado. Ele também impede que a automação com permissão excessiva se torne uma vulnerabilidade arquitetônica.

permissions:
  contents: read
  pull-requests: write

Essa configuração permite que a automação leia o conteúdo do repositório e atualize o contexto de PR (comentários, status) ao mesmo tempo em que impede o acesso amplo à gravação por padrão.