Crie uma aplicação delimitada com o Copilot SDK

Um agente incorporado a uma aplicação é diferente do assistente de desenvolvimento usado para criá-la. Argumentos de ferramentas, identidade, permissões, tempo limite, limpeza e tratamento de erros são contratos da aplicação, não detalhes de redação de prompts.

Resumo do laboratório

[!NOTE] Os gêmeos offline testam a aplicação; eles não avaliam um modelo.

Conceitos · Primeira tarefa · Lista de evidências · Redefinir

Objetivos de aprendizagem

• Teste um manipulador real de ferramenta e a orquestração de sessões sem um modelo.
• Mantenha a identidade do chamador fora dos argumentos de ferramenta fornecidos pelo modelo.
• Restrinja as ferramentas e rejeite explicitamente solicitações adicionais de permissão.
• Separe evidências de testes offline da execução autenticada opcional do SDK.

Antes de começar

Conclua a configuração do SDK e prepare 16-sdk usando o guia da unidade de trabalho. A fixture integrada em Node fixa @github/copilot-sdk em 1.0.13, cuja API com tag foi verificada em 2026-09-07. Esta é uma referência reproduzível, não uma alegação de que será sempre o pacote mais recente.

Não são necessários aplicação Blazor, LocalDB, senha de teste, pedido real de cliente, serviço de pagamento ou e-mail. Eles introduziriam contratos separados de identidade e efeitos colaterais.

Conceitos e casos de uso

Cenário do exercício

Um assistente de suporte pode consultar o status de pedidos sintéticos para um ator da fixture. Não pode iniciar um reembolso, enviar um e-mail, ler arquivos arbitrários nem confiar em um userId fornecido nos argumentos de ferramenta do modelo.

---
config:
  theme: base
  look: classic
  themeVariables:
    darkMode: false
    background: "#ffffff"
    primaryColor: "#f5f5f5"
    primaryTextColor: "#111111"
    primaryBorderColor: "#555555"
    secondaryColor: "#e0e0e0"
    secondaryTextColor: "#111111"
    secondaryBorderColor: "#666666"
    tertiaryColor: "#bdbdbd"
    tertiaryTextColor: "#111111"
    tertiaryBorderColor: "#444444"
    lineColor: "#444444"
    textColor: "#111111"
    mainBkg: "#f5f5f5"
    nodeBorder: "#555555"
    clusterBkg: "#ffffff"
    clusterBorder: "#999999"
    edgeLabelBackground: "#ffffff"
    actorBkg: "#e0e0e0"
    actorBorder: "#555555"
    actorTextColor: "#111111"
    actorLineColor: "#777777"
    signalColor: "#333333"
    signalTextColor: "#111111"
    labelBoxBkgColor: "#f5f5f5"
    labelBoxBorderColor: "#777777"
    labelTextColor: "#111111"
    loopTextColor: "#111111"
    activationBkgColor: "#bdbdbd"
    activationBorderColor: "#555555"
    noteBkgColor: "#f5f5f5"
    noteTextColor: "#111111"
    noteBorderColor: "#777777"
    attributeBackgroundColorOdd: "#f5f5f5"
    attributeBackgroundColorEven: "#e0e0e0"
---
sequenceDiagram
    accTitle: Limite da aplicação e da ferramenta do assistente de suporte
    accDescr: A aplicação fornece uma identidade confiável, abre uma sessão restrita do SDK e a consulta personalizada valida a propriedade antes de retornar um registro.
    participant Caller as Chamador
    participant Application as Aplicação
    participant Session as Sessão do SDK
    participant Tool as Consulta somente leitura
    Caller->>Application: Pergunta e ator confiável
    Application->>Session: Criar sessão restrita
    Session->>Tool: lookup_order(orderId)
    Tool-->>Session: Registro permitido ou erro explícito
    Session-->>Application: Mensagem do assistente ou falha
    Application-->>Caller: Resposta validada ou erro apresentado
    Application->>Session: Desconectar na limpeza

Legenda. As setas contínuas são chamadas; as tracejadas são retornos. A consulta recebe somente um ID de pedido; a identidade confiável é capturada pela aplicação, não escolhida pelo modelo. A chamada final representa a limpeza, não outra solicitação do usuário.

Explicação. Este contrato impede que uma ferramenta irrestrita se torne um meio de escalada de autoridade. Os testes offline exercitam a mesma orquestração com um cliente simulado; somente uma execução real explicitamente identificada exercita o SDK/runtime real.

Tarefa 1 - Inspecione e execute a linha de base offline

1. Leia catalog.mjs, app.mjs, app.test.mjs, live.mjs e o manifesto de pacotes.

2. Execute sem instalar o SDK:

   node --test --test-concurrency=1 app.test.mjs
   

3. Registre o que os testes comprovam: controle de propriedade na ferramenta, entrada ausente/inválida, política de negação, propagação de tempo limite e limpeza.

4. Eles não comprovam respostas do modelo, direito de acesso da conta ou disponibilidade na nuvem.

Tarefa 2 - Explique o projeto da ferramenta e da identidade com Ask

Trace lookup_order and its captured actor. What data can the model supply?
What prevents it from requesting another actor's order? Explain the permission
policy and why a missing tool result must not become a success-shaped answer.
Do not make a live model request.

Verifique se pedido não encontrado e propriedade não autorizada compartilham intencionalmente um resultado de indisponibilidade. Não divulgue os dados de outro ator em um erro.

Tarefa 3 - Planeje uma extensão delimitada

Adicione uma melhoria local de formatação ou outro campo somente leitura já presente na fixture. O plano deve preservar:

• o limite exato de propriedade e a validação dos argumentos;
• nenhuma gravação, shell, ferramenta de rede ou acesso arbitrário ao sistema de arquivos;
• propagação explícita de erros e limpeza;
• testes unitários para o novo comportamento.

Não implemente os reembolsos automáticos ou a alternativa de e-mail da lição original. Uma ferramenta de escrita exige projeto separado de confirmação, idempotência, auditoria e reversão.

Tarefa 4 - Implemente e valide offline

1. Peça a Agent que implemente somente a extensão aprovada.
2. Execute app.test.mjs.
3. Remova deliberadamente a verificação de propriedade e confirme que o caso entre atores falha.
4. Restaure-a e injete um erro controlado de sendAndWait. Confirme que a limpeza é executada e nenhum conteúdo de sucesso é retornado.
5. Compare o diff com o plano antes de qualquer invocação real.

Tarefa 5 - Execução autenticada opcional do SDK

1. Na cópia descartável, instale somente a dependência do SDK com versão fixada:

   npm install
   

2. Revise as referências da API com versão fixada abaixo e a configuração de ferramentas/permissões.

3. live.mjs mantém os dados do runtime dentro do workspace copiado e usa mode: "empty". Autentique-se pelo fluxo aprovado de SDK/CLI para esse runtime; o acesso pelo editor, por si só, não comprova a identidade desta aplicação.

4. Execute uma solicitação delimitada:

   node live.mjs "What is the status of order ORD-1?"
   

5. Registre a resposta real, as ferramentas invocadas, os erros e a limpeza. Se o runtime solicitar uma permissão adicional, este exemplo a rejeita; não contorne a política.

6. Marque a execução real como não realizada se o acesso ou a política estiver indisponível.

Verifique seu trabalho

• Os testes offline chamam o código real da aplicação/ferramenta.
• A identidade do ator não é aceita pelos argumentos da ferramenta.
• Solicitações desconhecidas, não autorizadas e malformadas retornam erros explícitos.
• Solicitações extras de permissão são negadas.
• A limpeza da sessão/cliente é observada após sucesso e falha.
• Evidências reais/do modelo, se houver, são identificadas separadamente das evidências offline.

Solução de problemas

Prática independente

Projete um fluxo de devolução em duas etapas: uma proposta somente leitura e depois uma gravação separada, autenticada, confirmada e idempotente. Especifique autorização, solicitações duplicadas, falha parcial, auditoria e limites de novas tentativas. Não execute reembolsos nem envie e-mails reais.

Para .NET, mapeie o mesmo contrato para as APIs atuais de sessão e liberação do SDK. Um front-end Blazor nunca deve fornecer o proprietário confiável diretamente de um formulário arbitrário. Esta adaptação é uma proposta até que você a compile e teste.

Restauração

Pare o processo real no terminal responsável por ele. Revogue qualquer autenticação exclusiva do exercício, salve evidências com informações sensíveis ocultadas e remova somente o workspace copiado e seus dados de runtime ao terminar. Não remova perfis compartilhados do Copilot nem credenciais de outro projeto.

Referências oficiais

• Referência Node do SDK v1.0.13
• Tipos do SDK com tag
• Decisões de permissão
• Autenticação do SDK
• Primeiros passos com o SDK