Compartir comentarios
Las respuestas se generan en base a la documentación.

Construye tu propio kit de agente

Tabla de contenidos
Disponibilidad: Acceso anticipado
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.

Este tutorial describe el proceso de construcción de un kit de agente para el agente de codificación Amp. 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. Este tutorial se centra en el proceso.

El kit terminado también está publicado como un ejemplo ejecutable en docker/sbx-kits-contrib, 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: 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.

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 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:

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 mediante serviceDomains y serviceAuth.

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 <clave>. El valor de <clave> proviene del secreto que registrarás en 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.

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:

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:

$ 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:

$ sbx kit validate ./amp/

Lanza un sandbox con el kit, pasando el name: del kit (amp) como argumento del agente:

$ sbx run --kit ./amp/ amp

La copia publicada de este kit también se ejecuta directamente desde el repositorio contrib:

$ 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 <nombre-sandbox>) 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 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:

$ 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.