Controlo e operação de agentes - observabilidade, ferramentas, MCP, segredos, ganchos e fiabilidade

Nesta unidade, irá aprender:

• Descubra as provas e artefactos necessários para o trabalho de agente

• Como controlar ferramentas, integrações MCP e segredos de forma segura

• Como os ganchos aplicam as proteções e a registo de auditorias

• Como projetar para fiabilidade usando tentativas, escalonamento e privilégios mínimos

Provas e artefactos necessários para agentes

Um sistema agente deve produzir artefactos visíveis para cada ação significativa. Sem artefactos, não pode rever comportamentos de forma fiável, depurar falhas ou realizar análises pós-hoc.

No GitHub, a observabilidade é alcançada através de artefactos como:

• pull requests e cronogramas de PR,

• comissões e história do ramo,

• execuções de workflow e registos de trabalhos,

• verificações e resultados de análise obrigatórios, e

• Carregava artefactos do fluxo de trabalho (por exemplo, relatórios de teste).

Conjunto mínimo de observabilidade

Uma tarefa de agente bem desenhada deve produzir evidências visíveis e revisíveis usando artefactos nativos do GitHub:

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

• um pull request restrito e histórico de commits

• Links de execução do workflow para verificações obrigatórias

• artefactos carregados (por exemplo, registos ou relatórios)

• Revisão dos resultados (aprovações ou alterações solicitadas)

Carregar artefactos do fluxo de trabalho para revisão e depuração

Carregar artefactos torna as provas duráveis e revisíveis, mesmo quando os registos desaparecem.

Recomendamos a melhor prática de incluir links para execuções de workflow e artefactos relevantes na PR sob a secçã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 fiabilidade assume a falha

Sistemas fiáveis assumem que ocorrerá uma falha. Os agentes irão interpretar mal as tarefas, os testes falharão e as alterações entrarão em conflito com o comportamento existente. A sua arquitetura deve detetar falhas cedo e fornecer caminhos de recuperação seguros.

Um padrão prático de fiabilidade inclui:

• Tentativas: o agente pode atualizar o branch quando os testes falham.

• Escalada: falhas persistentes são resumidas e passadas para um humano.

• Prontidão para rollback: alterações de alto risco incluem notas de rollback e limites de âmbito.

Política de iteração segura

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

• Se uma verificação obrigatória falhar, o agente pode rever o ramo PR e repetir as verificações.

• Se a mesma verificação exigida falhar duas vezes, escale para um revisor humano com:

  • O que falhou,

  • O que foi tentado,

  • que provas existem, e

  • Qual é o próximo passo sugerido.

Esta política ajuda a prevenir ciclos infinitos e torna as falhas acionáveis.

Observabilidade como característica arquitetónica obrigatória

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

• um artefacto visível do plano,

• um PR + histórico de commits,

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

• artefactos duráveis (registos/relatórios/vestígios),

• Analise os resultados e aprovações.

Tornar a prova rastreável em relação à execução e ao estado do código

Ensinar um princípio de nomeamento/metadados

• As provas devem ser rastreáveis a uma execução de fluxo de trabalho específica e a um commit específico.

Isto auxilia nas auditorias e na depuração: pode responder "qual execução produziu este artefacto e em que estado estava o código?"

Partilhar evidências entre tarefas usando artefactos

Ensina o padrão:

• Carregar artefactos onde são produzidos

• Descarregu-os onde forem revistos ou implementados

Isto mantém as saídas inspecionáveis e utilizáveis sem que os ficheiros gerados sejam reenviados para o repositório.

Como controlar ferramentas, integrações MCP e segredos de forma segura

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

• Limite de capacidade: que ferramentas são permitidas (prefere listas de permissões)
• Limite de visibilidade: se o agente é selecionável pelo utilizador na interface interativa
• Delimitação de delegação: quais subagentes podem ser invocados e como as transferências ocorrem Diretrizes de design:
• Utilize conjuntos de ferramentas de apenas leitura para agentes de planeamento e revisão.
• Restringa as ferramentas de implementação a agentes de execução.
• Trate as alterações às listas de permissões de ferramentas como uma alteração sensível à governação.

Servidores MCP: estender ferramentas de forma segura

Os servidores MCP estendem a capacidade da ferramenta. Ensina estes padrões:

• Forma de transporte: alguns servidores MCP são endpoints remotos; outros são processos locais.
• Autenticação: os tokens devem ser injetados em tempo de execução através de limites secretos protegidos.
• Controlo do namespace: prefiro permitir um subconjunto restrito de ferramentas em vez de wildcards amplos.

Orientações operacionais:

• Adicionar ou expandir ferramentas MCP aumenta o raio de explosão e deve ser analisado 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:

• ficheiros de instruções,
• ficheiros de configuração comprometidos,
• ou workflow YAML em texto simples.

Em vez disso:

• Use limites secretos protegidos destinados à injeção em tempo de execução,
• Passar segredos apenas aos componentes que precisam,
• Analise a disponibilidade de segredos (por exemplo, por ambiente) para reduzir a exposição.

Ensina o princípio:

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

Como os ganchos aplicam as proteções e a registo de auditorias

Nos agentes GitHub Copilot, hooks são definidos como ficheiros de configuração armazenados no repositório (por exemplo, em .github/hooks/). Cada hook especifica quando é ativado e que ação realiza.

Os ganchos executam comandos personalizados em pontos específicos durante a execução do agente. Isto permite às equipas aplicar políticas, validar ações e capturar automaticamente os dados das auditorias.

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 funciona

• O gancho é executado antes de uma ferramenta ser utilizada (pré-uso da ferramenta)

• Inspeciona a ação solicitada

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

Padrões comuns de gancho

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

• Ganchos pós-ação Registo de utilização de ferramentas, resultados ou decisões para auditoria

• Ganchos de erro Capturar falhas e escalar ou disparar alertas

O que os ganchos permitem

• Aplicação de políticas de segurança (por exemplo, bloquear comandos inseguros)

• Adição de registos de auditoria para conformidade e resolução de problemas

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

• Os ganchos fornecem pontos de controlo exequíveis que operam independentemente do raciocínio do modelo. Em vez de dependerem de instruções, garantem que certas regras são sempre aplicadas durante a execução.

Como projetar para fiabilidade usando tentativas, escalonamento e privilégios mínimos

Como falámos anteriormente, os agentes acabarão por falhar, mas podemos construir sistemas que consigam detetar essas falhas e garantir que a intervenção humana as detete; por exemplo, aqui estão algumas formas de garantir que as falhas são detetadas:

• Retentativas limitadas para falhas transitórias

• Caminhos de escalonamento para falhas repetidas

• Prontidão para reverter alterações de alto risco

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

Padrão seguro para rollback a ser ensinado:

• Operar com referências explícitas (commit/tag) ao implementar configurações sensíveis, em vez de "mais recente numa ramificação".

Lembrete sobre privilégio mínimo

• Restringa as permissões do fluxo de trabalho por defeito e eleve apenas onde necessário.

Permissões de fluxo de trabalho de menor privilégio

O privilégio mínimo reduz o risco quando algo corre mal. Também impede que a automação com excesso de permissões se torne uma vulnerabilidade arquitetónica.

permissions:
  contents: read
  pull-requests: write

Esta configuração permite automação para ler conteúdos de repositórios e atualizar o contexto de PR (comentários, estados), impedindo por defeito o acesso amplo à escrita.