Visão geral
Neste guia, você pode aprender como iniciar um ambiente de desenvolvimento local para seu agente do Atlas Agent Engine. O comando agentengine dev cria uma imagem do Docker que inclui o código do seu aplicação e inicia a pilha de agente completa, incluindo o orquestrador, a sandbox do agente , a sandbox da ferramenta e uma instância local do MongoDB , em seu computador. Quando o ambiente está em execução, a CLI imprime as URLs de serviço para que você possa desenvolver e testar seu agente.
Pré-requisitos
Antes de começar, certifique-se de instalar a CLI agentengine. Para saber mais sobre como instalar a CLI, autenticar e registrar o projeto, consulte Instalar e autenticar.
Definições de configuração opcionais
Esta seção descreve as configurações opcionais que você pode usar para definir seu ambiente de desenvolvimento local.
Habilitar memória
Se você definir features.memory: true no arquivo agent.yaml, adicione as seguintes variáveis ao arquivo .env antes de iniciar o ambiente local:
VOYAGE_API_KEY: necessário para gerar incorporações de memória.MONGOMEM_DB_NAME: Opcional. O nome do banco de dados MongoDB no qual o servidor de memória grava. O padrão émdb_memory_<project-id>.
Definir configurações de desenvolvimento local
Você pode usar um arquivo dev.yaml para substituir atribuições de porta de serviço local e ativar ou desativar a instância local do MongoDB durante o desenvolvimento. Coloque seu arquivo dev.yaml no mesmo diretório que seu arquivo agent.yaml. Este arquivo é opcional e a plataforma não o adiciona ao seu arquivo .gitignore, para que você possa confirmar e compartilhar as configurações.
A tabela seguinte descreve os campos que você pode incluir no arquivo dev.yaml:
Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| int (1 – 65535) | no | Substituição de porta para um serviço de plataforma. Nomes de serviço válidos são: |
| bool | no | Se iniciar uma instância MongoDB local como parte da pilha de desenvolvimento. O padrão é |
| int | no | A Porta MongoDB escuta quando executada localmente. O padrão é |
O exemplo a seguir mostra um arquivo dev.yaml que define todos os campos disponíveis:
services: playground: port: 3000 oe: port: 8000 aer: port: 8001 tool: port: 8002 mongodb: local: true port: 27017
Iniciar desenvolvimento local
O comando agentengine dev suporta dois modos de inicialização: modo de recarga a quente para desenvolvimento ativo e modo isolado para testar uma topologia semelhante à produção.
Modo de recarga a quente (recomendado)
O modo de recarga automática executa todos os serviços do agente dentro de um único container de aplicativo e monta seu código-fonte diretamente nele. Quando você edita um arquivo, owatchfiles detecta a alteração e recarrega automaticamente o serviço afetado sem exigir uma reconstrução completa.
(Opcional) Anexar código VS como contêiner de desenvolvimento.
Se você usar o código do Visual Studio (VS), execute as etapas a seguir para anexar diretamente ao contêiner em execução. Isso fornece uma experiência de desenvolvimento integrada com suporte completo a IntelliSense e depuração.
Instale a extensão Dev Containers no VS Code.
Enquanto a pilha estiver em execução, abra o Command Palette e selecione Dev Containers:/ Reopen in Container.
O VS Code se conecta ao container do aplicativo e recarrega o espaço de trabalho dentro dele.
Modo isolado
Você pode usar o sinalizador --isolated para iniciar o ambiente local no modo isolado. O modo isolado inicia cada serviço de agente em um container separado, espelhando a topologia de produção. Use este modo para validar o comportamento através dos limites de serviço ou para reproduzir problemas específicos da produção. Como o código não é montado no seu host, você deve reconstruir as imagens depois de fazer alterações no código.
Gerencie o ambiente local
Use os seguintes comandos do agentengine dev para gerenciar seu ambiente de execução.
Exibir registros
Para transmitir registros de todos os serviços em execução, execute o seguinte comando:
agentengine dev logs
Para transmitir registros de um serviço específico, passe o nome do serviço como um argumento posicional:
agentengine dev logs <service>
Em um monorepo, passe --all para transmitir registros para a pilha compartilhada de todos os espaços de trabalho:
agentengine dev logs --all
Verifique o status da pilha local
O comando agentengine dev status mostra o estado atual da pilha de composição local, incluindo o status por serviço e os URLs de host publicados. O exemplo a seguir mostra a sintaxe do comando:
agentengine dev status [--workspace <name>] [--all] [--json]
A tabela a seguir descreve os sinalizadores disponíveis:
bandeira | Descrição |
|---|---|
| (Somente Monorepo) Segmenta um agente específico por nome, conforme definido na raiz |
| (Somente Monorepo) Tem como alvo a pilha de todos os espaços de trabalho. |
| Imprime um objeto de status legível por máquina para stdout. Inclui |
Reiniciar serviços
O comando agentengine dev restart reinicia os contêineres de recarga a quente app e oe sem reconstruir a imagem. Use isso depois de alterar as dependências do host. O exemplo a seguir mostra a sintaxe do comando:
agentengine dev restart [--workspace <name>]
Este comando tem como alvo apenas a pilha de recarga instantânea. Não suporta --all ou modo isolado.
Adicionar novas dependências
Quando você adiciona uma dependência ao seu arquivo pyproject.toml, a pilha de desenvolvimento local pode não instalá-la se um arquivo uv.lock já existir. Quando um arquivo uv.lock está presente, o ponto de entrada de desenvolvimento sincroniza o ambiente com o sinalizador --frozen, que resolve as dependências do lockfile em vez do arquivo pyproject.toml.
Para instalar a nova dependência, execute os seguintes comandos para excluir o arquivo uv.lock e reiniciar a pilha:
rm uv.lock agentengine dev stop agentengine dev up
Como alternativa, você pode executar os seguintes comandos para atualizar o lockfile antes de reiniciar a pilha:
uv lock agentengine dev stop agentengine dev up
Usar repositórios de artefatos privados
Se o seu agente depender de pacotes hospedados em repositórios de artefatos privados, como um PyPI privado ou registro npm no AWS CodeArtifact, declare-os no bloco artifact_repositories do seu arquivo agent.yaml. No modo de carregamento automático, os comandos agentengine dev up e agentengine dev restart configuram automaticamente as credenciais de registro para entradas type: pypi. A CLI não configura automaticamente entradas npm. Para dependências privadas de npm, autentique-se por meio da configuração local do npm, como um arquivo .npmrc no nível do projeto.
Para cada repositório PyPI declarado, forneça uma credencial por meio de um dos seguintes:
Uma variável
UV_INDEX_<NAME>_PASSWORD(e, opcionalmente,_USERNAME) em seu ambiente de processo ou arquivo.env. Por exemplo, para um índice denominadocorps-pypi, configureUV_INDEX_CORPS_PYPI_PASSWORD.O campo
secretdeclarado, leia seu arquivo.env.Para um índice do AWS CodeArtifact, um token criado a partir do seu perfil ativo da AWS ou sessão SSO.
Se nenhuma credencial for resolvida para um repositório declarado, a CLI falhará e nomeará o repositório e as fontes a serem verificadas.
Para ignorar a configuração automática e gerenciar as variáveis UV_INDEX_* por conta própria, execute o seguinte comando:
agentengine dev up --no-artifact-auth
Observação
Se você declarar uma entrada type: pypi e iniciar no modo--isolated ou --all, a CLI retornará um erro em vez de iniciar contêineres que falham na instalação da dependência.
Para saber mais sobre o esquema artifact_repositories, consulte Esquema YAML do agente. Para saber como os repositórios de artefatos privados funcionam em compilações na nuvem, consulte Repositórios de artefatos privados.
Interromper serviços
Para pausar o ambiente local sem remover os containers, execute o seguinte comando:
agentengine dev stop [--workspace <name>] [--all]
O comando interrompe os containers sem removê-los. Execute agentengine dev up novamente para retomar os containers sem uma reconstrução.
Redefinir estado local
Para interromper todos os contêineres e remover todos os volumes associados e arquivos de tempo de execução gerados, execute o seguinte comando:
agentengine dev clean [--workspace <name>] [--all]
Aviso
A execução de agentengine dev clean exclui permanentemente todos os dados locais armazenados no volume MongoDB Atlas Local. Faça backup de todos os dados necessários antes de executar este comando.
Após a limpeza, execute agentengine dev up para gerar novamente arquivos e iniciar novos containers locais.
Autenticar servidores MCP remotos
Os comandos agentengine dev mcp auth gerenciam credenciais OAuth para servidores MCP remotos configurados em seu arquivo agent.yaml em mcp.servers. Os comandos gravam credenciais de login no cache de credenciais de dev em ~/.agentengine/mcp-oauth e as pilhas agentengine dev up geradas montam esse diretório automaticamente.
O cache é separado para cada projeto e cada endpoint MCP. Conectar de um projeto não conecta você para outro projeto, então você deve executar o comando agentengine dev mcp auth login uma vez por projeto. Para saber mais sobre os requisitos de nomenclatura dos servidores MCP, consulte Regras de nomenclatura do servidor.
login de autenticação
Use o comando agentengine dev mcp auth login para abrir o fluxo de autorização do provedor para um servidor e salvar as credenciais no cache de desenvolvimento, conforme mostrado no exemplo a seguir:
agentengine dev mcp auth login <server> [--no-browser]
O sinalizador --no-browser imprime a URL de login em vez de abrir a URL em um navegador.
A URL de autorização que o servidor anuncia deve usar o esquema https. Se o servidor anunciar um endpoint de autorização que usa qualquer outro esquema, o comando interromperá e gerará um erro Refused to open unauthorized MCP OAuth URL.
status de autenticação
Use o comando agentengine dev mcp auth status para verificar se existem credenciais em cache para um servidor, conforme mostrado no exemplo a seguir:
agentengine dev mcp auth status [server] [--check]
O sinalizador --check usa as credenciais em cache para se conectar ao servidor MCP e chama o endpoint da lista de ferramentas para confirmar que o servidor as aceita.
upload de autenticação
Use o comando agentengine dev mcp auth upload para base64-codificar o cache OAuth local para um servidor e armazená-lo como um segredo de espaço de trabalho denominado AGENTIC_MCP_OAUTH_B64_<SERVER>. Este comando expõe as credenciais de autorização aos agentes implementados.
O exemplo a seguir mostra a sintaxe do comando:
agentengine dev mcp auth upload <server> [--workspace-id <id>] [--sync]
O sinalizador --workspace-id especifica o ID do espaço de trabalho, e o sinalizador ''--sync'' recarrega segredos em sistemas ativos imediatamente após o upload.
Antes de fazer o upload, a CLI verifica se a URL do servidor registrada no cache corresponde à URL no seu arquivo agent.yaml. Se o cache foi registrado para um endpoint diferente, a CLI recusará o carregamento e solicitará que você execute o comando agentengine dev mcp auth login novamente.
Validar configuração
O comando agentengine agent validate liga seu arquivo agent.yaml localmente com o mesmo analisador e validador que o pipeline de construção usa. Execute-o antes de criar para detectar erros de digitação, valores inválidos e erros de política de rede.
O exemplo a seguir mostra a sintaxe do comando:
agentengine agent validate [path] [--strict]
O caminho padrão é ./agent.yaml. Passe um caminho explícito para validar um arquivo em um local diferente, como um espaço de trabalho de monorepo.
O comando retorna os seguintes códigos de saída:
Código de saída | Significado |
|---|---|
|
|
| Falha na validação. A saída identifica os campos inválidos. |
| Erro de arquivo ou E/S. Não foi possível ler o arquivo. |
O comando não requer autenticação e pode ser executado em CI sem um token válido.
Quando artifact_repositories não está vazio, o comando faz uma verificação cruzada dos nomes de índice declarados com as ferramentas do seu projeto no mesmo diretório de agent.yaml. Para agentes Python, lê pyproject.toml e uv.lock. Para agentes TypeScript, lê package.json, .npmrc e package-lock.json. URLs privados não declarados em lockfiles são permitidos, porque a injeção de credenciais é opcional. Os mesmos erros rígidos que bloqueiam compilações de nuvem param a validação e retornam código de saída 1.
Quando você está conectado, o comando também imprime avisos não bloqueantes para valores artifact_repositories[].secret ausentes ou com escopo definido incorretamente, incluindo WORKSPACE_CONTEXT_NEEDED quando uma entrada com escopo definido pelo espaço de trabalho é declarada sem um contexto agentengine init ativo. Passe --strict para tratar esses avisos como código de saída 1. Para saber como os repositórios de artefatos privados funcionam em compilações na nuvem, consulte Repositórios de artefatos privados.
Observação
O comando agentengine agent validate é experimental. Seus sinalizadores, formato de saída e códigos de saída podem mudar à medida que o validador se expande para cobrir mais campos agent.yaml.
Próximos passos
Depois que seu ambiente local estiver em execução, você poderá testar o agente e iterar em seu código. Para saber como testar manualmente o agente e aplicar alterações de código, consulte Testar o agente.