Criar agentes de IA usando o SDK do GitHub Copilot

Concluído

Você explorou o que os agentes de IA podem fazer. Agora considere como projetar o sistema que os faz funcionar. Independentemente do cenário específico, os agentes de IA compartilham um blueprint de arquitetura comum. Esta unidade abrange os componentes fundamentais — o modelo de IA, as ferramentas, o planejador, a memória e os guardrails — que todos os sistemas de agentes exigem. Entender esse blueprint ajuda você a implementar agentes com mais eficiência quando trabalha com o SDK do GitHub Copilot.

Componentes principais de um sistema de agente de IA

Cada agente de IA, seja ele que manipula o suporte ao cliente ou monitora a infraestrutura de TI, é criado a partir do mesmo conjunto de blocos de construção arquitetônicos.

Mecanismo de raciocínio de IA

No centro do agente está um LLM (modelo de linguagem grande), como GPT-5, que interpreta instruções e gera respostas. Esse LLM é o componente que "raciocina" e decide o que fazer a seguir em cada etapa. O amplo treinamento do LLM fornece uma compreensão da linguagem e um conhecimento geral, enquanto a estrutura do agente lhe dá a capacidade de agir com base nesse raciocínio.

No SDK do GitHub Copilot, você seleciona o modelo ao configurar uma sessão. Diferentes modelos oferecem diferentes compensações entre a velocidade, o custo e a funcionalidade de raciocínio, e o SDK dá suporte à troca de modelos entre as sessões.

Tools

As ferramentas são funções externas ou APIs que o agente pode invocar durante seu processo de raciocínio. Cada ferramenta representa uma ação específica que o agente pode executar: pesquisar um registro de banco de dados, chamar uma API REST, enviar um email ou executar um comando de diagnóstico. As ferramentas são como o agente vai além da geração de texto e, na verdade, interage com sistemas reais.

Projetar o conjunto certo de ferramentas é uma decisão crítica. Você deseja dar ao agente ferramentas suficientes para ser útil, mas não tantas que ele fique confuso ou dominado. Cada ferramenta deve fazer uma coisa bem, com um nome e uma descrição claros que ajudam o modelo de IA a entender quando usá-lo.

Planner e controlador

O planejador orquestra o raciocínio e o uso da ferramenta do agente. Ele decide quando invocar uma ferramenta, quando fazer uma pergunta esclarecedora e quando produzir uma resposta final. Os agentes de IA modernos usam técnicas como o loop ReAct (Motivo + Ato), em que o agente alterna entre pensar (o LLM propõe uma etapa) e agir (chamar uma ferramenta).

O SDK do GitHub Copilot fornece esse planejador como um recurso interno. O loop de agente do SDK manipula a orquestração– você configura os componentes e o SDK gerencia o ciclo de execução de plano, ato, observação e repetição.

Memória e contexto

Ao contrário de uma chamada à API sem estado, os agentes mantêm a memória contextual durante uma sessão. O reconhecimento do agente inclui o histórico de conversas, as saídas de ferramenta e os dados recuperados durante as etapas anteriores. Memória é o que permite a coerência: quando um usuário diz "na verdade, era a cor errada", o agente sabe que "ela" se refere ao item discutido anteriormente.

O SDK do GitHub Copilot gerencia a memória de curto prazo automaticamente acompanhando o histórico de conversas em uma sessão. Para as sessões que podem exceder a janela de contexto do modelo, o recurso de sessões infinitas do SDK compacta o contexto mais antigo a fim de evitar o estouro do token, o que preserva informações essenciais.

Políticas e proteções

Como os agentes de IA tomam ações autônomas, você precisa de restrições para garantir que eles operem com segurança e conforme o esperado. Os guardrails se enquadram em várias categorias:

• Limites de escopo: defina o que o agente pode ou não fazer. Por exemplo, permita que o agente processe retornos, mas exija aprovação humana para reembolsos acima de um valor específico.
• Controles de permissão: use o gancho do OnPreToolUse SDK para interceptar chamadas de ferramenta antes de serem executadas. O gancho retorna um PermissionDecision valor (Allowou DenyAsk) que controla se a ação continua, é bloqueada ou requer confirmação do usuário.
• Filtros de segurança: instrua o agente (por meio do prompt do sistema) a permanecer dentro de seu domínio e evitar revelar informações internas.
• Fallback e escalonamento: elabore o processo para quando o agente não for capaz de resolver uma solicitação. Normalmente, essa proteção significa passar para um humano o contexto que foi reunido pelo agente.

No SDK do GitHub Copilot, os guardrails vêm de três fontes: as ferramentas que são expostas (que limitam inerentemente o que o agente pode fazer), o aviso do sistema (que orienta o comportamento) e os controles em nível de código em seus tratadores de ferramentas e ganchos de sessão.

Fluxo de trabalho do agente na prática

Quando um agente recebe uma solicitação, ele segue um fluxo de trabalho iterativo:

1. Receber entrada: o usuário envia uma mensagem ou um evento dispara o agente.
2. Motivo e plano: o LLM interpreta a entrada, identifica a meta e decide qual ação tomar primeiro.
3. Ato: o agente chama uma ferramenta (por exemplo, pesquisando um pedido no banco de dados).
4. Observe: a ferramenta retorna um resultado e o agente avalia se ela tem informações suficientes para responder.
5. Iterar ou responder: se mais informações ou ações forem necessárias, o agente retornará à etapa 2. Depois que a meta é atingida, ela produz uma resposta final.

Esse ciclo pode ser repetido várias vezes em uma única solicitação de usuário. O SDK do GitHub Copilot gerencia esse loop automaticamente por meio do mecanismo de execução do agente.

Exemplo de passo a passo

Considere como um agente de retorno de comércio eletrônico lida com uma solicitação:

1. Entrada do usuário: "Recebi o item errado, pedido 12345. Eu quero devolvê-lo.
2. Plano: O agente identifica duas metas: verificar a ordem e iniciar um retorno.
3. Chamada de ferramenta: o agente chama get_order_details(12345) para recuperar informações de pedido.
4. Observe: a ferramenta retorna os detalhes do pedido, confirmando o item e a data de entrega.
5. Chamada de ferramenta: o agente chama process_return(12345) para criar uma solicitação de retorno.
6. Observe: a ferramenta retorna um número de confirmação.
7. Responder: O agente diz ao usuário: "Criei o retorno RMA-1001 para o Order 12345 e agendoi uma retirada para amanhã. Você receberá seu reembolso em 3 a 5 dias úteis."

O agente usou duas ferramentas e raciocinou através de várias etapas, mas, do ponto de vista do usuário, foi uma única interação fluida.

Decisões de design para o SDK do GitHub Copilot

Ao criar um agente para compilar com o SDK do GitHub Copilot, concentre-se em três áreas:

• Contexto: Quais informações o agente precisa no início de cada sessão? O contexto normalmente inclui um prompt do sistema que define as diretrizes de função e comportamento do agente, além de quaisquer dados específicos do usuário que habilitem respostas personalizadas.
• Ferramentas: Quais ações o agente deve ser capaz de executar? Defina cada ferramenta com um nome claro, uma descrição e um esquema de parâmetro. Implemente a lógica de negócios no manipulador de ferramentas.
• Políticas: Quais regras o agente deve seguir? Codifique as políticas como instruções de prompt do sistema, validações de manipulador de ferramenta ou lógica de gancho de sessão.

Você também precisa planejar os modos de falha. Se uma chamada de ferramenta falhar, o agente deverá tentar novamente, tentar uma abordagem alternativa ou escalonar? Essas decisões podem ser codificadas no prompt do sistema ("se uma ferramenta retornar um erro, informar o usuário e oferecer alternativas") ou tratadas programaticamente em ganchos de tratamento de erros.

Resumo

A criação de um agente de IA envolve a definição de seus recursos de raciocínio, as ferramentas que ele pode usar, como ele mantém o contexto e os guardrails que garantem a operação segura. O SDK do GitHub Copilot fornece uma estrutura poderosa para criar agentes com esses componentes. Ao projetar cuidadosamente o prompt do sistema, selecionando as ferramentas apropriadas e implementando políticas, você pode criar agentes que fornecem valor comercial real enquanto operam dentro dos limites definidos. Na próxima unidade, você verá como aplicar esses princípios de design na prática criando um agente de exemplo com o SDK do GitHub Copilot.