Contexto e limites de execução

  • 5 minutos

Depois que um agente pode executar ações e se conectar às ferramentas, a próxima pergunta é onde e como essas ações são executadas.

O contexto de execução define os limites nos quais um agente opera. Isso inclui o repositório ao qual ele pode acessar, o branch no qual ele opera, o fluxo de trabalho que realiza suas tarefas e as permissões que lhe são concedidas.

Sem um contexto de execução claramente definido, o comportamento do agente torna-se imprevisível e não seguro.

Nesta unidade, você aprenderá:

  • O que o contexto de execução significa em GitHub
  • Como o repositório e o escopo do branch definem limites
  • Como os fluxos de trabalho isolam a execução
  • Como as permissões impõem o controle sobre as ações do agente

O que é o contexto de execução?

O contexto de execução é o conjunto de restrições que define onde um agente opera e o que ele pode acessar.

Em GitHub, o contexto de execução inclui:

  • O repositório no qual o agente está trabalhando
  • A ramificação que o agente está visando
  • O fluxo de trabalho que está executando tarefas
  • As permissões concedidas a esse fluxo de trabalho

Esse contexto determina a visibilidade e a funcionalidade.

Escopo do repositório

Os agentes sempre operam dentro de um repositório. Eles só podem ler e modificar o código dentro desse repositório. Eles interagem com problemas, solicitações de pull e fluxos de trabalho vinculados a ele. Eles não têm acesso a outros repositórios, a menos que sejam concedidos explicitamente.

O escopo do repositório é o primeiro limite que limita o comportamento do agente.

Como o escopo do repositório está configurado

Para agentes como o agente de nuvem Copilot, esse limite é configurado explicitamente no nível do repositório.

Para configurar isso:

  1. Abra o repositório no GitHub
  2. Clique em Configurações
  3. Na barra lateral, em Código & automação, clique em Copilot
  4. Selecionar agente de nuvem
  5. Habilitar e configurar o agente para esse repositório
  6. Salvar sua configuração

Depois de configurado, o agente está limitado a esse repositório e não pode operar fora dele.

Escopo do agente personalizado em um repositório

Os agentes personalizados operam dentro do mesmo limite do repositório, mas podem refinar ainda mais seu escopo por meio da configuração.

Dentro de um arquivo de agente personalizado (por exemplo, .github/agents/security-reviewer.agent.md), o escopo é definido usando campos como:

  • applyTo → limita em quais arquivos ou diretórios o agente se concentra
  • ferramentas → define quais ações o agente pode executar

Exemplo:

applyTo:
    - '**/*.js'
    - 'src/auth/**' tools:
    - read_file
    - search_files

Para configurar um agente personalizado:

  1. Criar o diretório .github/agents/em seu repositório
  2. Adicionar um arquivo de agente com a extensão .agent.md
  3. Defina seu escopo usando applyTo e ferramentas
  4. Confirmar e enviar por push o arquivo

Isso permite que o agente se concentre apenas em partes específicas do repositório e opere com recursos limitados.

Como isso se encaixa no contexto de execução

O escopo do repositório define onde o agente opera, enquanto a configuração do agente personalizado define o que o agente pode acessar e fazer dentro desse limite.

Juntos, eles criam controle em camadas.

Isolamento baseado em ramificação

Os agentes não trabalham diretamente no ramo principal.

Em vez disso, eles:

  • Criar uma nova branch a partir da branch que você selecionou
  • Fazer alterações dentro desse branch
  • Abrir um pull request direcionado para um branch base

Isso isola as alterações e garante que todas as modificações passem pela revisão antes de serem mescladas.

O isolamento baseado em ramificação é um mecanismo de segurança chave.

Configurar um agente para usar o escopo baseado em branch

Para configurar um agente do Copilot Cloud para operação com um escopo baseado em ramificação, siga estas etapas:

  1. Selecionando um Ramo Base:
    • Acesse a página de Agentes: navegue até a página de Agentes no repositório GitHub.
  2. Escolha o Branch Base: ao delegar tarefas para o agente de codificação Copilot, você pode selecionar um branch base específico. Isso permite que o agente crie uma nova ramificação com base no branch selecionado em vez do branch padrão (geralmente "principal").

Os agentes personalizados operam em um repositório, mas não controlam diretamente o comportamento do branch. O escopo baseado em ramificação é determinado pelo sistema que executa o agente.

Como funciona

Quando usado com um agente de nuvem:

  • O sistema cria automaticamente um branch
  • Aplica alterações
  • Abre uma solicitação de pull

Quando usado em fluxos de trabalho (CI):

  • O fluxo de trabalho determina a ramificação
  • O agente atua nesse contexto de branch

O que agentes personalizados controlam

Os agentes personalizados definem:

  • Em quais arquivos eles se concentram (applyTo)
  • Quais ações eles podem executar (ferramentas)
  • Como eles se comportam (instruções)

Mas eles não definem:

  • Criação de ramificação
  • Comportamento do pull request
  • Isolamento de execução

O escopo baseado em branch é sempre imposto pelo contexto de execução, não pelo agente personalizado em si.

Habilitar um agente para executar ações autônomas, incluindo a criação de branches e pull requests

Os agentes podem executar ações autônomas em um repositório quando estiverem habilitados e receberem uma tarefa.

Steps:

  1. Habilite o agente para o repositório.

    • Ir para Configurações → Copilot → Agente de Nuvem
    • Habilite o agente, selecione o repositório

  2. Atribua uma tarefa ao agente.

    • De um problema, Copilot Chat ou da interface de agentes
    • Exemplo: corrigir um bug, implementar um recurso

  3. Permitir que o agente execute a tarefa.

    O agente:

    • Criar um branch
    • Fazer alterações de código
    • Confirmar e enviar atualizações por push

  4. Examine e finalize.

    Depois de estar satisfeito com as alterações de código e os resultados, dispare uma solicitação de pull. Você pode solicitar alterações no pull request ou simplesmente fazer o merge.

O agente funciona de forma autônoma dentro do repositório criando branches, modificando o código e abrindo solicitações de pull, enquanto ainda está operando dentro de um fluxo de trabalho controlado e revisível.

Limites de fluxo de trabalho

A execução ocorre dentro de fluxos de trabalho alimentados por GitHub Actions. Cada fluxo de trabalho define o que aciona a execução, quais etapas são realizadas e em qual ambiente o código é executado. Os fluxos de trabalho atuam como contêineres de execução controlados. Elas garantem que as tarefas sejam executadas em um ambiente limpo, a execução seja repetível e os logs e os resultados sejam capturados. Fluxos de trabalho também são como o comportamento do agente é executado em ambientes de CI.

Limites de permissão

As permissões definem o que um agente pode fazer em seu contexto de execução.

Fluxos de trabalho recebem permissões por meio de tokens, como o GITHUB_TOKEN.

Essas permissões podem permitir ou restringir:

  • Ler conteúdo do repositório
  • Escrevendo código
  • Criando solicitações de pull
  • Acessando segredos
  • Disparando fluxos de trabalho

As permissões sempre devem ser definidas explicitamente e minimizadas.

Guardrails em fluxos de trabalho GitHub agentic

GitHub fluxos de trabalho de agentes são projetados com defesa em profundidade. Os principais controles incluem:

  • Tokens somente leitura por padrão para que o agente possa inspecionar o estado do repositório sem alterá-lo diretamente
  • Saídas seguras que permitem que o agente proponha ações enquanto uma etapa fechada separada decide o que é permitido
  • Zero segredos no processo do agente, mantendo credenciais confidenciais fora do runtime usado pelo agente de codificação
  • Execução em área restrita e em contêineres
  • Isolamento de rede e acesso de saída permitido
  • Detecção de ameaças que verifica as saídas propostas antes de qualquer ação de gravação ser aplicada

Esse modelo ajuda a reduzir os riscos de agentes superprivilegiados, inserção de prompt e alterações de repositório não intencionais.

Por que os limites importam

O contexto de execução é o que torna os sistemas de agente seguros.

Combinando:

  • Escopo do repositório
  • Isolamento de ramificação
  • Execução do fluxo de trabalho
  • Controle de permissão

GitHub garante que os agentes operem dentro de limites claros e executáveis.

Isso impede:

  • Alterações descontroladas no código de produção
  • Acesso a recursos não intencionais
  • Execução não segura ou não revisada

Como os agentes são invocados por meio de fluxos de trabalho

Para executar tarefas controladas por agente como parte da CI, você as invoca dentro de um fluxo de trabalho. Nessa configuração, o fluxo de trabalho se torna o limite de execução e o agente é executado dentro do executor usando as etapas e permissões definidas.

Steps:

  1. Crie ou abra um arquivo de fluxo de trabalho em seu repositório: .github/workflows/agent-task.yml

  2. Defina quando o fluxo de trabalho deve ser executado:

    on:
 workflow_dispatch: 
schedule: - cron: '0 9 * * *'

    Você também pode usar eventos como push ou pull_request dependendo do seu caso de uso.

  3. Definir permissões de fluxo de trabalho:

    permissions: 
    contents: read

    Ajuste as permissões com base no que o fluxo de trabalho precisa fazer.

  4. Definir um trabalho e um ambiente de execução:

    jobs: 
	agent-task: 
		runs-on: ubuntu-latest

  5. Confira o repositório:

    uses: actions/checkout@v4

  6. Configurar Node.js:

    uses: actions/setup-node@v4 
with: node-version: '18'

  7. Forneça autenticação:

    env: COPILOT_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  8. Execute a tarefa do agente:

    run: | npx @github/copilot-cli 
-p "Summarize recent changes in this repository" 
--no-ask-user (Optional)

  9. Use um agente personalizado:

    run: | npx @github/copilot-cli 
--agent security-reviewer 
-p "Review this code for vulnerabilities" 
--no-ask-user

O fluxo de trabalho torna-se o caminho de execução controlado para o agente. A tarefa é executada em um executor definido, com um gatilho definido, dentro de um contexto de repositório definido e com apenas as permissões concedidas a esse fluxo de trabalho.

Escopo do branch e execução de fluxo de trabalho

Os fluxos de trabalho são executados em um branch específico.

Como os agentes fazem alterações em um branch:

  • ** A execução do fluxo de trabalho está limitada a esse branch.
  • As alterações são isoladas do branch padrão
  • A validação ocorre antes da mesclagem

Isso garante que a atividade do agente permaneça contida dentro de um escopo de execução controlado.

Conclusão principal

O contexto de execução define onde os agentes operam. Limites como escopo de repositório, isolamento de ramificação, fluxos de trabalho e permissões garantem que as ações do agente permaneçam controladas, previsíveis e seguras.

Em seguida, você aprenderá a projetar caminhos de execução seguros, incluindo repetições, reversões e mecanismos de escalonamento.