Visão geral
Neste guia, você pode aprender a gerenciar suas organizações, projetos e espaços de trabalho do MongoDB Atlas Agent Engine. Este guia descreve os seguintes comandos de gerenciamento:
Agentngine organização: lista e visualiza organizações.
Agentngine projeto: liste e visualize projetos.
agentengine workspace: Crie e gerencie espaços de trabalho para um agente implementado.
agentengine service-account: crie e gerencie contas de serviço para seu projeto ou organização.
versão do agente: Gerencie a versão da CLI.
Pré-requisitos
Antes de começar, certifique-se de instalar e autenticar o agentengine CLI. Para saber mais, consulte o guia Instalar e autenticar.
Ver organizações
As organizações são o agrupamento de nível superior para suas equipes e recursos no MongoDB Atlas Agent Engine. A CLI agentengine pode listar e visualizar organizações, mas não pode alterá-las. Para alterar uma organização apoiada pelo Atlas, use o MongoDB Atlas:
Para criar, atualizar ou excluir uma organização, consulte o guia Gerenciar Organizações.
Se sua organização não for baseada no MongoDB Atlas, use a interface do usuário do Atlas Agent Engine para alterar sua organização.
Listar todas as organizações
Para listar todas as organizações às quais sua conta pertence, execute o seguinte comando:
agentengine organization list
Obter detalhes da organização
Para recuperar detalhes de uma organização específica, execute o seguinte comando. Substitua <org-id> pelo ID da organização:
agentengine organization get <org-id>
Visualizar projetos
Os projetos existem dentro de uma organização e agrupam os recursos para um agente ou equipe específica. O agentengine CLI pode listar e visualizar projetos, mas não pode alterá-los. Para alterar um projeto apoiado pelo Atlas, use MongoDB Atlas:
Para adicionar, atualizar ou remover usuários do projeto , consulte o guia Gerenciar acesso a um projeto.
Se o seu projeto não for apoiado MongoDB Atlas, use a interface do usuário do Atlas Agent Engine para alterar seu projeto.
Listar todos os projetos
Para listar todos os projetos na sua organização, execute o seguinte comando:
agentengine project list [--org-id <org-id>]
Você pode usar o sinalizador --org-id para especificar o ID da organização. Por padrão, a CLI lê esse valor do seu estado de autenticação armazenado localmente.
Obter detalhes do projeto
Para recuperar detalhes de um projeto específico, execute o seguinte comando. Substitua <project-id> pelo ID do projeto:
agentengine project get <project-id>
Gerenciar espaços de trabalho
Um espaço de trabalho é o ambiente de tempo de execução de um agente implementado em um projeto. Use os seguintes comandos para criar e gerenciar espaços de trabalho. Os exemplos nesta seção usam o espaço reservado <workspace-id>. Substitua este espaço reservado pelo ID do seu espaço de trabalho.
Listar todos os espaços de trabalho
Para listar todos os espaços de trabalho no seu projeto, execute o seguinte comando:
agentengine workspace list [--project-id <id>] [--org-id <id>] [--base-url <url>] [--json]
A tabela a seguir descreve os sinalizadores disponíveis:
bandeira | Descrição |
|---|---|
| Padrão de ID do projeto: usa o projeto do estado de autenticação armazenado localmente. |
| ID da organização para roteamento de várias organizações |
| URL base da API da plataforma |
| Gera JSON bruto em vez de uma tabela legível por humanos |
Obter detalhes do espaço de trabalho
Para recuperar detalhes de um espaço de trabalho específico, execute o comando agentengine workspace get:
agentengine workspace get <workspace-id> [--project-id <id>] [--org-id <id>] [--base-url <url>] [--json]
A tabela a seguir descreve os sinalizadores disponíveis:
bandeira | Descrição |
|---|---|
| Padrão do ID do projeto: valor retirado do estado de autenticação armazenado localmente. |
| ID da organização para roteamento de várias organizações |
| URL base da API da plataforma |
| Saída de JSON bruto em vez de pares de valores-chave legíveis por humanos |
Criar um espaço de trabalho
O comando agentengine workspace create cria um novo espaço de trabalho na plataforma. Execute este comando a partir de um diretório de agente que contenha um arquivo agent.yaml que inclui os campos name e entrypoint.
O comando lê automaticamente description, framework, features e agent_card de agent.yaml e detecta automaticamente campos GitOps do repositório git local, se presente. Use os sinalizadores --description e --framework para substituir valores de agent.yaml.
Se já existir um espaço de trabalho para o projeto, o comando imprime o ID do espaço de trabalho existente e sai com sucesso.
agentengine workspace create [--description <desc>] [--framework <fw>] [--project-id <id>] [--org-id <id>] [--base-url <url>] [--json]
A tabela a seguir descreve os sinalizadores disponíveis:
bandeira | Descrição |
|---|---|
| Descrição do espaço de trabalho. Substitui o valor de |
| Framework do agente (por exemplo, |
| Padrão do ID do projeto: valor retirado do estado de autenticação armazenado localmente. |
| ID da organização para roteamento de várias organizações |
| URL base da API da plataforma |
| JSON de saída com campos |
Atualizar um espaço de trabalho
O comando agentengine workspace update atualiza parcialmente um espaço de trabalho existente. Somente os sinalizadores explicitamente fornecidos são incluídos na solicitação de atualização.
agentengine workspace update <workspace-id> [flags]
A tabela a seguir descreve os sinalizadores disponíveis:
bandeira | Descrição |
|---|---|
| Nome de exibição do espaço de trabalho |
| Descrição do espaço de trabalho |
| Framework do agente |
| Nome do modelo LLM |
| Ferramentas habilitadas (separadas por vírgula) |
| Ativar ou desativar grades de proteção ( |
| Ativar ou desativar memória ( |
| Texto de resumo do cartão do agente |
| Recursos do cartão do agente (separados por vírgula) |
| Provedor de GitOps |
| URL do repositório GitOps |
| Ramo do GitOps |
| Caminho do manifesto do GitOps |
| Referência de conexão do GitOps |
| Padrão do ID do projeto: valor retirado do estado de autenticação armazenado localmente. |
| ID da organização para roteamento de várias organizações |
| URL base da API da plataforma |
Gerencie espaços de trabalho usando a API
Os comandos do espaço de trabalho chamam a API do Mecanismo do Agente do Atlas . Para gerenciar espaços de trabalho programaticamente, chame esses endpoints diretamente.
Cada endpoint do espaço de trabalho tem como escopo um único projeto. Se você estiver chamando endpoints em mais de um projeto, inclua o ID do projeto na solicitação.
A tabela a seguir descreve os endpoints disponíveis. Substitua {project-id} pelo ID do projeto e {workspace-id} pelo ID do seu workspace:
Endpoint | Descrição |
|---|---|
| Lista os espaços de trabalho no projeto. |
| Cria um espaço de trabalho no projeto. |
| Retorna os detalhes de um único workspace. |
| Atualiza os campos incluídos no corpo da solicitação. |
| Exclui o workspace. |
Gerenciar contas de serviço
Uma conta de serviço é uma identidade programática que pertence a um projeto ou uma organização em vez de uma pessoa. Use os seguintes comandos para criar, listar, girar e excluir contas de serviço.
Para recuperar o token de acesso da sua conta de serviço, passe seu ID do cliente e segredo em uma solicitação de POST para o endpoint /api/v1/oauth/token. Para saber mais,consulte Invocar um agente.
Os exemplos nesta seção usam os seguintes espaços reservados:
<name>: o nome da conta de serviço.<role>: o role a ser concedido à conta de serviço. Para uma conta de projeto , utilizePROJECT_OWNERouPROJECT_READ_ONLY. Para uma conta de organização , utilizeORG_GROUP_CREATORouORG_READ_ONLY.<client-id>: o ID do cliente da conta de serviço.
Criar uma Conta de Serviço
Para criar uma nova conta de serviço, execute o seguinte comando:
agentengine service-account create <name> --role <role> [--org-id <id> | --project-id <id>] [--description <text>] [--secret-expires-in <duration>] [--ip-access-list <ip-or-cidr>,...] [--json]
O comando gera o segredo do cliente em texto simples e os detalhes da conta de serviço, conforme mostrado no exemplo a seguir:
Client Secret: agp_sa_sk_... Client ID: agp_sa_id_... Name: ci-pipeline ...
Importante
Salve o segredo do cliente quando ele for exibido. É mostrado apenas uma vez.
A tabela a seguir descreve os sinalizadores disponíveis:
bandeira | Descrição |
|---|---|
| Obrigatório. Role concedido à conta de serviço. |
| ID da organização para uma conta com escopo organizacional. |
| ID do projeto para uma conta com escopo de projeto. |
| Descrição legível por humanos. |
| Vida útil do segredo em horas, como |
| Endereços IP ou blocos CIDR permitidos para utilizar a credencial. |
| Gera a conta de serviço criada, o segredo único do cliente e o contexto resolvido como JSON. Os avisos não aparecem em stdout. |
Listar contas de serviço
Para listar todas as contas de serviço do projeto ou organização atual, execute o seguinte comando:
agentengine service-account list [--org-id <id>] [--project-id <id>] [--limit <n>]
O comando exibe uma tabela com ID do cliente , nome, funções, status ativo, expiração do segredo, data da última utilização do segredo e descrição para cada conta de serviço.
Por padrão, o comando lista contas de serviço para o projeto em seu estado de autenticação armazenado localmente. Use o sinalizador --org-id ou --project-id para listar contas de serviço de uma organização ou projeto diferente.
Girar um segredo de conta de serviço
Para emitir um novo segredo do cliente para uma conta de serviço, execute o seguinte comando:
agentengine service-account rotate <client-id> [--org-id <id>] [--project-id <id>] [--secret-expires-in <duration>]
O comando produz o novo segredo do cliente de texto simples. O segredo anterior permanece válido por até sete dias ou até sua própria expiração, o que ocorrer primeiro.
Dica
Para revogar imediatamente o segredo anterior, gire o segredo uma segunda vez ou exclua a conta de serviço.
Excluir uma conta de serviço
Para excluir permanentemente uma conta de serviço, execute o seguinte comando:
agentengine service-account delete <client-id> [--org-id <id>] [--project-id <id>]
Depois de excluir uma conta de serviço, ela não poderá mais solicitar tokens de acesso, e qualquer token que ela já contenha falhará no próximo uso.
Gerenciar versões CLI
Esta seção descreve os comandos que você pode usar para recuperar e atualizar sua versão da CLI.
Verifique a versão do CLI
O comando agentengine version imprime a versão da CLI, o commit git do qual o binário foi compilado e as marcações de imagem de container padrão usadas pela pilha de desenvolvimento local.
Para recuperar a versão CLI, execute o seguinte comando:
agentengine version [--json]
Dica
Por padrão, este comando imprime uma string de texto sem formatação legível por humanos. Passe o sinalizador --json para imprimir um objeto JSON estável e legível por máquina que inclua os campos schema_version, status, version, git_commit, build e images incorporados.
A saída se assemelha ao seguinte:
0.1.94-alpha (commit: <hash>) image registry: ECR runner-base: <registry>/runner-base:0.1.94-alpha runner-base-typescript-langgraph: <registry>/runner-base-typescript-langgraph:0.1.94-alpha playground-ui: <registry>/playground-ui:0.1.94-alpha orchestrator: <registry>/orchestration-engine:<version> memory-server: <registry>/memory-server:<version>
Atualizar a CLI
O comando agentengine self-update faz o download do ativo de versão correspondente mais recente para seu sistema operacional e arquitetura atuais, verifica a checksum SHA-256 desse ativo e substitui o binário existente em seu caminho de instalação atual.
Quando você está conectado ao Atlas Agent Engine, a CLI recupera a lista de versões disponíveis do API Gateway da plataforma.
Observação
O comando agentengine self-update baixa o novo binário no diretório que contém seu binário atual, então você deve ter acesso de escrita a esse diretório. Se você não tiver acesso de gravação, prefixe o comando com sudo ou reinstale a CLI em um diretório diferente.
Para atualizar a CLI, execute o seguinte comando:
agentengine self-update [--force] [--auto[=true|false]]
A tabela a seguir descreve os sinalizadores disponíveis:
bandeira | Descrição |
|---|---|
| Baixe e instale a versão mais recente, mesmo que a CLI atual já esteja atualizada. |
| Ative as atualizações automáticas antes que a maioria dos comandos seja executada. Passe o sinalizador |
Quando você executa a maioria dos comandos agentengine, a CLI imprime um aviso de uma linha para stderr se uma versão mais recente estiver disponível. A CLI executa a verificação de atualização uma vez a cada 24 horas. Para desabilitar totalmente a verificação, defina a variável de ambiente AGENTENGINE_NO_UPDATE_CHECK=1 em seu shell.
Observação
No Windows, o comando agentengine self-update baixa o binário atualizado para substituição manual porque um agentengine.exe em execução não pode ser substituído no local.
Limites de recursos
Cada organização pode ter até 100 contas de serviço da organização . Se você exceder esse limite, a solicitação retornará um erro 400 Bad Request com uma mensagem RESOURCE_LIMIT_EXCEEDED.
A tabela a seguir lista os limites de recursos para cada projeto:
Resource | Limite |
|---|---|
Espaços de trabalho | 25 |
Chaves de API | 100 |
Fornecedores de credenciais | 100 |
Contas de serviço do projeto | 100 |
Se você exceder um limite de recurso, a solicitação retornará um erro 400 Bad Request com uma mensagem de RESOURCE_LIMIT_EXCEEDED.
Para revisar todas as limitações que se aplicam durante a visualização pública, consulte Limitações do mecanismo do agente do MongoDB Atlas .
Próximos passos
Depois de configurar suas organizações, projetos e espaços de trabalho, você pode criar e executar seu agente localmente. Para saber como, consulte Construir seu ambiente local.