Construa agentes com modelos de MongoDB Agent

Modelos disponíveis

O repositório de agentes MongoDB inclui os seguintes modelos:

Pré-requisitos

Antes de usar os modelos de MongoDB Agent , você precisa dos seguintes pré-requisitos:

• Node.js 24 ou posterior.

• pnpm.

• Atlas CLI 1.58 ou posterior.

• A CLI agentengine. Para saber como instalar a CLI, consulte Instalar e Autenticar na documentação do Mecanismo do Agente do MongoDB Atlas .

• Um projeto do MongoDB Atlas que contém os dados que você deseja que o agente examine.

• Uma chave de API para o seu fornecedor de grandes modelos de linguagem (LLM). Por padrão, os modelos usam OpenAI.

Configurar Credenciais e Acesso

Os modelos de MongoDB Agent se conectam ao seu projeto do MongoDB Atlas por meio de uma configuração do MongoDB MCP no nível do projeto. Para configurar o acesso, use as seguintes etapas:

1. Crie uma configuração de MCP em nível de projeto no MongoDB Atlas com a Atlas CLI.

   1. Execute o comando a seguir para criar uma configuração do MCP em nível de projeto. Use a opção --groupId para especificar o ID do projeto e a opção --file para especificar o caminho para o arquivo de solicitação.

      atlas api remoteMcpConfigurations createGroupMcpConfig --groupId <your-group-id> --file <your-request-file-path>

   2. Atribua as roles do MongoDB Atlas com menos privilégios que o agente precisa, como GROUP_DATA_ACCESS_READ_ONLY.

   3. No arquivo de configuração MCP, adicione seu endereço IP público local e os endereços IP do MongoDB Atlas Agent Engine. Os dois endereços 34.196.57.85 e 54.227.181.25 são os endereços IP do Atlas Agent Engine. Substitua YOUR_LOCAL_PUBLIC_IP pelo seu próprio endereço e mantenha os dois endereços do Atlas Agent Engine para que os agentes implementados possam se conectar. O exemplo a seguir mostra um exemplo de arquivo de solicitação:

      {
        "mcpConfigName": "{template-name-environment}",
        "roles": [
          "GROUP_DATA_ACCESS_READ_ONLY"
        ],
        "ipAccessList": [
          {
            "ipAddress": "YOUR_LOCAL_PUBLIC_IP"
          },
          {
            "ipAddress": "34.196.57.85"
          },
          {
            "ipAddress": "54.227.181.25"
          }
        ]
      }

2. Crie um segredo do cliente para a configuração do MCP. O segredo herda os roles da configuração.

   1. Execute o comando a seguir para criar um segredo do cliente . Use a opção --groupId para especificar a ID do projeto, a opção --mcpConfigId para especificar a ID da configuração do MCP e a opção --file para especificar o caminho para o arquivo de metadados secretos.

      atlas api remoteMcpConfigurations createGroupMcpSecret --groupId <your-group-id> --mcpConfigId <your-mcp-id> --file <your-metadata-file-path>

   2. No arquivo de metadados, defina o tempo de expiração secreto. O exemplo a seguir mostra um arquivo de metadados secreto que expira após 8760 horas (um ano):

      {
        "secretExpiresAfterHours": 8760
      }

   3. Copie e salve o segredo do cliente imediatamente. O comando retorna o segredo do cliente apenas uma vez.

3. Armazene o ID do cliente , o segredo do cliente e a chave de API do provedor de LLM.

   1. Para desenvolvimento local, armazene-os em um arquivo .env. Para um agente implementado, armazene-o no armazenamento secreto do Atlas Agent Engine com o comando agentengine secret set.

Crie uma configuração e um segredo de MCP separados para cada ambiente, como desenvolvimento local, preparação e produção. Não compartilhe credenciais entre ambientes.

Todos que usam o agente compartilham o mesmo acesso ao MongoDB Atlas , porque o segredo do cliente herda as funções da configuração do MCP. Portanto, conceda apenas ao MongoDB Atlas as funções que todo usuário do agente precisa.

Para os comandos completos e arquivos de configuração de cada modelo, consulte o README dos Modelos do MongoDB Agent. Para saber mais sobre como armazenar segredos no Atlas Agent Engine,consulte Provisionar segredos na documentação do MongoDB Atlas Agent Engine.

Executar e distribuir um modelo

Depois de configurar as credenciais de um agente, execute o modelo localmente para testá-lo e, em seguida, implemente-o no MongoDB Atlas Agent Engine.

agentengine dev up

agentengine deploy --auto

Segurança e dados

A lista a seguir contém considerações de segurança e dados para os modelos de MongoDB Agent :

• Somente leitura por padrão. O MongoDB Atlas Explorer grava no MongoDB Atlas somente se você conceder funções de gravação de configuração MCP e definir a variável de ambiente ALLOW_WRITE_OPERATIONS como true. Cada escrita faz uma pausa para aprovação humana. A query do MongoDB Atlas não pode ser gravada no MongoDB Atlas.

• Rastreamentos e conversas incluem seus dados. O MongoDB Atlas Agent Engine armazena cada rastreamento e conversa em seu projeto. Rastreamentos e conversas podem incluir banco de dados, coleção e nomes de campo , e documentos que o agente lê. Somente pessoas com acesso ao seu projeto podem vê-las. Você é responsável por controlar seus dados. Para saber mais, consulte Inspecionar rastreamentos na documentação do MongoDB Atlas Agent Engine.

• Seu fornecedor de LLM vê solicitações e resultados de ferramentas. Isso inclui os resultados da query que o agente lê. Escolha um fornecedor de LLM cujas políticas de tratamento de dados atendam à política de dados da sua organização.

• Sem acesso à shell. Os agentes não podem executar comandos de shell em seu sandbox.

• Você hospeda qualquer bot Slack. O bot Slack é um exemplo, não um serviço gerenciado. Você mesmo hospeda, protege e mantém.

Limitações

Os modelos de MongoDB Agent têm as seguintes limitações:

• Os modelos exigem o MongoDB Atlas. Eles não oferecem suporte ao Enterprise Advanced, sistemas locais ou MongoDB Atlas for Government.

• Os fluxos de trabalho de implantação oficiais oferecem suporte apenas ao MongoDB Atlas Agent Engine. Tempo de execução auto-hospedados não são suportados.

• Os agentes não acompanham as alterações em seu ambiente do MongoDB Atlas ao longo do tempo.

• Cada configuração de MCP tem um limite de capacidade por hora. Uma conta de serviço do MongoDB Atlas pode ter um máximo de 100 tokens de acesso ativo, e cada token dura uma hora. Cada espaço de trabalho e cliente que usa a mesma configuração do MCP compartilha esse limite. O MongoDB Atlas Agent Engine cria dois tokens sempre que uma conversa começa ou é retomada após o tempo limite ocioso. As mensagens de acompanhamento dentro dessa janela reutilizam os processos da sessão e não criam tokens. Isso permite de 40 a 50 conversas novas ou retomadas por hora. Quando o agente atinge o limite de token, as novas conversas falham até que os tokens mais antigos expirem, o que leva até uma hora. Para obter detalhes, consulte os limites de token de acesso no repositório de agentes MongoDB .

Cada modelo também tem limitações individuais que esta lista não abrange. Para obter as informações de limitação mais atualizadas, consulte o repositório de agentes do MongoDB .

Saiba mais

Para saber mais sobre os agentes que trabalham com MongoDB, consulte os seguintes recursos:

• Repositório de MongoDB Agents

• Habilidades do MongoDB Agent

• Documentação do servidor MongoDB MCP

• Documentação do Mecanismo do Agente do MongoDB Atlas