Visão geral
Neste guia, você pode aprender como construir a imagem do agente a partir da CLI. O processo de construção carrega o código-fonte do agente para o armazenamento na nuvem e inicia um tarefa de construção remota que produz uma imagem do Docker.
Sintaxe e opções de comando do build
Use a seguinte sintaxe para criar a imagem do agente :
agentengine build [--label <str>] [--no-wait] [--context <name>] [--workspace <name>] [--all] [--json] [--upload-build-secrets]
Este comando empacota a origem do agente como um arquivo tar.gz, faz o upload para um bucket do Simple Storage Service (S3) por meio de um URL assinado e, em seguida, inicia um tarefa do AWS CodeBuild para produzir uma imagem do Docker no Elastic Container Registry ( ECR).
Sinalizadores de comando
Ao criar a imagem do agente , você pode usar as seguintes sinalizações opcionais:
bandeira | Descrição |
|---|---|
| O rótulo de construção. Por padrão, esse valor é lido do seu repositório git local no formato |
| Instrui a CLI a retornar imediatamente após iniciar o tarefa de construção sem pesquisar o status de construção. |
| O contexto local nomeado do arquivo |
| (Somente Monorepo) Constrói um espaço de trabalho específico por nome, conforme definido na raiz |
| (Somente Monorepo) Constrói todos os espaços de trabalho sequencialmente. A CLI cria o arquivo de origem uma vez, depois executa as etapas de upload e construção para cada espaço de trabalho. Depois que todas as compilações são iniciadas, ele pesquisa cada compilação até atingir um status de terminal. Este sinalizador é mutuamente exclusivo com |
| Produz um único resultado de construção legível por máquina. |
| Carrega cada |
Arquivar conteúdo
Antes de carregar a origem do agente , a CLI cria o arquivo tar.gz referenciado na seção anterior. Esta seção descreve qual diretório o arquivo empacota e quais arquivos ele exclui.
Raiz do arquivo
Por padrão, o comando agentengine build empacota somente o diretório de agente . Os pacotes de comando da raiz do espaço de trabalho ou do monorepo se o arquivo de configuração do espaço de trabalho ou do monorepo listar o diretório do agente como membro. O requisito de listagem depende do tipo de espaço de trabalho, conforme descrito na tabela a seguir:
Tipo de espaço de trabalho | Requisito de associação |
|---|---|
espaço de trabalho uv | O diretório do agente deve corresponder a um padrão |
Monorepo | O diretório do agente deve aparecer exatamente como está escrito na lista |
Para localizar a raiz do workspace ou do monorepo, a CLI pesquisa para cima, nos diretórios pai do diretório do agente , um arquivo que marque uma raiz. A pesquisa para no diretório raiz do repositório git e nunca continua no seu diretório inicial, portanto, o comando não pode pacote arquivos de fora do repositório.
Se o diretório do agente for um submódulo git ou uma árvore de trabalho vinculada, a pesquisa não terminará nesse limite. A pesquisa continua no repositório pai, e as regras de associação descritas na tabela anterior determinam de qual diretório os pacotes de comando.
Arquivos excluídos
Um arquivo .agentengineignore em nível de projeto na raiz do arquivo controla quais arquivos a CLI empacota no arquivo. Esse arquivo usa sintaxe.gitignore padrão , incluindo globs, ** e negação !. O comando agentengine init cria o arquivo com os seguintes padrões padrão:
.git.venv*__pycache__.pytest_cache.mypy_cache.ruff_cachenode_modulesdistbuild.agentengine*.pyc.env.env.*.DS_Store*.pem*.key
Se o arquivo estiver ausente, a CLI usará os mesmos padrões padrão do comando agentengine init.
Os seguintes arquivos são sempre excluídos, e você não pode usar uma negação ! no arquivo .agentengineignore para substituir isso:
.enve arquivos.env.**.peme arquivos*.keyChaves privadas OpenSSH comuns:
id_rsa,id_dsa,id_ecdsa,id_ed25519eid_ed448.gitDiretórioArmazenamentos de credenciais de nuvem e ferramentas:
.aws,.kube,.ssh,.netrc,.git-credentials,.azure,.config/gh,.docker/config.jsone.config/gcloud
Um arquivo .npmrc de nível de projeto não faz parte deste conjunto de arquivos excluídos. A construção da plataforma lê o arquivo .npmrc do arquivo para resolver os registros npm privados declarados. A compilação também lê pyproject.toml para resolver registros PyPI privados declarados. Para saber como configurar credenciais de registro privadas para a compilação, consulte Repositórios de artefatos privados.
Aviso
Como a compilação inclui seus arquivos .npmrc e pyproject.toml, não armazene tokens de registro ou credenciais nesses arquivos. Em vez disso, declare credenciais em artifact_repositories em seu arquivo agent.yaml. Para saber mais,consulte Repositórios de artefatos privados.
Repositórios de artefatos privados
Se o seu agente depender de pacotes hospedados em repositórios privados de artefatos, como o AWS CodeArtifact, declare esses repositórios no bloco artifact_repositories do seu arquivo agent.yaml. O Atlas Agent Engine resolve as credenciais de registro no momento da construção do segredo do Atlas Agent Engine nomeado em cada entrada e as injeta no ambiente de construção. As credenciais não são armazenadas em seus arquivos de origem e não estão expostas a pods em execução. Se você não declarar nenhum repositório, o Atlas Agent Engine resolverá as dependências de registros públicos usando sua configuração de ferramentas existente, inalterada.
Os URLs de registro residem nas ferramentas do seu projeto , não no agent.yaml. Para agentes Python, declare cada índice privado em uma entrada [[tool.uv.index]] em pyproject.toml. O campo name em agent.yaml deve corresponder ao nome do índice. Para agentes TypeScript, declare cada registro de escopo privado em um arquivo .npmrc. Defina npm_scope em agent.yaml para o escopo mapeado para o registro. Os exemplos a seguir mostram o arquivo de ferramentas correspondente e a entrada agent.yaml para cada idioma:
[[tool.uv.index]] name = "corps-pypi" url = "https://<domain>-<account>.d.codeartifact.<region>.amazonaws.com/pypi/<repo>/simple/" explicit = true
artifact_repositories: - name: corps-pypi type: pypi secret: ARTIFACT_REPO_CORPS_PYPI_TOKEN username: aws scope: project
@acme:registry=https://npm.pkg.github.com/
artifact_repositories: - name: corp-npm type: npm secret: ARTIFACT_REPO_CORP_NPM_TOKEN npm_scope: "@acme" scope: project
Para saber mais sobre o esquema artifact_repositories completo, consulte Esquema YAML do agente.
Antes do início da construção, o Atlas Agent Engine valida os repositórios declarados em relação às ferramentas do seu projeto . Se a validação falhar, a compilação interromperá com um erro aplicável. Para detectar problemas antes de construir, execute agentengine agent validate localmente. Para saber mais, consulte Validar Configuração.
Cada artifact_repositories[].secret declarado deve existir no escopo declarado em seus segredos do Atlas Agent Engine antes do início da compilação. Para tokens de registro de curta duração que expiram entre compilações, use o sinalizador --upload-build-secrets para carregar cada segredo de uma variável de ambiente com o mesmo nome. O exemplo a seguir gera um token AWS CodeArtifact e o carrega em um comando de compilação:
export ARTIFACT_REPO_CORPS_PYPI_TOKEN="$(aws codeartifact get-authorization-token \ --domain my-domain --query authorizationToken --output text)" agentengine build --upload-build-secrets
Para credenciais de longa duração, defina cada segredo uma vez com agentengine secret set e compile sem o sinalizador. Para saber mais sobre o provisionamento de segredos, consulte Provisionar segredos de nuvem.
Construir comandos de gerenciamento
A tabela a seguir descreve os comandos de gerenciamento de compilação que você pode usar para monitorar e gerenciar as compilações do agente :
Comando | Descrição |
|---|---|
| Registros de construção de fluxos para |
| Lista todas as compilações para o espaço de trabalho em um formato de tabela. A tabela inclui ID de compilação, status, rótulo e tempo de criação. |
| Cancela uma compilação especificada em execução ou em fila. Este comando retorna um erro se a compilação já tiver sido bem-sucedida ou falhar. |
| Promove uma imagem de construção bem-sucedida em outro espaço de trabalho sem reconstruir a imagem a partir da origem. Para saber mais, consulte Promover uma compilação. |
| Retorna o status de uma promoção de construção especificada. A saída inclui o ID de compilação de destino e o motivo da falha, se a promoção tiver falhado. |
Dica
Sinalizadores de comando
Cada comando de gerenciamento de compilação aceita os sinalizadores --workspace-id e --project-id para especificar o espaço de trabalho e o projeto. Se não forem fornecidos, a CLI lê esses valores do arquivo .agentengine/state.json.
Promover uma compilação
Quando você promover uma compilação, o Mecanismo do Agente Atlas copia uma imagem de compilação testada de um espaço de trabalho para outro espaço de trabalho sem reconstruir a imagem da origem. Como a imagem promovido é byteidêntica à imagem de origem, o agente que é executado no workspace de destino é o mesmo que você testou no workspace de origem.
Observação
A página de detalhes da compilação da interface do usuário da plataforma não mostra uma seção Build Logs para uma compilação promovido, porque uma promoção reutiliza uma imagem existente em vez de executar uma nova compilação.
Por padrão, a compilação de origem deve ter pelo menos uma implantação bem-sucedida, o que confirma que a imagem é implantável. Para ignorar este requisito, use o sinalizador --force.
Use a seguinte sintaxe para promover uma compilação:
agentengine build promote <source_build_id> [--workspace <name>] [--workspace-id <id>] [--project-id <id>] [--context <name>] [--force] [--yes] [--json]
A CLI identifica a compilação de origem por ID e a resolve dentro da sua organização atual . Você não pode promover uma compilação para um projeto em uma organização diferente.
Ao promover uma compilação, você pode usar as seguintes sinalizações:
bandeira | Descrição |
|---|---|
| (Somente Monorepo) O nome do espaço de trabalho de destino, conforme definido no arquivo raiz |
| A ID do espaço de trabalho da plataforma de destino. |
| O ID do projeto da plataforma de destino . |
| O contexto local nomeado do arquivo |
| Ignora o requisito de implementação bem-sucedida. Este sinalizador requer a função |
| Ignora o prompt de confirmação interativo. Use esse sinalizador ao executar o comando em um pipeline de CI ou em outro ambiente não interativo. Sem ele, o comando falha fora de um terminal interativo. |
| Gera o resultado da promoção como JSON. |
Aviso
A promoção não copia o tempo de execução ou a configuração do projeto do espaço de trabalho de origem. Segredos, configuração de conexão do Atlas e políticas de saída não são transferidos para o workspace de destino. Antes de implementar a compilação promovido, defina estas configurações no projeto e no espaço de trabalho de destino.
Após o sucesso da promoção, implemente a compilação promovido no espaço de trabalho de destino. Para saber como implantar uma compilação, consulte Implementar sua compilação.
Exemplo
O comando a seguir cria a imagem do agente sem pesquisar o status da compilação e, em seguida, lista as informações da compilação:
agentengine build --no-wait && agentengine build list
Se a compilação for bem-sucedida, a saída do comando será semelhante ao exemplo a seguir:
Initialising build... build_id: <build_id> Creating archive... Uploading archive... Starting build... ✓ Build started (build_id: ...) URL: https://agentengine.mongodb.com/api/v1/workspaces/<workspace_id>/builds/<build_id> BUILD_ID STATUS LABEL CREATED_AT <build_id> running main@abc123def456 2026-04-01T10:30:00Z
Próximos passos
Depois de criar a imagem do agente , você pode implementar o agente na produção. Para saber como distribuir o agente, consulte o guia Distribua sua compilação.