Crear un proyecto

Sintaxis del comando

Utilice el siguiente comando para generar la estructura básica de un nuevo proyecto:

agentengine create [--template <template-id>] [--name <display-name>] [--dir <path>] [--llm <provider>] [--llm-base-url <url>] [--llm-model <model>] [--llm-auth-header <header>] [--memory] [--yes]

Dependiendo de las opciones que especifique, la interfaz de línea de comandos le pedirá que configure su proyecto.

Este comando crea un directorio de proyecto que contiene un archivo project-config.yaml y genera la estructura del directorio de espacio de trabajo de su agente en un subdirectorio <project-directory>/agents/<slug>. El valor <slug> es una versión en minúsculas y con guiones del valor --name. El directorio de espacio de trabajo contiene agent.yaml, .env y los demás archivos específicos del agente que se describen en secciones posteriores.

Banderas de comando

Restricciones del nombre para mostrar

La interfaz de línea de comandos (CLI) copia el nombre para mostrar en los archivos fuente generados. El nombre no puede contener los siguientes caracteres:

• Comillas dobles (")

• Barras invertidas (\)

• acentos graves

• Caracteres de control, salto de línea o dirección de texto

Si introduce un nombre no válido al usar la interfaz de línea de comandos interactiva, esta mostrará un error y le pedirá que lo introduzca de nuevo. Si pasa un nombre no válido al indicador --name, el comando fallará con un error que indicará el carácter o la categoría de caracteres no permitidos.

Plantillas compatibles

La siguiente tabla describe las plantillas de inicio que puede pasar al comando agentengine create:

Configuración predeterminada del entorno local

Al seleccionar una conexión LLM del catálogo de proveedores, agentengine create le solicita los detalles de conexión necesarios, como una clave API. Si LLM_API_KEY está configurado en su entorno de shell, el comando lo ofrece como valor predeterminado. Al confirmar el valor, el comando lo escribe en el archivo .env generado como LLM_API_KEY. No es necesario configurar este valor manualmente.

Cuando la memoria está habilitada, agentengine create detecta VOYAGE_API_KEY de su entorno local y lo ofrece como valor predeterminado. Al confirmar el valor, este se escribe en el .env generado.

Al ejecutar agentengine create con la bandera --yes, el comando no solicita valores de entorno detectados. Para todas las opciones del catálogo de proveedores, excepto custom, debe configurar LLM_API_KEY en su entorno antes de ejecutar el comando. Si también pasa --memory --yes, debe configurar VOYAGE_API_KEY en su entorno antes de ejecutar el comando; de lo contrario, el comando fallará.

La plantilla chatbot-client genera un archivo .env.local en lugar de un archivo .env. Antes de ejecutar la aplicación, debe completar manualmente el archivo .env.local con los siguientes valores:

• URL de la API de su agente implementado

• ID detu proyecto

• ID detu espacio de trabajo

• Token de acceso a su cuenta de servicio

Personaliza tu agente andamiado

Una vez que agentengine create se complete, navegue hasta el directorio del espacio de trabajo de su agente en <project-directory>/agents/<slug> y revise los archivos generados.

Todos los agentes generados incluyen la habilidad atlas-agent-engine en .agents/skills/atlas-agent-engine (para Codex, Copilot y otros agentes) o .claude/skills/atlas-agent-engine (para Claude Code).

Al usar una plantilla de agente inicial, revise el código fuente del agente generado y el archivo .env para confirmar que la conexión LLM cumple con sus requisitos. El cliente LLM, el modelo, el punto final y el comportamiento de autenticación se configuran en el código fuente del agente generado.

Para las opciones de catálogo que configuran una conexión LLM, el archivo .env generado contiene la credencial compartida como LLM_API_KEY. Si elige Manual setup, configure la conexión LLM en el código de su agente y agregue los secretos que dicho código requiera al archivo .env. Para obtener más información, consulte Configurar una puerta de enlace LLM en el código.

Al usar la plantilla chatbot-client, revise el archivo .env.local y confirme que ha configurado correctamente la URL de la API, el ID del proyecto, el ID del espacio de trabajo y el token de acceso a la cuenta de servicio de su agente implementado. No existe un archivo agent.yaml en la aplicación cliente del chatbot.

Configurar una puerta de enlace LLM a partir de una plantilla de inicio

Cuando ejecuta el comando agentengine create, el comando le solicita que elija una conexión LLM, similar al siguiente ejemplo:

Which LLM connection do you want to use?
  1) OpenAI
  2) Anthropic
  3) Google Gemini
  4) OpenRouter
  5) OpenAI-compatible - AWS Bedrock, Azure Foundry
  6) Anthropic-compatible - AWS Bedrock, Azure Foundry
  7) Manual setup - implement the LLM client in code

Si elige un proveedor de este catálogo, el comando agentengine create le pedirá los detalles necesarios para la conexión, que podrían incluir lo siguiente:

• URL base

• Nombre del modelo o de la implementación

• Clave de API

• Encabezado de autenticación para conexiones cuando el host no es reconocido.

El comando escribe el cliente LLM seleccionado en la fuente del agente generado y almacena la credencial compartida en el archivo .env generado como LLM_API_KEY.

El comando también le solicita que elija cómo el Agente y la Herramienta acceden a los hosts externos:

• Aplique la configuración network.egress recomendada. Si no hay ningún host de puerta de enlace disponible, como cuando elige Manual setup (custom), esta opción le indica que configure la salida LLM más adelante.

• Permitir todo el acceso saliente.

Si su conexión LLM no aparece entre las opciones listadas, seleccione Manual setup y configure la puerta de enlace mediante código. Esta opción crea un modelo auxiliar para que pueda configurar la conexión en el código de su agente.

Configurar una puerta de enlace LLM en código

Para conectar un LLM a tu agente, crea un modelo específico del framework y pasa la instancia del modelo resultante al método app.llm(...) desde el punto de entrada de tu agente. Puedes colocar el código de creación del modelo en cualquier archivo del código de tu agente, pero las plantillas de inicio colocan un fragmento de código en un archivo específico del lenguaje. Si no utilizas una plantilla de inicio, puedes definir el modelo en otro lugar, siempre que app.llm(...) reciba un objeto de modelo compatible.

La siguiente tabla describe las convenciones para configurar una puerta de enlace LLM en el código en diferentes entornos de ejecución:

El constructor es el que establece el punto final, los encabezados de autenticación y el nombre del modelo. Por ejemplo, la plantilla LangGraph Python insurance-agent define build_llm() en src/<module>/llm.py y devuelve un LangChain BaseChatModel. El punto de entrada del agente importa build_llm() y pasa el modelo devuelto a app.llm(...).

Permita el host de la puerta de enlace para que su agente pueda acceder a él. Agregue el host y el puerto de la puerta de enlace personalizados al bloque network.egress en el archivo agent.yaml. Por ejemplo, para agregar gateway.example.com:443 a la lista de permisos de salida existente del entorno aislado de la herramienta, ejecute el siguiente comando:

agentengine agent egress add --component tool gateway.example.com:443

Para obtener más información sobre cómo configurar la salida de red para su agente, consulte la guía "Primeros pasos con la salida de red".

Sintaxis del comando

Desde el directorio del espacio de trabajo de su agente, ejecute el siguiente comando para registrar el agente y generar archivos locales:

agentengine init [--workspace-id <id>] [--project-id <id>] [--org-id <id>] [--base-url <url>] [--context <name>]

Este comando selecciona o crea interactivamente una organización y un proyecto, genera archivos de desarrollo locales y registra su agente como un espacio de trabajo en el motor de agentes de Atlas.

Banderas de comando

Flujo interactivo

Cuando ejecutas agentengine init, la interfaz de línea de comandos te guía a través de los siguientes pasos:

1. Muestra una lista de tus organizaciones con un menú numerado, que incluye la opción "Create a new organization...". Si no existen organizaciones, la interfaz de línea de comandos te pide que introduzcas un nombre para crear una.

2. Una vez que seleccione una organización, verá una lista de sus proyectos en un menú numerado, que incluye la opción "Create a new project...". Si no existen proyectos, la interfaz de línea de comandos le pedirá que ingrese un nombre para crear uno.

3. Guarda el proyecto seleccionado como su project_id activo en el estado de autenticación local.

4. Genera los siguientes archivos de desarrollo locales en el directorio de tu agente:

   • docker-compose.yml

   • .agentengine/Dockerfile

   • .agentengine/entrypoint.py

   • .dockerignore

   • .gitignore

5. Registra el agente como un espacio de trabajo en la plataforma y crea el archivo .agentengine/state.json con los parámetros workspace_id, org_id y project_id especificados.

Plantillas de inicio para agentes

Si utiliza una plantilla de TypeScript, instale las dependencias de Node.js antes de iniciar su agente localmente:

pnpm install

Después de revisar su agente con estructura básica, ejecute agentengine dev up para iniciar su agente localmente:

agentengine dev up

Plantilla de cliente de chatbot

Después de configurar los valores necesarios en el archivo .env.local, instale las dependencias e inicie el servidor de desarrollo:

pnpm install
pnpm run dev

Abre http://localhost:3000 en tu navegador para usar la interfaz de chat.