Fonte de artefato personalizada (`AGENTENGINE_IMAGE_SOURCE=custom`)

A fonte custom roteia o baixar de binários CLI e as extrações de imagens de pilha de desenvolvimento por meio de sua própria infraestrutura hospedada, em vez de Github Releases e GHCR do MongoDB. Ele é projetado para ambientes de rede isolados (fisicamente isolados, com saída restrita) onde ghcr.io ou github.com está inacessível.

Como funciona

Dois botões independentes, cada um opcional:

Bloco	Controles	Comandos afetados
`release`	Hospedar de baixar do binário da CLI	`agentengine self-update`, aviso de atualizar uma vez por dia
`registry`	Hospedar imagem de dev (5 imagens)	`agentengine dev up`

A origem personalizada substitui apenas o hospedar — os nomes e as tags dos repositórios de imagens permanecem fixos ao criar, para que seu espelho possa copiar mecanicamente: mesmos nomes, mesmas tags, seu hospedar.

As cinco imagens da pilha de desenvolvimento são: playground-ui, orchestration-engine, memory-server, runner-base, runner-base-typescript-langgraph.

Pré-requisitos

AGENTENGINE_IMAGE_SOURCE=custom em seu ambiente
source.yaml em ~/.agentengine/source.yaml (ou em um caminho definido em $AGENTENGINE_IMAGE_SOURCE_FILE)
Sua CA corporativa deve estar no armazenar de confiança do SO — não há flag --insecure (consulte Segurança)

Observação

Os nomes das variáveis de substituição são fixos. A CLI lê AGENTENGINE_IMAGE_SOURCE e AGENTENGINE_IMAGE_SOURCE_FILE. Os nomes AP_SOURCE / AP_SOURCE_FILE desativados não são mais lidos, e definir qualquer um deles faz com que o comando falhe.

Não é necessária conectividade com a plataforma. A CLI resolve a origem localmente, portanto, uma máquina com air-gap ou com restrição de saída se configura apenas com AGENTENGINE_IMAGE_SOURCE=custom. Consulte public-artifacts.

Passo 1 — Obter nomes e tags de imagem

Executar agentengine version --full para obter os nomes exatos da imagem e a tag para a criar atual da CLI:

agentengine version --full

Saída de exemplo:

1.4.2 (commit: abc1234)runner-base: ghcr.io/mongodb/agent-engine-client-libraries/runner-base:v1.4.2runner-base-typescript-langgraph: ghcr.io/mongodb/agent-engine-client-libraries/runner-base-typescript-langgraph:v1.4.2playground-ui: ghcr.io/mongodb/agent-engine-client-libraries/playground-ui:v1.4.2orchestrator: ghcr.io/mongodb/agent-engine-client-libraries/orchestration-engine:v1.4.2memory-server: ghcr.io/mongodb/agent-engine-client-libraries/memory-server:v1.4.2

Use estes nomes e tags exatos ao espelhar. Eles são estáveis em lançamentos de patch dentro de uma versão principal; apenas o sufixo da versão muda.

Etapa 2 — Espelhar imagens (se estiver espelhando a pilha de desenvolvimento)

docker login ghcr.io                           # read access to MongoDB's GHCRdocker login artifactory.example.com           # write access to your registry
for img in playground-ui orchestration-engine memory-server runner-base runner-base-typescript-langgraph; do  docker pull ghcr.io/mongodb/agent-engine-client-libraries/$img:v1.4.2  docker tag  ghcr.io/mongodb/agent-engine-client-libraries/$img:v1.4.2 artifactory.example.com/acme-docker/$img:v1.4.2  docker push artifactory.example.com/acme-docker/$img:v1.4.2done

Repita para cada nova versão da CLI. Os nomes do repositório e o formato da tag são estáveis; apenas o número da versão muda.

Passo 3 — Hospedar o binário da CLI (se estiver espelhando o baixar de binários)

Se a sua rede também bloquear os lançamentos do Github, hospede os binários da CLI em um servidor HTTPS (um repositório genérico do Artifactory funciona bem) e publique um manifest.json correspondente ao formato de manifesto estático.

Faça o upload dos arquivos binários para cada combinação de SO/arquitetura e, em seguida, crie o manifesto apontando para eles. A URL do manifesto torna-se release.url em source.yaml.

Etapa 4 — gravar `source.yaml`

Coloque em ~/.agentengine/source.yaml ou no caminho que você definiu em $AGENTENGINE_IMAGE_SOURCE_FILE.

Recomendado: gere-o com a CLI

agentengine agent source setup      # interactive wizard: asks base/release/registry, validates before writingagentengine agent source template   # writes a commented, ready-to-edit starting point insteadagentengine agent source template --stdout   # print the template instead of writing it

Ambos gravam no caminho de descoberta padrão (ou --force para ignorar o prompt de substituição em um arquivo existente) e se autovalidam antes de gravar, para que o resultado tenha garantias de carregamento. Use agentengine agent source setup quando responder aos prompts for mais fácil do que editar YAML manualmente; use agentengine agent source template quando preferir editar o arquivo você mesmo — os exemplo abaixo mostram o que preencher.

Espelhamento completo — binários e imagens do seu hospedar

base: publicrelease:  type: static  url: https://artifactory.example.com/acme-generic/agentic-cli/manifest.jsonregistry:  prefix: artifactory.example.com/acme-docker

Apenas imagens — o binário permanece no Github

Use quando sua rede permite github.com, mas bloqueia ghcr.io:

base: publicregistry:  prefix: artifactory.example.com/acme-docker

Apenas binário — as imagens permanecem no GHCR

Use quando sua rede permite ghcr.io, mas bloqueia baixar versões do Github:

base: publicrelease:  type: static  url: https://nexus.example.com/agentic-cli/manifest.json

API de lançamento no estilo GitHub — GitHub Enterprise local

Use quando sua infraestrutura expõe uma API de lançamentos com o formato JSON do Github (por exemplo, Github Enterprise) em vez de hospedar um manifesto estático:

base: publicrelease:  type: github  url: https://ghe.example.internal/api/v3/repos/acme/agentic-cli/releasesregistry:  prefix: registry.example.internal/agentic

Espelhando o lançamento público

Para implantações que espelham os artefatos de lançamento público:

base: publicrelease:  type: static  url: https://artifactory.example.com/agentic-cli/manifest.jsonregistry:  prefix: artifactory.example.com/agent-engine-mirror

base: public herda o que quer que public resolva atualmente. Isso se aplica apenas a blocos que você não substitui: um registry.prefix ou release.url fixado é seu. Fixe o bloco para ter certeza dele. Veja public-artifacts.md.

`source.yaml` referência de campo

Campo	Obrigatório	Descrição
`base`	No (default: `public`)	Fonte de fallback para qualquer coisa que não tenha sido substituída: `public`
`release.type`	Sim, se `release` estiver presente	`static` — manifesto JSON estático (este documento); `github` — API de lançamentos no formato GitHub
`release.url`	Sim, se `release` estiver presente	URL HTTPS completa do manifesto (estático) ou base da API (Github). Deve usar `https://`
`registry.prefix`	Sim, se `registry` estiver presente	Hospedar do registro + caminho, sem esquema, sem tag (por exemplo, `artifactory.example.com/acme-docker`)

Pelo menos um de release ou registry é necessário — um source.yaml sem nenhum dos dois é equivalente à fonte base e é rejeitado.

$AGENTENGINE_IMAGE_SOURCE_FILE substitui o caminho de descoberta ~/.agentengine/source.yaml. Quando definido, um arquivo ausente ou ilegível é um erro grave em vez de um fallback silencioso para o arquivo inicial.

Passo 5 — Verificar

agentengine agent source validate verifica o arquivo sem exigir que $AGENTENGINE_IMAGE_SOURCE seja definido primeiro e, em caso de sucesso, imprime as variáveis de ambiente exatas para ativá-lo:

agentengine agent source validate                          # standard discovery pathagentengine agent source validate ./some/other/source.yaml  # or an explicit path

AGENTENGINE_IMAGE_SOURCE=customAGENTENGINE_IMAGE_SOURCE_FILE=/Users/you/.agentengine/source.yaml

As falhas de validação exibem as mesmas mensagens fixadas listadas em Solução de problemas abaixo, independentemente de o arquivo ter vindo de agentengine agent source setup, agentengine agent source template ou de edição manual.

Em seguida, ative-o e confirme o roteamento resolvido:

export AGENTENGINE_IMAGE_SOURCE=customagentengine version --full

Para um espelhamento completo, você deverá ver:

1.4.2 (commit: abc1234)source: custom  release:  https://artifactory.example.com/acme-generic/agentic-cli/manifest.json (static)  registry: artifactory.example.com/acme-dockerrunner-base: artifactory.example.com/acme-docker/runner-base:v1.4.2runner-base-typescript-langgraph: artifactory.example.com/acme-docker/runner-base-typescript-langgraph:v1.4.2playground-ui: artifactory.example.com/acme-docker/playground-ui:v1.4.2orchestrator: artifactory.example.com/acme-docker/orchestration-engine:v1.4.2memory-server: artifactory.example.com/acme-docker/memory-server:v1.4.2

As imagens na saída são as strings exatas passadas para docker pull por agentengine dev up.

Em seguida, execute agentengine self-update para testar o caminho para atualizar binários e agentengine dev up para confirmar se os pulls de imagem foram bem-sucedidos.

Formato de manifesto de lançamento estático

A CLI busca este arquivo em release.url, escolhe a versão semver mais alta e seleciona o ativo correspondente ao sistema operacional e à arquitetura atuais. Não existe um campo latest — a CLI calcula a versão máxima a partir do array releases, portanto, um ponteiro desatualizado nunca pode discordar dos ativos disponíveis.

{  "releases": [    {      "version": "1.4.2",      "assets": [        {          "os": "darwin",          "arch": "arm64",          "url": "https://artifactory.example.com/acme-generic/agentic-cli/1.4.2/agentic_darwin_arm64",          "sha256": "9f2b...e1"        },        {          "os": "linux",          "arch": "amd64",          "url": "https://artifactory.example.com/acme-generic/agentic-cli/1.4.2/agentic_linux_amd64",          "sha256": "4c7a...bd"        }      ]    }  ]}

Campo	Tipo	Descrição
`releases`	array	Uma entrada por versão. A CLI seleciona o semver mais alto.
`releases[].version`	string	Versão semântica (por exemplo, `1.4.2`)
`releases[].assets`	array	Uma entrada por combinação de SO/arquitetura
`assets[].os`	string	`darwin`, `linux` ou `windows`
`assets[].arch`	string	`amd64` ou `arm64`
`assets[].url`	string	URL HTTPS completa para o binário
`assets[].sha256`	string	Resumo SHA-256 hexadecimal de 64caracteres do binário

A CLI valida se sha256 é uma string hexadecimal de 64caracteres no momento da análise e verifica novamente o binário baixado antes da instalação.

Segurança

HTTPS é obrigatório, sem substituição ``--insecure``. O SHA-256 verifica se o binário corresponde ao manifesto, mas nada assina criptograficamente o próprio manifesto. Por HTTP simples, um invasor pode reescrever a URL de baixar e o hash juntos e a verificação ainda será aprovada. O TLS é a única garantia de integridade do manifesto. Os servidor de lançamento no local devem usar TLS.

CA corporativa. Empresas com air-gap normalmente executam uma autoridade de certificação interna. A CLI usa a pilha TLS do Go, que segue o armazenamento de confiança de certificados do SO. Sua CA corporativa deve ser instalada no armazenamento de confiança do SO antes de usar AGENTENGINE_IMAGE_SOURCE=custom com um host HTTPS interno. Não há flag --insecure ou --cacert. Uma falha de verificação TLS em um host interno é um problema de armazenamento de confiança, não um bug da CLI.

As instalações de pacotes dentro da imagem local-dev gerada são um armazenar de confiança separado. Consulte Inspeção de TLS corporativo no agentengine dev up local.

Autenticação de registro. A CLI nunca armazena ou gerencia credenciais do Docker. Se o seu registro exigir autenticação, execute docker login <registry> uma vez antes de executar agentengine dev up. A CLI passa referências de imagem para o Docker, que usa seu próprio armazenar de credenciais ambiente.

Descoberta de ``source.yaml``. A CLI carrega source.yaml apenas de $AGENTENGINE_IMAGE_SOURCE_FILE (quando definido) ou ~/.agentengine/source.yaml. Ele nunca carrega automaticamente do diretório de trabalho atual — fazer isso permitiria que um repositório clonado redirecionasse o autoatualizar para um hospedar controlado por um invasor.

Solução de problemas

Erro	Causa	Corrigir
`AGENTENGINE_IMAGE_SOURCE=custom but no source.yaml found`	Nenhum arquivo em nenhum dos caminhos pesquisados	Crie `~/.agentengine/source.yaml` ou defina `$AGENTENGINE_IMAGE_SOURCE_FILE`
`$AGENTENGINE_IMAGE_SOURCE_FILE points to "..." which does not exist`	`$AGENTENGINE_IMAGE_SOURCE_FILE` definido, mas o arquivo está ausente	Verifique o caminho; o arquivo deve existir quando a variável de ambiente estiver definida
`source.yaml: release.url must be an https:// URL`	A URL começa com `http://`	Use `https://`; adicione TLS ao seu servidor
`source.yaml: registry.prefix "..." must not include a scheme`	O prefixo possui `https://`	Remova o esquema; use bare `host/path`
`source.yaml: registry.prefix "..." must not contain a tag or digest`	O prefixo inclui o sufixo `:v1`	Use apenas hospedar + caminho (sem dois pontos após o último `/`)
`source.yaml: custom source needs at least one of 'release' or 'registry'`	Nenhum dos blocos está presente	Adicione pelo menos um bloco
`release manifest: HTTP 404 fetching ...`	URL incorreta ou arquivo ainda não carregado	Verifique `release.url` e confirme se o arquivo está acessível
`release manifest: no asset for darwin/arm64 in version 1.4.2`	Entrada de SO/arquitetura ausente	Adicione a entrada de ativo ausente ao seu manifesto
`release manifest: asset sha256 "xyz" is not a 64-char hex digest`	Resumo muito curto ou não hexadecimal	Calcule o `sha256sum` do binário e cole o hex de 64caracteres completo
Falha na verificação de TLS no hospedar interno	CA corporativa não está no armazenamento de confiança do SO	Instale sua CA; não existe uma flag `--insecure`
O pull de imagem falhou no `agentengine dev up`	Imagem não espelhada ou `docker login` ausente	Espelhar a imagem; executar `docker login <registry>` primeiro

Voltar

tls-corporativo

variáveis de ambiente

Fonte de artefato personalizada (AGENTENGINE_IMAGE_SOURCE=custom)