Crear una aplicación acotada con Copilot SDK

Un agente integrado en una aplicación es distinto del asistente de desarrollo usado para crearla. Los argumentos de herramientas, la identidad, los permisos, el tiempo de espera, la limpieza y la gestión de errores son contratos de la aplicación, no detalles de redacción de prompts.

Resumen del laboratorio

[!NOTE] Los dobles offline prueban la aplicación; no evalúan un modelo.

Conceptos · Primera tarea · Lista de evidencias · Restablecer

Objetivos de aprendizaje

• Prueba un controlador real de herramienta y la orquestación de sesiones sin un modelo.
• Mantén la identidad del llamador fuera de los argumentos de herramientas proporcionados por el modelo.
• Restringe las herramientas y rechaza explícitamente las solicitudes adicionales de permisos.
• Separa la evidencia de pruebas sin conexión de la ejecución opcional autenticada del SDK.

Antes de empezar

Completa la configuración del SDK y prepara 16-sdk usando la guía de la unidad de trabajo. El fixture integrado de Node fija @github/copilot-sdk en 1.0.13, cuya API etiquetada se comprobó el 2026-09-07. Esta es una referencia reproducible, no una afirmación de que siempre será el paquete más reciente.

No se requiere una aplicación Blazor, LocalDB, contraseña de prueba, pedido real de cliente, servicio de pago ni de correo. Estos introducirían contratos separados de identidad y efectos secundarios.

Conceptos y casos de uso

Escenario del ejercicio

Un asistente de soporte puede consultar el estado de pedidos sintéticos para un actor del fixture. No puede iniciar un reembolso, enviar un correo, leer archivos arbitrarios ni confiar en un userId proporcionado en los argumentos de herramienta del 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: Límite de la aplicación del asistente de soporte y su herramienta
    accDescr: La aplicación proporciona una identidad confiable, abre una sesión restringida del SDK y la consulta personalizada valida la propiedad antes de devolver un registro.
    participant Caller
    participant Application
    participant Session as Sesión del SDK
    participant Tool as Consulta de solo lectura
    Caller->>Application: Pregunta y actor confiable
    Application->>Session: Crear sesión restringida
    Session->>Tool: lookup_order(orderId)
    Tool-->>Session: Registro permitido o error explícito
    Session-->>Application: Mensaje del asistente o fallo
    Application-->>Caller: Respuesta validada o error mostrado
    Application->>Session: Desconectar durante la limpieza

Leyenda. Las flechas continuas son llamadas; las discontinuas son retornos. La consulta recibe solo un ID de pedido; la identidad confiable la captura la aplicación, no la elige el modelo. La llamada final representa la limpieza, no otra solicitud del usuario.

Explicación. Este contrato impide que una herramienta sin restricciones se convierta en una escalada de autoridad. Las pruebas sin conexión ejecutan la misma orquestación con un cliente falso; solo una ejecución real explícitamente etiquetada ejercita el SDK y el entorno de ejecución reales.

Tarea 1 - Inspeccionar y ejecutar la línea base sin conexión

1. Lee catalog.mjs, app.mjs, app.test.mjs, live.mjs y el manifiesto de paquetes.

2. Ejecuta sin instalar el SDK:

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

3. Registra lo que demuestran las pruebas: propiedad en la herramienta, entradas ausentes o no válidas, política de denegación, propagación de tiempos de espera agotados y limpieza.

4. No demuestran las respuestas del modelo, el derecho de acceso de la cuenta ni la disponibilidad de la nube.

Tarea 2 - Explicar el diseño de la herramienta y la identidad con 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.

Verifica que un pedido no encontrado y una propiedad no autorizada compartan un resultado intencional de no disponibilidad. No reveles datos de otro actor en un error.

Tarea 3 - Planificar una ampliación acotada

Añade una mejora local de formato u otro campo de solo lectura ya presente en el fixture. El plan debe preservar:

• el límite exacto de propiedad y la validación de argumentos;
• ninguna escritura, shell, herramienta de red ni acceso arbitrario al sistema de archivos;
• propagación explícita de errores y limpieza;
• pruebas unitarias del comportamiento nuevo.

No implementes los reembolsos automáticos ni la alternativa por correo de la lección original. Una herramienta de escritura requiere un diseño separado de confirmación, idempotencia, auditoría y reversión.

Tarea 4 - Implementar y validar sin conexión

1. Pide a Agent que implemente únicamente la ampliación aprobada.
2. Ejecuta app.test.mjs.
3. Elimina deliberadamente la comprobación de propiedad y confirma que falle el caso entre actores.
4. Restáurala e inyecta un error controlado de sendAndWait. Confirma que se ejecute la limpieza y que no se devuelva contenido de éxito.
5. Compara el diff con el plan antes de cualquier invocación real.

Tarea 5 - Ejecución opcional autenticada del SDK

1. En la copia desechable, instala únicamente la dependencia del SDK con versión fijada:

   npm install
   

2. Revisa las referencias de la API fijada que aparecen abajo y la configuración de herramientas y permisos.

3. live.mjs mantiene los datos del entorno de ejecución dentro del espacio de trabajo copiado y usa mode: "empty". Autentícate mediante el flujo aprobado de SDK/CLI para ese entorno; el acceso al editor por sí solo no demuestra la identidad de esta aplicación.

4. Ejecuta una solicitud acotada:

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

5. Registra la respuesta real, las herramientas invocadas, los errores y la limpieza. Si el entorno de ejecución solicita un permiso adicional, este ejemplo lo rechaza; no eludas la política.

6. Marca la ejecución real como no realizada si el acceso o las políticas no la permiten.

Verifica tu trabajo

• Las pruebas sin conexión llaman al código real de la aplicación y la herramienta.
• No se acepta la identidad del actor desde los argumentos de la herramienta.
• Las solicitudes desconocidas, no autorizadas y mal formadas devuelven errores explícitos.
• Se deniegan las solicitudes adicionales de permisos.
• Se observa la limpieza de sesión y cliente tanto tras el éxito como tras el fallo.
• La evidencia real o del modelo, si existe, se etiqueta por separado de la evidencia sin conexión.

Solución de problemas

Práctica independiente

Diseña un flujo de devolución de dos pasos: una propuesta de solo lectura y después una escritura separada, autenticada, confirmada e idempotente. Especifica autorización, solicitudes duplicadas, fallo parcial, auditoría y límites de reintentos. No ejecutes reembolsos ni correos reales.

Para .NET, relaciona el mismo contrato con las API actuales de sesiones y liberación de recursos de su SDK. Una interfaz Blazor nunca debe proporcionar el propietario confiable directamente desde un formulario arbitrario. Esta adaptación es una propuesta hasta que la compiles y pruebes.

Restablecimiento

Detén el proceso real en su terminal de origen. Revoca cualquier autenticación exclusiva del ejercicio, guarda evidencia con los datos sensibles ocultos y elimina solo los datos del espacio de trabajo copiado y su entorno de ejecución al terminar. No elimines perfiles compartidos de Copilot ni credenciales de otro proyecto.

Referencias oficiales

• Referencia de Node del SDK v1.0.13
• Tipos del SDK etiquetado
• Decisiones de permisos
• Autenticación del SDK
• Primeros pasos con el SDK