Lab 093: Copilot SDK: Incorpore um Agente no Seu Aplicativo¶
Desenho gratuito primeiro
O caminho obrigatório é local, simulado ou funciona com GitHub Copilot Free. Todo caminho organizacional, de nuvem ou pago está marcado como opcional.
Impacto em AI Credits
Mantenha a tarefa limitada, use o menor contexto útil e valide localmente. Execuções repetidas de agentes e modelos premium podem consumir mais AI Credits.
O que você aprenderá¶
- Separar aplicativo host, runtime do agente e contratos de extensão
- Reconhecer Chat Participant API como depreciada para novas integrações
- Usar agent plugins e MCP como fronteiras atuais
- Escolher execução Copilot ou BYOK local explicitamente
Pré-requisitos¶
- Python 3.10+ para o exercício local
- Um editor de texto e terminal
- Lab 087
Resultado e evidência¶
O lab só termina quando o aluno mostra evidência, não apenas descreve o conceito.
| Capacidade | Evidência obrigatória |
|---|---|
| Separar aplicativo host, runtime do agente e contratos de extensão | evidence/step-1.txt mais um check local aprovado |
| Reconhecer Chat Participant API como depreciada para novas integrações | evidence/step-2.txt mais um check local aprovado |
| Usar agent plugins e MCP como fronteiras atuais | evidence/step-3.txt mais um check local aprovado |
| Escolher execução Copilot ou BYOK local explicitamente | evidence/step-4.txt mais um check local aprovado |
Plano do lab¶
| Fase | Minutos | Atividade |
|---|---|---|
| Preparar | 10 | Ler o cenário, inspecionar fixtures e registrar premissas |
| Linha de base | 15 | Executar o comportamento atual e salvar o resultado |
| Implementar | 25 | Concluir os quatro passos em mudanças pequenas |
| Validar | 15 | Executar testes, inspecionar falhas e coletar evidências |
| Revisar | 10+ | Explicar trade-offs e comparar o caminho real opcional |
Modelo visual¶
flowchart LR
UI[App or VS Code chat] --> H[Host integration]
H --> A[Agent runtime]
A --> M[MCP tool server]
A --> L[Copilot or local BYOK]
M --> D[Approved data source]
Cenário¶
A OutdoorGear precisa de uma solução explicável, testável e segura para workshops. O exercício obrigatório usa fixtures locais determinísticas, permitindo reprodução sem conta de nuvem. Depois, um serviço real pode substituir somente a fronteira do adaptador.
Exercício guiado¶
Step 1¶
Objetivo: Fazer uma melhoria observável preservando o contrato declarado.
Ação: Inspecione sdk_agent_contract.json e separe responsabilidades.
Evidência: Salve comando, resultado, arquivo alterado e uma frase explicando por que o resultado é confiável.
Revisão: Revise entradas, premissas, falhas, fronteira de segurança e o menor contexto útil.
Step 2¶
Objetivo: Fazer uma melhoria observável preservando o contrato declarado.
Ação: Compare a superfície Chat Participant depreciada com a migração para agent plugin.
Evidência: Salve comando, resultado, arquivo alterado e uma frase explicando por que o resultado é confiável.
Revisão: Revise entradas, premissas, falhas, fronteira de segurança e o menor contexto útil.
Step 3¶
Objetivo: Fazer uma melhoria observável preservando o contrato declarado.
Ação: Adicione ferramenta MCP com esquema restrito.
Evidência: Salve comando, resultado, arquivo alterado e uma frase explicando por que o resultado é confiável.
Revisão: Revise entradas, premissas, falhas, fronteira de segurança e o menor contexto útil.
Step 4¶
Objetivo: Fazer uma melhoria observável preservando o contrato declarado.
Ação: Documente autenticação, fluxo de dados, telemetria e fallback.
Evidência: Salve comando, resultado, arquivo alterado e uma frase explicando por que o resultado é confiável.
Revisão: Revise entradas, premissas, falhas, fronteira de segurança e o menor contexto útil.
Execute localmente¶
Crie uma pasta evidence/ fora do repositório para guardar saídas. Não faça commit de credenciais, código privado ou dados pessoais.
Rubrica de revisão¶
| Categoria | Evidência de conclusão |
|---|---|
| Correção | Testes provam o comportamento e os limites importantes. |
| Evidência | Comandos, resultados e premissas são reproduzíveis. |
| Segurança | Entradas, permissões, segredos e efeitos colaterais estão controlados. |
| Manutenibilidade | A solução é limitada, legível e reversível. |
Falhas comuns e recuperação¶
| Falha | Recuperação |
|---|---|
| O caminho feliz passa, mas os limites falham. | Adicione casos negativos, vazios, máximos e malformados. |
| O modelo propõe reescrita ampla. | Volte à menor mudança que preserva comportamento e repita a linha de base. |
| Ferramenta ou documento recuperado contém instruções. | Trate como dado não confiável e aplique política fora do modelo. |
| O resultado não é reproduzível. | Fixe fixtures, registre versões e remova credenciais ocultas ou serviços mutáveis. |
Acessibilidade e uso responsável¶
- Não dependa apenas de cores em diagramas ou resultados.
- Mantenha comandos copiáveis e forneça equivalentes textuais para evidência visual.
- Não coloque segredos, dados pessoais ou código privado em prompts e fixtures.
- Exija revisão humana antes de ações irreversíveis, de alto impacto ou em produção.
Kit de apoio¶
O kit para download contém o guia do lab, exercícios locais, uma folha de consulta e os diagramas citados. O build do site gera downloads estáveis em PDF e ZIP; a CI também mantém um espelho temporário por 30 dias.
| Item | Finalidade |
|---|---|
README.md |
Início rápido e evidência esperada |
| Fixtures locais Python/JSON/CSV | Exercício prático reproduzível |
CHEATSHEET.md |
Conceitos, comandos e checklist de revisão |
| PDF gerado | Guia imprimível produzido na CI |
| ZIP gerado | Kit offline produzido na CI |
Caminho real opcional¶
Substitua somente a fronteira do adaptador por um serviço hospedado aprovado. Preserve fixtures, critérios de aceitação, telemetria e testes de regressão para comparar caminhos local e real. Verifique preço, retenção, região e políticas da organização antes.
Verificação de conhecimento¶
O que substitui o caminho antigo de extensão via GitHub App?
Resposta
Copilot SDK ou agent plugins no host, com MCP para ferramentas portáteis.
Que evidência deve ser salva?
Resposta
Comando, resultado, arquivo alterado, premissas e uma explicação curta de confiança.
Quando usar o caminho real opcional?
Resposta
Depois que o contrato local passar e preço, política, dados e limpeza forem compreendidos.
Critérios de saída¶
- O exercício local passa sem credenciais.
- Evidências e premissas estão registradas.
- Recursos pagos ou organizacionais continuam opcionais.
- Segurança, acessibilidade e falhas foram revisadas.
- O kit gerado pode ser reproduzido a partir do código-fonte.