Como os agentes interagem com APIs GitHub e fluxos de trabalho

  • 5 minutos

Os agentes de IA estão mudando a forma como o trabalho de desenvolvimento é feito. Em vez de navegar manualmente em repositórios, escrever código e executar comandos, os agentes podem operar diretamente dentro de GitHub para concluir tarefas do início ao fim.

GitHub dá suporte ao trabalho controlado por agente por meio de várias camadas. Os agentes podem usar as APIs do GitHub para ler o estado do repositório e realizar ações, os fluxos de trabalho do GitHub Actions para executar automações em executores controlados e os GitHub Agentic Workflows para descrever tarefas de nível superior do repositório em Markdown e executá-las com agentes de codificação sob rigorosas medidas de segurança. Em vez de ignorar GitHub, os agentes trabalham com os mesmos sistemas que os desenvolvedores usam, incluindo branches, solicitações de pull, problemas e automação.

Nesta unidade, você aprenderá:

  • Como os agentes interagem com GitHub por meio de APIs
  • Como os agentes usam fluxos de trabalho como ambientes de execução
  • Como as alterações do repositório são criadas e gerenciadas
  • Como é um fluxo de execução de agente completo no GitHub

Como os agentes interagem com GitHub

Agentes do GitHub, como o agente de nuvem Copilot, operam dentro de um contexto de repositório e branch definido. Quando você atribui uma tarefa, por exemplo, por meio de um problema ou prompt, o agente começa a trabalhar dentro desse repositório.

Os agentes podem:

  • Pesquisar e entender o repositório
  • Planejar as alterações necessárias para concluir uma tarefa
  • Fazer alterações de código em um novo branch
  • Abrir uma solicitação de pull para revisão

Os agentes executam essas ações usando GitHub recursos de plataforma, como APIs e fluxos de trabalho.

Essas ações podem ser disparadas por eventos de repositório (como push ou solicitação de pull), executadas em horários agendados ou orquestradas por meio de fluxos de trabalho automáticos que continuamente automatizam tarefas do repositório ao longo do tempo.

Usando APIs de GitHub para executar ações

GitHub fornece APIs que permitem que os sistemas interajam com repositórios programaticamente.

As APIs habilitam ações como:

  • Criação de ramificações e commits
  • Lendo dados do repositório
  • Abrir e atualizar solicitações de pull
  • Disparando fluxos de trabalho

Todas as solicitações de API devem ser autenticadas usando tokens, como tokens de acesso pessoal, tokens de aplicativo GitHub ou os GITHUB_TOKEN fornecidos em fluxos de trabalho.

Isso garante que todas as ações executadas por um agente sejam controladas por permissão e auditáveis.

Como os agentes criam alterações em um repositório

Quando um agente faz alterações, ele segue o mesmo fluxo de trabalho que um desenvolvedor. Uma sequência típica tem esta aparência:

  1. Selecionar um branch base
  2. Criar um novo ramo de trabalho
  3. Modificar ou criar arquivos
  4. Confirmar alterações
  5. Abrir uma solicitação de pull

Há operações de API separadas para cada uma dessas etapas, incluindo trabalhar com referências do Git, conteúdo do repositório e solicitações de pull.

Isso significa que as ações do agente estão totalmente alinhadas com o modelo de desenvolvimento padrão do GitHub.

Usando GitHub Actions como a camada de execução

Os agentes não executam tarefas diretamente em seu computador. Em vez disso, GitHub fornece ambientes de execução por meio de fluxos de trabalho alimentados por GitHub Actions.

Um fluxo de trabalho é um processo definido por YAML que executa trabalhos em resposta a eventos.

Os agentes dependem desses fluxos de trabalho para:

  • Executar testes
  • Validar alterações
  • Executar tarefas de automação
  • Implantar aplicativos

Copilot agente de nuvem opera em um ambiente alimentado por GitHub Actions, o que significa que os fluxos de trabalho formam a base da execução do agente.

Fluxos de trabalho tradicionais versus fluxos de trabalho agente

Fluxos de trabalho de GitHub Actions tradicionais geralmente são determinísticos e definidos por YAML: você especifica explicitamente cada etapa, gatilho e condição. Fluxos de Trabalho Agentic do GitHub introduzem um modelo diferente para a automação de repositórios. Eles permitem que você descreva o resultado desejado em Markdown, defina guardrails no frontmatter e execute essa intenção usando um agente de codificação em GitHub Actions. Elas são mais adequadas para tarefas de repositório abertas, mas limitadas, como triagem, relatórios, manutenção da documentação, análise de falhas de CI e melhoria de código. Eles não substituem os pipelines de CI/CD; eles os ampliam com o que o GitHub descreve como “IA contínua”.

O que torna um fluxo de trabalho agente diferente

Um fluxo de trabalho GitHub agentic tem duas partes principais:

  • Frontmatter para configurações como gatilhos, permissões, ferramentas e saídas seguras
  • Instruções de Markdown que descrevem o trabalho em linguagem natural

O Markdown expressa a intenção, enquanto o frontmatter define os limites. Em seguida, o fluxo de trabalho é compilado em um lock file que o GitHub Actions executa.

on: schedule: daily
permissions: contents: read issues: read pull-requests: read
safe-outputs: create-issue: title-prefix: "[repo-status] " labels: [report]
tools: github:

Daily Repository Status Report
Create a daily report for maintainers.
Include:
Recent activity (issues, PRs, commits)
Key highlights and risks
Recommended next steps
Keep the report concise and link to relevant issues and pull requests.

Neste exemplo, o frontmatter (entre ---) define como e quando o fluxo de trabalho é executado, o que ele pode acessar e quais ações são permitidas.

O Markdown abaixo define a intenção do fluxo de trabalho em linguagem natural. Um agente interpreta essa intenção e produz saídas estruturadas, que são aplicadas por meio de etapas controladas e revisíveis.

Ao contrário dos fluxos de trabalho de GitHub Actions tradicionais, que definem explicitamente cada etapa, os fluxos de trabalho agente se concentram na descrição dos resultados. O agente determina como alcançar a meta dentro das restrições definidas no frontmatter.

Iniciando e interagindo com fluxos de trabalho

Os fluxos de trabalho podem ser disparados de várias maneiras:

  • Automaticamente por meio de eventos como push ou pull request
  • Usar manualmente o evento workflow_dispatch
  • Programaticamente por meio da API de GitHub

Os agentes podem contar com esses gatilhos para executar tarefas ou validar alterações depois de fazer atualizações em um repositório.

Cada execução de fluxo de trabalho executa trabalhos em ambientes isolados, garantindo a execução consistente e segura.

O que acontece durante uma sessão de agente

Sessões de agentes como observáveis e interativas.

Durante uma sessão, você pode:

  • Monitorar o progresso por meio de um log de sessão
  • Veja quais ações o agente está tomando
  • Fornecer comentários ou ajustar a tarefa
  • Revisar a solicitação de pull final

O agente se adapta com base nos comentários e continua trabalhando até que a tarefa seja concluída.

Fluxo de execução de agente de ponta a ponta

Juntando tudo, uma interação típica do agente com GitHub tem esta aparência:

  1. Uma tarefa é atribuída por meio de um problema, chat ou CLI
  2. O agente seleciona o repositório e o ramo base
  3. O agente analisa a base de código e planeja mudanças.
  4. As operações de API são usadas para criar ramificações e commits.
  5. Uma solicitação de pull é aberta
  6. Fluxos de trabalho são executados para validar ou implantar alterações
  7. O usuário analisa, aprova ou solicita atualizações

Esse fluxo garante que toda a atividade do agente seja:

  • Vinculado a um repositório
  • Controlado por permissões
  • Executado por meio de fluxos de trabalho
  • Visível e revisível

Conclusão principal

Agentes em GitHub não operam fora da plataforma. Eles interagem por meio de APIs, fluxos de trabalho e estruturas de repositório que impõem permissões, fornecem ambientes de execução e permitem a colaboração por meio de solicitações de pull.

Em seguida, você aprenderá como o PROTOCOLO MCP (Model Context Protocol) estende esses recursos, permitindo que os agentes se conectem a ferramentas e serviços adicionais além de GitHub.