Crie a partir do seu próprio pipeline CI/CD

Confira e arquive a origem do seu agente .

Confira o commit ou ramificação que você deseja criar e, em seguida, crie um arquivo tar.gz do seu diretório de agente . O Atlas Agent Engine compila exatamente o arquivo que você carrega, então esta etapa determina o que a compilação contém.

O exemplo seguinte utiliza o comando tar para criar um arquivo denominado agent.tar.gz. O exemplo exclui artefatos de desenvolvimento local do arquivo, incluindo os diretórios .venv, __pycache__ e .agentengine e o arquivo .env.

tar --exclude='.venv' --exclude='__pycache__' \
  --exclude='.agentengine' --exclude='.env' \
  -czf agent.tar.gz -C <agent-directory> .

Inicialize o arquivo de compilação.

Antes de executar os comandos a seguir, defina essas variáveis de ambiente em seu tarefa de CI/CD:

export PROJECT_ID="<project-id>"
export WORKSPACE_ID="<workspace-id>"
export GATEWAY_HOST="agentengine-qa.mongodb.com"
export API_KEY="$CI_API_KEY"
export COMMIT_SHA="<commit-sha>"

Use o ID do projeto para seu projeto do Mecanismo Atlas Agent. Use a ID do espaço de trabalho retornada por agentengine init. Defina GATEWAY_HOST como o host do seu ambiente, conforme listado na tabela acima. Armazene a chave de API no armazenamento secreto do seu sistema CI/CD e exponha-a como CI_API_KEY. Defina COMMIT_SHA como o commit que você passa em git_info.commit_sha.

Para criar um registro de compilação e obter uma URL pré-assinada para o upload de origem, envie uma solicitação POST para o endpoint builds/archive-init executando o seguinte comando curl:

curl -s -X POST \
  "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/builds/archive-init" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "label": "my-ci-build-123",
        "git_info": {
          "commit_sha": "<commit-sha>",
          "branch": "<branch-name>",
          "dirty": false
        },
        "build_target": { "subdirectory": "" },
        "auto_deploy": false
      }'

Todos os campos no corpo da solicitação são opcionais. Para tornar a compilação reproduzível, sempre passe a propriedadegit_info.commit_sha . Sem ele, o Atlas Agent Engine marca a imagem resultante build-<random-id> em vez de sha-<commit-sha>.

Para que uma compilação bem-sucedida se implemente e pule a etapa final, defina auto_deploy como true.

Se a solicitação for bem-sucedida, o endpoint retornará uma resposta 201 Created que se assemelhará à seguinte:

{
  "build_id": "bld_01ABC...",
  "upload_url": "https://<presigned-s3-url>",
  "upload_expires_at": "2026-01-01T00:05:00Z",
  "source_type": "archive"
}

Carregue a origem do agente .

Para carregar seu diretório de agente , envie uma solicitação PUT que inclua o arquivamento como um arquivo tar.gz para o valor upload_url retornado da etapa anterior executando o seguinte comando curl:

curl -s -X PUT \
  --upload-file agent.tar.gz \
  -H "Content-Type: application/gzip" \
  "$UPLOAD_URL"

Não envie um cabeçalho Authorization nesta solicitação. O URL assinado é a credencial e expira no momento fornecido pelo valor upload_expires_at retornado por archive-init. Se a URL de upload expirar antes de você usá-la, chame archive-init novamente para obter uma nova URL de upload.

Se o carregamento for bem-sucedido, o endpoint retornará uma resposta 200 OK.

Inicie a construção.

Para confirmar que o carregamento chegou e colocar o tarefa de construção na fila, envie uma solicitação POST sem corpo para o endpoint builds/<build-id>/start e salve a resposta executando o seguinte comando curl:

RESPONSE=$(curl -s -X POST \
  "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/builds/$BUILD_ID/start" \
  -H "Authorization: Bearer $API_KEY")
echo "$RESPONSE"

Se a solicitação for bem-sucedida, o endpoint retornará uma resposta 202 Accepted que se assemelhará à seguinte:

{ "build_id": "bld_01ABC...", "status": "accepted" }

Se uma compilação para o mesmo commit já estiver em execução, esse endpoint retornará um erro 409 BUILD_ALREADY_ACTIVE. O erro é uma proteção de construção duplicada em vez de uma falha transitória.

Quando disponível, a resposta inclui o ID e o status da compilação ativa no objetodetails :

{
  "success": false,
  "code": "BUILD_ALREADY_ACTIVE",
  "details": {
    "existing_build_id": "bld_01ABC...",
    "existing_status": "in_progress"
  }
}

Defina BUILD_ID para o valor details.existing_build_id e pesquise essa compilação em vez de inicializar outro arquivo de compilação:

BUILD_ID=$(printf '%s' "$RESPONSE" |
  jq -r '.details.existing_build_id // empty')

Se a resposta não incluir existing_build_id, liste as compilações do espaço de trabalho e selecione a compilação ativa para o mesmo commit:

BUILD_ID=$(curl -s \
  "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/builds?limit=100" \
  -H "Authorization: Bearer $API_KEY" |
  jq -r --arg commit "$COMMIT_SHA" '
    .builds[]
    | select(.commit_sha == $commit)
    | select(
        .status == "queued" or
        .status == "in_progress" or
        .status == "waiting"
      )
    | .build_id' |
  head -n 1)

Pesquise o status de construção.

Para aguardar a conclusão da compilação, pesquise o endpoint builds/<build-id> em um intervalo regular até que a compilação atinja um status de terminal. O exemplo a seguir pesquisa a cada cinco segundos e falha no pipeline após 30 minutos, para que uma compilação presa no estado queued ou waiting não possa manter seu tarefa de CI/CD em execução indefinidamente:

TIMEOUT_SECONDS=1800
INTERVAL_SECONDS=5
ELAPSED=0
while true; do
  STATUS=$(curl -s \
    "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/builds/$BUILD_ID" \
    -H "Authorization: Bearer $API_KEY" \
    | jq -r '.status')
  if [ "$STATUS" = "succeeded" ]; then
    break
  elif [ "$STATUS" = "failed" ] || [ "$STATUS" = "cancelled" ]; then
    echo "Build $BUILD_ID ended with status: $STATUS" >&2
    exit 1
  elif [ "$ELAPSED" -ge "$TIMEOUT_SECONDS" ]; then
    echo "Timed out after ${TIMEOUT_SECONDS}s waiting for build $BUILD_ID" >&2
    exit 1
  fi
  sleep "$INTERVAL_SECONDS"
  ELAPSED=$((ELAPSED + INTERVAL_SECONDS))
done

Quando a compilação atinge succeeded, o loop é encerrado e o pipeline continua para a próxima etapa. Quando atinge failed ou cancelled, ou quando o tempo limite termina, o exemplo é encerrado com um status diferente de zero, portanto o pipeline falha. Ajuste TIMEOUT_SECONDS e INTERVAL_SECONDS para corresponder à duração da compilação e à tolerância do sistema de CI/CD para chamadas de API.

Enquanto a compilação está em andamento, o endpoint retorna uma resposta semelhante à seguinte:

{
  "build_id": "bld_01ABC...",
  "status": "in_progress",
  "executor_type": "vm",
  "image_uri": null,
  "lockfile_mode": null,
  "error_message": null
}

A tabela seguinte descreve os valores status:

O campo lockfile_mode informa se o Atlas Agent Engine cumprou um arquivo de bloqueio confirmado. Para saber mais, consulte Gerenciar dependências.

Implemente a construção.

Para implantar a imagem produzida pela compilação, envie uma solicitação POST para o endpoint deployments executando o seguinte comando curl:

curl -s -X POST \
  "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/deployments" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "build_id": "'"$BUILD_ID"'" }'

O campo build_id é opcional. Se você omitir, o Atlas Agent Engine implementará a compilação bem-sucedida mais recente no espaço de trabalho.

Se a solicitação for bem-sucedida, o endpoint retornará uma resposta 202 Accepted que se assemelhará à seguinte:

{ "deployment_id": "deploy-abc123" }

A resposta confirma apenas que o Atlas Agent Engine aceitou a implementação. Para confirmar se o sistema está sendo executado corretamente, pesquise o endpoint deployments/current, conforme mostrado no exemplo a seguir:

curl -s \
  "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/deployments/current" \
  -H "Authorization: Bearer $API_KEY"

O endpoint retorna a implantação ativa do espaço de trabalho, incluindo seu status, a prontidão de cada componente que o sistema executa e a integridade geral do sistema. A seguinte resposta é reduzida para os campos que uma verificação com script precisa:

{
  "deployment_id": "deploy-abc123",
  "status": "successful",
  "components": [
    {
      "name": "agent",
      "available": true,
      "replicas": 1,
      "ready_replicas": 1
    }
  ],
  "health": {
    "available": true,
    "checked_at": "2026-01-01T00:10:00Z"
  }
}

Em uma implantação saudável, status é successful, cada entrada na array components tem available definido como true com ready_replicas igual a replicas e o campo health available do objeto é true.