Referência do contrato do agente

Visão geral

Neste guia, você aprenderá os requisitos mínimos para executar um agente no MongoDB Atlas Agent Engine. Este guia aborda os arquivos que o Atlas Agent Engine precisa para descobrir e executar seu agente, o esquema agent.yaml e estruturas compatíveis e fornecedores de LLM.

Os agentes não implementam seu próprio endpoint HTTP. O Atlas Agent Engine importa o agente dentro do mesmo processo da sandbox do agente .

Agente implementável mínimo

Um agente implementável mínimo consiste em dois arquivos:

my_agent/main.py: define o objeto App e o gráfico.
agent.yaml: aponta para o objeto App definido em my_agent/main.py.

O exemplo a seguir mostra um arquivo main.py mínimo que define um objeto App chamado my-agent e cria um grafo de agente :

my_agent/main.py

from agent_engine_sdk_langgraph import App
from langgraph.graph import StateGraph, MessagesState
from langgraph.prebuilt import ToolNode
from langchain_openai import ChatOpenAI
app = App(app_name="my-agent")
@app.tool()
def lookup(query: str) -> str:
    """Search the knowledge base."""
    return f"result for {query}"
@app.entrypoint
def build_agent():
    llm = app.llm(ChatOpenAI(model="gpt-4o-mini"))
    tools = app.get_tools()
    def call_model(state: MessagesState):
        return {"messages": [llm.invoke(state["messages"])]}
    graph = StateGraph(MessagesState)
    graph.add_node("agent", call_model)
    graph.add_node("tools", ToolNode(tools))
    graph.set_entry_point("agent")
    graph.add_edge("tools", "agent")
    return graph.compile(checkpointer=app.checkpointer())
app.run()

O exemplo a seguir mostra um arquivo agent.yaml mínimo:

agent.yaml

entrypoint: my_agent.main:app

No arquivo main.py, você deve executar os seguintes componentes:

Defina um objeto App no nível do módulo, geralmente chamado app.
Registre um ponto de entrada no aplicativo com a função @app.entrypoint.
Registre ferramentas com a função @app.tool(...).
Ligue para a função app.run() na parte inferior do módulo.

No arquivo agent.yaml, você deve definir a chave entrypoint YAML para o objeto App usando o formato <module.path>:<attribute>.

Direções do agente

Siga estas diretrizes para garantir que seu agente funcione corretamente com os recursos da plataforma, como registro de auditar , aplicação de políticas e suspensão ou retomada de execuções do agente :

Ferramenta de roteamento e chamadas LLM por meio das funções app.tool(...) e app.llm(...).

O Atlas Agent Engine usa esses wrappers para registro de auditar , aplicação de políticas e ferramentas de repetição e chamadas LLM quando você retoma uma execução suspensa. As chamadas feitas fora desses wrappers não são auditadas pelo Atlas Agent Engine e não são repetidas corretamente depois de retomar a execução.
Mantenha o estado do gráfico JSON/BSON serializável.

As sandboxes do Agent são efêmeras, portanto, o Atlas Agent Engine salva os estados de checkpoint no MongoDB entre as ações de suspensão e retomada. Cada valor em seu estado de gráfico deve ser serializável para JSON ou BSON para que o checkpoint seja bem-sucedido, como subclasses primitivas, listas, dices, datetime, Enum e LangChain BaseMessage. Não armazene lambdas, fechamentos, identificadores de arquivo, conexões de banco de dados ou classes personalizadas em seu estado de gráfico sem suporte de serialização .
Chamar o app.llm(...) funcione somente enquanto seu ponto de entrada estiver na pilha de chamadas.

Quando você chama app.llm(...) do código de nível superior do módulo, do corpo de uma ferramenta ou de qualquer outra função que seu ponto de entrada não invoque, o Atlas Agent Engine gera um erro que identifica o arquivo e a linha com a chamada inválida. Para saber mais, consulte Ciclo de vida de execução.

Ciclo de vida de execução

O Mecanismo de Agente do Atlas carrega e executa seu código de agente em pontos definidos no ciclo de vida dos seguintes processos:

Agent Sandbox, que executa seu código de agente e constrói seu gráfico.
Sandbox de ferramentas, que executa corpos de ferramentas remotas em um processo separado da sandbox do agente .

Observação

Esse ciclo de vida de execução é o mesmo nos SDKs Python e TypeScript.

Esta seção descreve quando partes individuais do código do agente são executadas em cada processo e usa os seguintes termos:

O código de nível superior do módulo é o código nos arquivos-fonte do seu agente que é executado no momento da importação, fora de qualquer corpo de função.
O ponto de entrada é a função que você decore com @app.entrypoint.
Uma ferramenta local é executada apenas dentro do próprio processo da sandbox do agente . Por padrão, cada ferramenta que você registra com o gravador @app.tool() é uma ferramenta local.
Uma ferramenta remota é uma ferramenta que você atribui à caixa de proteção de ferramentas listando-a no campo sandboxes.tool.tools de seu arquivo agent.yaml. A sandbox do agente interpreta ferramentas remotas, mas os corpos de ferramentas remotas são executados na sandbox de ferramentas.

Inicialização

Nos processos de sandbox do agente e de sandbox de ferramentas, o Atlas Agent Engine executa as seguintes ações na inicialização:

Carrega os arquivos de origem do seu agente.
Executa o código de nível superior do módulo.

A plataforma não executa as seguintes ações na inicialização:

Execute seu ponto de entrada.
Execute seus corpos de ferramenta. O Atlas Agent Engine interpreta as definições de ferramentas para registrar suas assinaturas, mas não as executa.

O código de nível superior do módulo pode acessar segredos de todo o processo,como MONGODB_URI, e as credenciais do MCP OAuth, porque esses valores estão disponíveis durante a vida útil do processo. O Atlas Agent Engine também define os segredos que você declara para uma sandbox, incluindo chaves de API LLM, quando a sandbox é iniciada. Como resultado, o código de nível superior do módulo em uma sandbox pode acessar os segredos dessa sandbox.

Invocação da sandbox do agente

Na sandbox do agente , o Mecanismo do Agente do Atlas executa as seguintes ações durante uma invocação:

Executa seu ponto de entrada uma vez.
Executa corpos de ferramenta locais no processo da própria sandbox do agente .

A plataforma não executa as seguintes ações durante uma invocação de sandbox de agente :

Execute corpos de ferramentas remotas. A sandbox do agente as interpreta e, em seguida, despacha a chamada para a sandbox da ferramenta.

Invocação de Sandbox da Ferramenta

Na sandbox de ferramentas, o Atlas Agent Engine executa as seguintes ações durante uma invocação:

Carrega seu ponto de entrada lentamente, exatamente uma vez por vida útil da sandbox, acionada pela primeira chamada invoke_llm. Esse carregamento descobre apenas seus registros app.llm(...) .
Interpreta corpos de ferramentas remotas e os executa sob demanda quando o Mecanismo de orquestração encaminha uma chamada de ferramenta para o sandbox.

O Atlas Agent Engine não executa as seguintes ações durante uma invocação de sandbox de ferramenta:

Execute seu gráfico.
Execute corpos de ferramentas locais.

O Mecanismo de Agente do Atlas fornece os segredos que você declara no campo sandboxes.tool.secrets como variáveis de ambiente na caixa de ferramentas de ferramentas. Cada corpo de ferramenta remota que é executado na sandbox de ferramentas pode ler essas variáveis de ambiente. Para saber mais sobre como as sandboxes compartilham segredos entre ferramentas, consulte Limitações do mecanismo do agente do MongoDB Atlas .

Resumo do ciclo de vida

A tabela a seguir resume quando cada parte do seu código é executada em cada processo de execução e fase:

Estágio	Processo	Código de nível superior	Ponto de entrada	Corpo de ferramenta remota	Corpo de ferramenta local
Inicialização	Agent Sandbox	Executado	Não executado	Interpretado apenas	Interpretado apenas
Inicialização	Sandbox de Ferramentas	Executado	Não executado	Interpretado apenas	Interpretado apenas
Por invocação	Agent Sandbox	Não executado	Executado uma vez	Interpretado, enviado para a Sandbox de Ferramentas	Executado
Primeira chamada `invoke_llm`	Sandbox de Ferramentas	Não executado	Executado uma vez, para registrar chamadas `app.llm(...)`	Não executado	Não executado
Por chamada de ferramenta	Sandbox de Ferramentas	Não executado	Não executado	Executado sob demanda	Não executado

Esquema YAML do agente

O arquivo agent.yaml configura como o Atlas Agent Engine descobre e executa seu agente. Ele oferece suporte a dois formatos: um manifesto de agente único para repositórios que contêm um agente e um manifesto de monorepo para repositórios que contêm vários agentes.

Manifesto de agente único

A tabela a seguir descreve os campos disponíveis para um arquivo agent.yaml de agente único. A coluna Required indica se um campo é exigido para um arquivo agent.yaml mínimo.

Campo	Tipo	Obrigatório	Descrição e restrições
`entrypoint`	string	sim	Caminho e atributo do módulo no formato `module.path:attribute`. Deve corresponder ao padrão regex `^[\w.]+:[\w]+$`, em que o lado esquerdo é o caminho do módulo separado por pontos e o lado direito é o nome do atributo.
`name`	string	no	Nome do agente. Deve conter apenas caracteres alfanuméricos minúsculos e hífen. Sem hífen inicial ou final.
`description`	string	no	Descrição do agente. Até 500 caracteres.
`agent_card.summary`	string	no	Resumo da finalidade do agente. Mostrado na UI.
`agent_card.capabilities`	list[string]	no	Rótulos que descrevem o que o agente pode fazer. Mostrado na UI.
`features.guardrails`	bool	no	Quando `true`, habilita a integração de grades de proteção.
`features.memory`	bool	no	Quando `true`, inicia um servidor de memória como um serviço separado. Os agentes acessam a memória por meio do cliente`app.memory`. Requer que o `VOYAGE_API_KEY` seja definido.
`features.deep_agent`	bool	no	Quando `true`, habilita o método de fábrica de agente profundos. Um gráfico que chama `app.deep_agent()` ou `app.deepAgent()` deve definir esse campo, ou o método gera um erro no momento da compilação. Para saber mais, consulte Criar um agente detalhado.
`features.playground`	bool	no	Quando `false`, o Atlas Agent Engine não provisiona a UI do Playground para o agente. Use esse campo para agentes que não produzem saída de conversação para visualizar e invoque-os usando a API. O padrão é `true`.
`features.use_custom_parser`	bool	no	Quando `true`, ativa a saída de fluxo personalizado. Requer um `OutputParser` registrado no gravador `@app.output_parser`. Se você definir esse campo como `true` sem registrar um analisador, uma invocação falhará quando o agente iniciar. Para saber mais, consulte Adicionar saída de stream personalizada ao seu agente.
`mcp.servers.<name>.transport`	string	quando `mcp.servers.<name>` é definido	Protocolo de transporte para uma conexão de servidor MCP remota. Valor aceito: `streamable_http`. Para saber mais, consulte Usar servidores MCP remotos.
`mcp.servers.<name>.url`	string	quando `mcp.servers.<name>` é definido	URL do ponto de extremidade do servidor MCP remoto.
`mcp.servers.<name>.headers`	map[string, string]	no	Cabeçalhos HTTP estáticos enviados com cada solicitação para o servidor MCP .
`mcp.servers.<name>.auth.type`	string	sim	Tipo de autenticação. Os valores aceitos são `bearer_env` e `oauth`.
`mcp.servers.<name>.auth.token_env`	string	quando `auth.type` é `bearer_env`	Nome da variável de ambiente que contém o token do portador. A variável deve ser definida em seu arquivo `.env`.
`mcp.servers.<name>.auth.scope`	string	quando `auth.type` é `oauth`	Escopos OAuth separados por espaço a serem solicitados durante o fluxo de autorização .
`mcp.servers.<name>.auth.client_name`	string	no	Nome legível por humanos para o cliente OAuth mostrado na tela de consenso.
`mcp.servers.<name>.allowed_tools`	list[string]	no	Lista de permissões de nomes de ferramentas MCP remotas a serem expostas ao agente. Quando definido, a plataforma registra apenas as ferramentas listadas e ignora todas as outras ferramentas que o servidor retorna. Quando omitido, a plataforma expõe todas as ferramentas que o servidor retorna. Use esse campo para limitar a superfície da ferramenta apenas às ferramentas necessárias para o agente .
`mcp.servers.<name>.timeout_seconds`	int	no	Solicite o tempo limite em segundos para cada chamada de ferramenta MCP. O padrão é `30`.
`scaling.replicas`	int	no	Contagem de pods estáticos para o sistema. O Atlas Agent Engine aplica esse valor separadamente à sandbox do agente e à sandbox da ferramenta. Cada sessão reserva uma sandbox de agente e, se configurada, uma sandbox de ferramenta, então esse valor é o número de sessões simultâneas que o sistema pode atender. Aceita um valor de 1 a 512. O padrão é 4 quando omitido.
`scaling.agent_idle_ttl_seconds`	int	no	Quanto tempo, em segundos, uma sessão ociosa mantém sua sandbox de agente reservada antes que o Atlas Agent Engine a recupere para outras sessões. Aceita um valor de 1 a 86400. O padrão é 600 quando omitido. `scaling.agent_idle_ttl_seconds` é um alias legado para este campo.
`scaling.tool_idle_ttl_seconds`	int	no	Quanto tempo, em segundos, uma sessão ociosa mantém sua sandbox de ferramenta reservada antes de o Atlas Agent Engine recuperá-la. Aceita um valor de 1 a 86400. O padrão é o valor `scaling.agent_idle_ttl_seconds`.
`sandboxes`	mapeamento	sim	Configura os sandboxes nomeados que executam seu agente e suas ferramentas. O Atlas Agent Engine suporta duas sandboxes nomeadas: `agent` e `tool`. Você não pode definir sandboxes adicionais, e o Atlas Agent Engine rejeita uma ferramenta que é atribuída a mais de uma sandbox. Para saber como as sandboxes compartilham segredos e destinos de saída entre ferramentas, consulte Limitações do mecanismo do agente do MongoDB Atlas .
`sandboxes.agent`	mapeamento	sim	Configuração da sandbox do agente , a sandbox isolada de hardware que executa seu código do agente .
`sandboxes.agent.secrets`	list[string]	no	Lista de nomes secretos, ou padrões glob que correspondem aos nomes secretos, disponíveis para a sandbox do agente . Você pode usar `*` para corresponder a todos os segredos. MONGODB_URI está automaticamente disponível e não precisa ser declarado.
`sandboxes.agent.tools`	list[string]	no	Lista de nomes de ferramentas, ou padrões glob que correspondem aos nomes de ferramentas, a serem executados na sandbox do agente . Você pode usar `*` para corresponder a todas as ferramentas. As ferramentas que não correspondem a nenhuma sandbox são executadas na sandbox do agente por padrão.
`sandboxes.agent.network`	mapeamento	no	Política de rede, incluindo regras de saída de saída, para a sandbox do agente . Para saber mais, consulte Gerenciar políticas de saída de rede.
`sandboxes.tool`	mapeamento	no	Configuração para a sandbox de ferramentas, a sandbox isolada de hardware que executa corpos de ferramentas remotas.
`sandboxes.tool.secrets`	list[string]	no	Lista de nomes secretos, ou padrões glob que correspondem aos nomes secretos, disponíveis na sandbox da ferramenta. Você pode usar `*` para corresponder a todos os segredos. MONGODB_URI está automaticamente disponível e não precisa ser declarado.
`sandboxes.tool.tools`	list[string]	no	Lista de nomes de ferramentas, ou padrões glob que correspondem aos nomes de ferramentas, a serem executados na sandbox de ferramentas. Você pode usar `*` para corresponder a todas as ferramentas. Para chamar um LLM a partir de um corpo de ferramenta, inclua a ferramenta `invoke_llm` nesta lista e declare sua chave de API do provedor de LLM em `sandboxes.tool.secrets`.
`artifact_repositories`	lista[mapeamento]	no	Declara registros de pacote privados para compilações gerenciadas. Cada entrada mapeia um nome de índice de registro para um segredo do Atlas Agent Engine que contém sua credencial. O Atlas Agent Engine injeta a credencial somente no tempo de compilação e não a expõe a pods em execução. Os URLs de registro residem nas ferramentas do seu projeto (`pyproject.toml`, `package.json` ou `.npmrc`), não neste bloco. Se você omitir esse campo, o Mecanismo do Atlas Agent resolverá as dependências de registros públicos usando sua configuração de ferramentas existente inalterada.
`artifact_repositories[].name`	string	sim	Identificador exclusivo da entrada. Para entradas PyPI, deve corresponder a um nome `[[tool.uv.index]]` em `pyproject.toml`. Para entradas npm, a validação compara `npm_scope` com o registro com escopo em `.npmrc` primeiro e, em seguida, volta para `name`. Deve corresponder a `^[a-z][a-z0-9-]*$` e ser exclusivo na lista.
`artifact_repositories[].type`	string	sim	Tipo de repositório. Os valores aceitos são `pypi` e `npm`.
`artifact_repositories[].secret`	string	sim	Nome do segredo do Atlas Agent Engine que contém a credencial. Deve corresponder a `^[A-Z][A-Z0-9_]{0,127}$`.
`artifact_repositories[].scope`	string	no	Escopo secreto. Os valores aceitos são `project` e `workspace`. O padrão é `project`.
`artifact_repositories[].auth`	string	no	Método de autenticação. Os valores aceitos são `token` e `basic`. O padrão é `token`.
`artifact_repositories[].username`	string	no	Nome de usuário para autenticação de registro. Obrigatório quando `auth` é `basic`. Para autenticação de token PyPI com este campo omitido, o padrão é `__token__`. a autenticação do token npm não usa um nome de usuário.
`artifact_repositories[].npm_scope`	string	no	escopo npm que mapeia para esse registro, como `@acme`. Quando fornecida, é a chave que corresponde ao registro com escopo em `.npmrc`. Válido somente quando `type` for `npm`.

artifact_repositories as credenciais são resolvidas somente no tempo de construção. Para saber como os repositórios de artefatos privados funcionam em compilações na nuvem e no desenvolvimento local, consulte Construir a imagem do agente e Executar agentes localmente.

Cada sessão reserva suas próprias sandboxes de agente e ferramenta durante sua vida útil, e o Atlas Agent Engine redefine uma sandbox antes de atribuí-la a uma nova sessão. Como resultado, os artefatos que uma sessão grava em uma sandbox não são visíveis para sessões posteriores.

O Atlas Agent Engine captura valores scaling no momento da compilação, para que as alterações entrem em vigor na próxima compilação e implementação. Uma alteração no padrão da plataforma não redimensiona um espaço de trabalho que já está implantado. O espaço de trabalho mantém a contagem de sandbox isolada de hardware de sua compilação mais recente até que você a construa e implemente novamente. Os valores de tempo de vida útil (TTL) ocioso se aplicam a todo o projeto. Quando vários agentes em um projeto definem valores diferentes, o projeto aplica os valores do agente implementado mais recentemente.

Observação

Você deve definir as configurações de desenvolvimento local em um arquivo dev.yaml separado no mesmo diretório que o arquivo agent.yaml, não no próprio agent.yaml. Para saber mais, consulte Configurar configurações de desenvolvimento local.

O exemplo a seguir mostra um arquivo agent.yaml com substituições de porta de serviço, sinalizadores de recursos, restrições de acesso secretas e um repositório de artefatos privado:

name: my-agent
entrypoint: my_agent.main:app
features:
  guardrails: true
scaling:
  replicas: 4
  agent_idle_ttl_seconds: 900
  tool_idle_ttl_seconds: 300
sandboxes:
  agent:
    secrets: ["*"]
    tools: []
  tool:
    secrets:
      - SEARCH_API_KEY
      - ANTHROPIC_API_KEY
    tools:
      - my_search_tool
      - invoke_llm
artifact_repositories:
  - name: corps-pypi
    type: pypi
    secret: ARTIFACT_REPO_CORPS_PYPI_TOKEN
    username: aws
    scope: project

Manifesto do Monorepo

Se o seu repositório contiver vários agentes, defina-os em um único arquivo agent.yaml usando uma lista agents: de nível superior. O Atlas Agent Engine detecta essa lista e trata o arquivo como um manifesto de monorepo em vez de uma configuração de agente único. O seguinte arquivo agent.yaml é um exemplo de um manifesto de monorepo com vários agentes:

agents:
  - name: chat
    path: agents/chat
  - name: research
    path: agents/research

Campo	Tipo	Obrigatório	Descrição
`agents[].name`	string	sim	Nome do agente. Deve conter apenas caracteres alfanuméricos minúsculos e hífen. Sem hífen inicial ou final. Deve ser exclusivo dentro da lista.
`agents[].path`	string	sim	Caminho para o subdiretório do agente, relativo à raiz do repositório. O caminho não pode fazer referência a locais fora do repositório.

Cada subdiretório de agente deve conter seu próprio arquivo agent.yaml de agente único.

Requisitos do .env

Você deve definir a variável de ambiente MONGODB_URI em seu arquivo .env para implantar seu agente com sucesso, se services.mongodb.local estiver definido como false em seu arquivo dev.yaml .

Seu agente também exige uma chave de API LLM no arquivo .env para processar solicitações no tempo de execução. A plataforma em si não valida nem exige credenciais LLM específicas, mas o agente falhará no tempo de execução sem elas. Use a sintaxe <PROVIDER>_API_KEY para definir a variável de ambiente para seu provedor de LLM.

Frameworks e provedores de LLM

Esta seção descreve as estruturas e fornecedores de LLM que você pode usar com o Atlas Agent Engine.

Frameworks

O Atlas Agent Engine é compatível com LangGraph e LangChain por meio do pacoteagent-engine-sdk-langgraph. O adaptador de estrutura lida com os seguintes pontos de integração:

interrupt() para pausar a execução do agente para revisão humana antes de continuar
MongoDBSaver por salvar o estado do gráfico do agente no MongoDB para que ele possa ser restaurado quando uma execução suspensa for retomada
LangChainInstrumentor para gravar chamadas de LLM e ferramentas durante a execução para depuração e monitoramento

Fornecedores de LLM

Você pode usar qualquer fornecedor de LLM com seu agente. Para usar um modelo, construa um LangChain BaseChatModel para o provedor e passe para o método app.llm(). O Atlas Agent Engine roteia essa chamada pelo Mecanismo de orquestração.

A tabela a seguir mostra exemplos de fornecedores comuns com sua chave de ambiente e classe LangChain:

Fornecedor	Chave de ambiente	Classe LangChain
OpenAI	`OPENAI_API_KEY`	`ChatOpenAI`
Antrópico	`ANTHROPIC_API_KEY`	`ChatAnthropic`
Gemini	`GEMINI_API_KEY` (opcional: `GEMINI_MODEL`)	`ChatGoogleGenerativeAI`
Cerebras	`CEREBRAS_API_KEY` (opcional: `CEREBRAS_MODEL`)	`ChatCerebras`

Os seguintes exemplos de código mostram como configurar cada provedor para o método app.llm():

# OpenAI
from langchain_openai import ChatOpenAI
llm = app.llm(ChatOpenAI(model="gpt-4o-mini"))
# Anthropic
from langchain_anthropic import ChatAnthropic
llm = app.llm(ChatAnthropic(model="claude-sonnet-4-5"))
# Gemini
from langchain_google_genai import ChatGoogleGenerativeAI
llm = app.llm(ChatGoogleGenerativeAI(model="gemini-2.5-flash-lite"))
# Cerebras
from langchain_cerebras import ChatCerebras
llm = app.llm(ChatCerebras(model="qwen-3-235b-a22b-instruct-2507"))

Próximos passos

Para saber como autenticar e invocar um agente implementado, consulte o guia Invoke an Agent (Invoque um agente).

Limitações de visualização pública