Contexto de execução e limites

5 minutos

Uma vez que um agente pode tomar ações e ligar-se às ferramentas, a próxima questão é onde e como essas ações são executadas.

O contexto de execução define os limites dentro dos quais um agente opera. Isto inclui o repositório a que pode aceder, a ramificação onde trabalha, o fluxo de trabalho que executa as suas tarefas e as permissões que lhe foram concedidas.

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

Nesta unidade, você aprenderá:

O que significa contexto de execução no GitHub
Como o repositório e o âmbito de ramificação definem limites
Como os fluxos de trabalho isolam a execução
Como as permissões impõem controlo sobre as ações do agente

O que é o contexto da execução?

O contexto de execução é o conjunto de restrições que definem onde um agente opera e a que pode aceder.

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

O repositório onde o agente trabalha
A filial que o agente visa
O fluxo de trabalho que está a executar tarefas
As permissões concedidas a esse fluxo de trabalho

Este contexto determina tanto a visibilidade como a capacidade.

Âmbito do repositório

Os agentes operam sempre dentro de um repositório. Eles só podem ler e modificar código dentro desse repositório. Eles interagem com problemas, pull requests e fluxos de trabalho associados a eles. Não têm acesso a outros repositórios a menos que seja concedido explicitamente.

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

Como é configurado o âmbito do repositório

Para agentes como o agente cloud Copilot, este limite é explicitamente configurado ao nível do repositório.

Para configurar isso:

Abra o seu repositório no GitHub
Clique em Definições
Na barra lateral, em Código & automação, clique em Copilot
Selecione o agente de Cloud
Ativa e configura o agente desse repositório
Guarde a sua configuração

Uma vez configurado, o agente é direcionado para esse repositório e não pode operar fora dele.

Âmbito de agente personalizado dentro de um repositório

Os agentes alfandegários operam dentro do mesmo limite do repositório, mas podem refinar ainda mais o seu âmbito através da configuração.

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

applyTo → limites em que ficheiros ou diretórios o agente se foca
Ferramentas → definem que ações o agente pode realizar

Exemplo:

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

Para configurar um agente personalizado:

Cria o diretório .github/agents/ no teu repositório
Adiciona um ficheiro agente com a extensão .agent.md
Defina o seu âmbito usando applyTo e ferramentas
Fazer commit e push do ficheiro

Isto permite que o agente se concentre apenas em partes específicas do repositório e opere com capacidades limitadas.

Como isto se enquadra no contexto da execução

O âmbito do repositório define onde o agente opera, enquanto a configuração personalizada do agente define o que o agente pode aceder e fazer dentro desse limite.

Juntos, criam controlo em camadas.

Isolamento baseado em ramificações

Os agentes não trabalham diretamente no ramo principal.

Em vez disso, eles:

Crie um novo ramo a partir do ramo que selecionou
Faça alterações dentro desse ramo
Abrir um pull request direcionado a um ramo base

Isto isola as alterações e garante que todas as modificações passam por revisão antes de serem integradas.

O isolamento baseado em ramificações é um mecanismo de segurança fundamental.

Configure um agente para usar escopo baseado em ramo

Para configurar um agente Copilot Cloud para operar com um âmbito baseado em ramos, siga os passos seguintes:

Seleção de um Ramo Base:
- Aceder à Página de Agentes: Navegue até à página de Agentes no seu repositório GitHub.
Escolha o Ramo Base: Ao delegar tarefas ao agente de codificação do Copilot, pode selecionar um ramo base específico. Isto permite que o agente crie um novo ramo com base no ramo selecionado em vez do ramo padrão (normalmente "principal").

Os agentes personalizados operam dentro de um repositório, mas eles não controlam diretamente o comportamento das ramificações. O âmbito baseado em branch é determinado pelo sistema que executa o agente.

Como funciona

Quando for usado com um agente de nuvem:

O sistema cria automaticamente uma agência
Aplica alterações
Abre um pull request

Quando utilizado em fluxos de trabalho (IC):

O fluxo de trabalho determina o ramo
O agente corre dentro desse contexto de ramo

O que os agentes de alfândega controlam

Os agentes alfandegários definem:

Em que ficheiros se focam (applyTo)
Que ações podem realizar (ferramentas)
Como se comportam (instruções)

Mas não definem:

Criação de filiais
Comportamento dos pull requests
Isolamento de execução

O âmbito baseado em ramificação é sempre aplicado pelo contexto de execução, não pelo próprio agente personalizado.

Permitir que um agente realize ações autónomas, incluindo a criação de branches e pull requests

Os agentes podem realizar ações autónomas dentro de um repositório depois de estarem ativados e receberem uma tarefa.

Passos:

Ativa o agente do repositório.
- Vá a Definições → Copilot → Cloud Agent
- Ativar o agente, selecionar o repositório
Atribui uma tarefa ao agente.
- De um problema, do Copilot Chat ou da interface dos agentes
- Exemplo: corrigir um bug, implementar uma funcionalidade
Permita que o agente execute a tarefa.

O agente irá:
- Criar uma ramificação
- Fazer alterações no código
- Confirmar e enviar atualizações por push
Reveja e finalize.

Quando estiveres satisfeito com as alterações ao código e os resultados, ativa um pull request. Podes pedir alterações no pull request, ou avançar e fundir.

O agente trabalha de forma autónoma dentro do repositório, criando branches, modificando código e abrindo pull requests, mantendo-se a operar dentro de um fluxo de trabalho controlado e revisável.

Limites do fluxo de trabalho

A execução ocorre dentro de fluxos de trabalho alimentados pelo GitHub Actions. Cada fluxo de trabalho define o que desencadeia a execução, que passos são realizados e em que ambiente o código corre. Os fluxos de trabalho funcionam como contentores de execução controlados. Garantem que as tarefas correm num ambiente limpo, a execução é repetível e que os registos e resultados são capturados. Os fluxos de trabalho são também a forma como o comportamento dos agentes é executado em ambientes de CI.

Limites de permissões

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

Os fluxos de trabalho recebem permissões através de tokens, como o GITHUB_TOKEN.

Estas permissões podem permitir ou restringir:

Leitura do conteúdo do repositório
Escrever código
Criação de pull requests
Aceder a segredos
Ativação de fluxos de trabalho

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

Guarda-raias nos fluxos de trabalho agentes do GitHub

Os fluxos de trabalho agentes do GitHub são concebidos com defesa em profundidade. Controlos-chave incluem:

Tokens de somente leitura por padrão para que o agente possa inspecionar o estado do repositório sem alterar diretamente.
Saídas seguras que permitem ao agente propor ações enquanto um passo separado com bloqueio decide o que é permitido
Zero segredos no processo do agente, mantendo credenciais sensíveis fora do runtime usado pelo agente de codificação
Execução em ambiente isolado e containerizado
Isolamento de rede e acesso autorizado de saída
Deteção de ameaças que analisa as saídas propostas antes de ser aplicada qualquer ação de escrita

Este modelo ajuda a reduzir os riscos de agentes sobrevalorizados, injeção rápida e alterações não intencionais do repositório.

Porque é que os limites importam

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

Combinando:

Âmbito do repositório
Isolamento dos ramos
Execução do fluxo de trabalho
Controlo de permissões

O GitHub garante que os agentes operam dentro de limites claros e aplicáveis.

Isto previne:

Alterações descontroladas ao código de produção
Acesso a recursos não intencionais
Execução insegura ou não revista

Como os agentes são invocados através dos fluxos de trabalho

Para executar tarefas orientadas por agentes como parte do CI, invoca-as dentro de um fluxo de trabalho. Nesta configuração, o fluxo de trabalho torna-se o limite de execução, e o agente executa-se dentro do runner usando passos e permissões definidos.

Passos:

Crie ou abra um ficheiro de workflow no seu repositório: .github/workflows/agent-task.yml
Defina quando o fluxo de trabalho deve correr:
```
on:
 workflow_dispatch: 
schedule: - cron: '0 9 * * *' 
```
Também podes usar eventos como push ou pull_request dependendo do teu caso de uso.
Definir permissões de fluxo de trabalho:
```
permissions: 
    contents: read
```
Ajusta as permissões com base no que o fluxo de trabalho precisa de fazer.

Defina um trabalho e um corredor:

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

Consulta o repositório:
```
uses: actions/checkout@v4
```

Configurar Node.js:

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

Forneça autenticação:

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

Executar a tarefa do agente:

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

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 corre num runner definido, com um trigger definido, dentro de um contexto de repositório definido, e apenas com as permissões concedidas a esse fluxo de trabalho.

Âmbito de ramificação e execução do fluxo de trabalho

Os fluxos de trabalho correm contra um ramo específico.

Como os agentes fazem alterações num ramo:

A execução do fluxo de trabalho é limitada a esse ramo
As alterações são isoladas do ramo padrão
A validação ocorre antes da fusão

Isto assegura que a atividade do agente permanece contida dentro de um âmbito de execução controlado.

Principal conclusão

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

De seguida, aprenderás a desenhar caminhos de execução seguros, incluindo tentativas de repetição, rollbacks (reversão) e mecanismos de escalonamento.

Comentários

Esta página foi útil?