# Construye tu propio kit de agente > [!NOTE] > Los kits son experimentales. El formato de archivo de los kits, los comandos de la CLI y la experiencia para crear, cargar y gestionar kits están sujetos a cambios a medida que la característica evoluciona. Comparte comentarios y reportes de errores en el repositorio [docker/sbx-releases](https://github.com/docker/sbx-releases). Este tutorial describe el proceso de construcción de un kit de agente para el agente de codificación [Amp](https://ampcode.com/). Cada paso explica la decisión detrás de una parte de la especificación, de modo que puedas aplicar el mismo razonamiento a otros agentes. Para obtener una referencia de cada campo, consulta la página de [Kits](/ai/sandboxes/customize/build-an-agent/kits/). Este tutorial se centra en el proceso. El kit terminado también está publicado como un ejemplo ejecutable en [docker/sbx-kits-contrib](https://github.com/docker/sbx-kits-contrib/tree/main/amp), lo cual es útil como referencia a medida que avanzas. ## Elegir una imagen base Un kit de agente necesita una imagen de contenedor que cumpla con los [requisitos de la imagen base](/ai/sandboxes/customize/build-an-agent/kits/#base-image-requirements): usuario `agent` sin privilegios de root con UID 1000, sudo sin contraseña, directorio de inicio en `/home/agent/` y reenvío de variables de entorno de proxy HTTP. En un principio, en lugar de compilar una imagen desde cero, puedes ampliar una de las plantillas de sandbox publicadas. Tres puntos de partida comunes: - `docker/sandbox-templates:shell`: Base genérica sin ningún agente preinstalado. - `docker/sandbox-templates:shell-docker`: Igual que la anterior, pero con Docker Engine dentro del sandbox. - Variantes específicas de agentes (`claude-code`, `codex`, etc.): Solo son útiles si estás haciendo la ampliación de ese agente específico. Para Amp, elige `shell-docker`: - Amp no está preinstalado en ninguna variante, por lo que necesitas una base genérica (`shell`). - El soporte de Docker es útil, ya que los agentes de codificación a menudo necesitan ejecutar contenedores. - Si no necesitas Docker dentro del sandbox, usa la etiqueta `shell` para obtener un entorno más ligero y sin privilegios. ## Planificar la autenticación Amp se autentica con una clave de API en `AMP_API_KEY`. Para mantener la clave real fuera de la VM, se divide el trabajo en dos partes: - La sección de red del kit mapea el host de la API a un identificador de servicio y le indica al proxy qué cabecera inyectar. - Proporcionas tu clave una vez en el host, a través del almacén de secretos de sbx. El valor real permanece en el host; al sandbox solo llega un marcador de posición (placeholder). Dentro del sandbox, `AMP_API_KEY` se configura con ese marcador de posición. El proxy sustituye la clave real en las solicitudes salientes al host de la API, por lo que el secreto nunca llega al sandbox. En una sección posterior se detalla el comando específico para almacenar la clave. ## Escribir el bloque del agente El bloque `agent:` le indica al sandbox cómo lanzar Amp cuando el usuario se acopla. ```yaml {title="amp/spec.yaml"} schemaVersion: "1" kind: agent name: amp displayName: Amp description: The frontier coding agent. agent: image: "docker/sandbox-templates:shell-docker" aiFilename: AGENTS.md persistence: persistent entrypoint: run: [amp, --dangerously-allow-all] ``` - `aiFilename: AGENTS.md` le indica al sandbox que cree `AGENTS.md` al iniciarse y le añada el bloque [`memory`](#preparar-amp-con-memoria-memory) encima. Amp lee este archivo para obtener instrucciones. - `persistence: persistent` mantiene el estado de Amp (tokens de autenticación, historial) en un volumen con nombre a lo largo de los reinicios del sandbox. Sin esto, tendrías que volver a autenticarte cada vez. - `entrypoint.run` ejecuta `amp` en "modo YOLO" cuando se inicia el sandbox. Ajústalo si deseas pasar diferentes argumentos durante el inicio. ## Instalar Amp Amp se instala mediante un script de curl a bash: ```yaml commands: install: - command: "curl -fsSL https://ampcode.com/install.sh | bash" user: "1000" description: Install Amp ``` Ten en cuenta `user: "1000"`. Ese es el usuario del agente. Los comandos de instalación se ejecutan como root (UID 0) de forma predeterminada, y el instalador de Amp coloca el binario en el directorio de inicio del usuario. Ejecutarlo como root colocaría el binario en `/root/`, donde el agente no podría acceder a él. ## Permitir el acceso a la red El bloque de red hace dos cosas: enumera los hosts a los que el sandbox puede acceder (`allowedDomains`) y conecta la parte del flujo de autenticación del lado del kit descrita en [Planificar la autenticación](#planificar-la-autenticacion) mediante `serviceDomains` y `serviceAuth`. ```yaml network: serviceDomains: ampcode.com: amp serviceAuth: amp: headerName: Authorization valueFormat: "Bearer %s" allowedDomains: - "ampcode.com:443" - "*.ampcode.com:443" ``` `allowedDomains` cubre aquí el dominio principal (`ampcode.com`) y los subdominios de instalación/CDN (`*.ampcode.com`). Tómalo como un punto de partida; Amp puede comunicarse con otros dominios (proveedores de modelos, análisis, actualizaciones) que descubrirás observando `sbx policy log` durante las pruebas. Los kits también pueden declarar `deniedDomains` para hosts a los que el sandbox no debe acceder, como puntos de conexión de telemetría. Las reglas de denegación tienen prioridad sobre las reglas de permiso y se aplican únicamente a los sandboxes que utilizan el kit. Para la conexión de autenticación, cuando el agente realiza una solicitud saliente a `ampcode.com`, el proxy busca el host en `serviceDomains` para encontrar el ID del servicio `amp`, luego utiliza `serviceAuth.amp` para inyectar una cabecera `Authorization: Bearer `. El valor de `` proviene del secreto que registrarás en [Registrar tu clave de API](#registrar-tu-clave-de-api), coincidiendo por host. El ID del servicio (`amp`) es solo una etiqueta que vincula ambos bloques; puedes elegir cualquier nombre. > [!IMPORTANT] > Mantén `serviceDomains` lo más acotado posible. Mapear `*.ampcode.com` obligaría al proxy a entrar en modo de interceptación TLS para cada subdominio —incluido el CDN de binarios desde el que descarga el script de instalación— lo que dañaría dichas descargas. Enumera únicamente el host que realmente necesite autenticación. ## Preparar Amp con memoria (memory) El campo `memory` añade markdown a `AGENTS.md` durante la creación del sandbox. Utilízalo para informarle a Amp sobre el entorno del sandbox, de modo que conozca las convenciones al iniciarse. ```yaml memory: | ## Sandbox environment You are running inside a Docker sandbox. The workspace is mounted at its absolute host path. `sudo` is passwordless; use it for package installs. Docker is available inside the sandbox; containers you start are isolated in the microVM. ``` Mantén este fragmento corto y específico para el sandbox. Para instrucciones propias del proyecto, coloca un archivo `AGENTS.md` normal en el espacio de trabajo. ## La especificación completa Poniéndolo todo junto: ```yaml {title="amp/spec.yaml"} schemaVersion: "1" kind: agent name: amp displayName: Amp description: The frontier coding agent. agent: image: "docker/sandbox-templates:shell-docker" aiFilename: AGENTS.md persistence: persistent entrypoint: run: [amp, --dangerously-allow-all] network: serviceDomains: ampcode.com: amp serviceAuth: amp: headerName: Authorization valueFormat: "Bearer %s" allowedDomains: - "ampcode.com:443" - "*.ampcode.com:443" commands: install: - command: "curl -fsSL https://ampcode.com/install.sh | bash" user: "1000" description: Install Amp memory: | ## Sandbox environment You are running inside a Docker sandbox. The workspace is mounted at its absolute host path. `sudo` is passwordless; use it for package installs. ``` ## Registrar tu clave de API Registra tu clave de API de Amp en el host con `sbx secret set-custom`. El valor se guarda en el almacén de secretos del host y se expone un marcador de posición (placeholder) dentro de cada sandbox que lances con este kit. Amp valida el formato de `AMP_API_KEY` al iniciarse, por lo que el marcador de posición debe parecerse a una clave de Amp real. Elige una estructura de marcador de posición que coincida con el formato esperado por Amp: ```console $ sbx secret set-custom -g \ --host ampcode.com \ --env AMP_API_KEY \ --placeholder "sgamp-{rand}" \ --value "$AMP_API_KEY" ``` `{rand}` se expande a un sufijo aleatorio en el momento del registro. Dentro del sandbox, `AMP_API_KEY` se configura con ese marcador de posición; Amp lo acepta como una clave sintácticamente válida y el proxy sustituye el secreto real en las solicitudes salientes a `ampcode.com`. > [!TIP] > `sbx secret set-custom` solo es necesario porque Amp valida el formato de la clave. Si tu agente lee la variable de entorno sin realizar una comprobación de formato local, puedes declarar `environment.proxyManaged: [AMP_API_KEY]` en el kit en su lugar y omitir este paso del lado del usuario; el proxy utilizará un valor centinela por defecto (`proxy-managed`) que el agente nunca verá rechazado. > [!NOTE] > `sbx secret set-custom` es un comando experimental y no aparece en la salida de `sbx secret --help`. Funciona actualmente pero podría cambiar en futuras versiones. Este tutorial lo muestra porque no existe otro camino para registrar un marcador de posición con un formato personalizado. ## Ejecución Valida la especificación: ```console $ sbx kit validate ./amp/ ``` Lanza un sandbox con el kit, pasando el `name:` del kit (`amp`) como argumento del agente: ```console $ sbx run --kit ./amp/ amp ``` La copia publicada de este kit también se ejecuta directamente desde el repositorio contrib: ```console $ sbx run --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=amp" amp ``` ## Iteración A medida que utilices el kit, es probable que te encuentres con dominios omitidos o peculiaridades de la instalación. Dos ciclos de retroalimentación son útiles: - Supervisa el registro de políticas de red (`sbx policy log`) para detectar solicitudes bloqueadas, y luego añade sus dominios a `allowedDomains`. - Añade dominios a `deniedDomains` cuando desees que el agente permanezca bloqueado para un host, incluso si otra política lo permite. - Edita la especificación y vuelve a ejecutar `sbx run --kit ./amp/ amp` para aplicar los cambios. Elimina el sandbox primero (`sbx rm `) para un inicio limpio. Completa el bloque `memory` a medida que perfecciones el comportamiento que debe tener Amp en el sandbox. ## Publicación Una vez que el kit funcione, compártelo empaquetándolo como un archivo ZIP, subiéndolo a un registro OCI o confirmándolo en un repositorio Git. Consulta [Empaquetado y distribución](/ai/sandboxes/customize/build-an-agent/kits/#empaquetado-y-distribucion) para ver los subcomandos de `sbx kit`. ## Adaptar esto a otro agente La mayoría de los detalles descritos aquí son específicos de Amp. Para portar este patrón, toma las mismas decisiones para tu agente: - **Imagen base**: `shell-docker` si necesitas Docker dentro del sandbox, `shell` en caso contrario. O bien, amplía cualquiera de las dos con tu propia imagen si la instalación es muy pesada. - **Instalación**: un bloque `commands.install` en tiempo de ejecución, o integra el agente en una imagen personalizada. Elige la instalación si es un script de una sola línea; opta por integrarlo en la imagen si la instalación es lenta o necesitas una versión fija. - **Mapeo de red**: enumera solo el host de la API en `serviceDomains`, no un comodín. Mantén las rutas de instalación/CDN fuera del modo de interceptación TLS. Usa `deniedDomains` para hosts a los que el agente no deba acceder. - **Inyección de credenciales**: si el agente valida localmente el formato de la clave de API, regístrala con `sbx secret set-custom` y elige un marcador de posición coincidente. Si acepta la variable de entorno tal cual, declara `environment.proxyManaged` en el kit y omite el paso del lado del usuario. El resto (bloque de memoria, iteración de políticas de red, empaquetado) es el mismo independientemente del agente. ## Eliminar el secreto almacenado Para eliminar la entrada creada anteriormente con `sbx secret set-custom`, pasa el host a `sbx secret rm`: ```console $ sbx secret rm -g --host ampcode.com ``` La bandera `--host` en `sbx secret rm` no está listada en la ayuda de `sbx secret rm --help`, pero es la única manera de eliminar entradas creadas con `set-custom`. Al igual que el propio `set-custom`, es experimental y puede cambiar en el futuro.