Referencia del contrato del agente

Overview

En esta guía, aprenderá los requisitos mínimos para ejecutar un agente en el Motor de Agentes de MongoDB Atlas. Esta guía abarca los archivos que el Motor de Agentes de Atlas necesita para detectar y ejecutar su agente, el esquema agent.yaml y los marcos de trabajo y proveedores LLM compatibles.

Los agentes no implementan su propio punto final HTTP. El motor de agentes de Atlas importa el agente dentro del mismo proceso que el entorno aislado del agente.

Agente mínimo desplegable

Un agente desplegable mínimo consta de dos archivos:

my_agent/main.py: define el objeto App y el grafo.
agent.yaml: apunta al objeto App definido en my_agent/main.py.

El siguiente ejemplo muestra un archivo main.py mínimo que define un objeto App llamado my-agent y construye un gráfico de agentes:

mi_agente/principal.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()

El siguiente ejemplo muestra un archivo agent.yaml mínimo:

agent.yaml

entrypoint: my_agent.main:app

En el archivo main.py, debe ejecutar los siguientes componentes:

Defina un objeto App a nivel de módulo, generalmente llamado app.
Registra un punto de entrada a la aplicación con la función @app.entrypoint.
Registra las herramientas con la función @app.tool(...).
Llama a la función app.run() que se encuentra al final del módulo.

En el archivo agent.yaml, debe establecer la clave YAML entrypoint al objeto App utilizando el formato <module.path>:<attribute>.

Directrices para agentes

Siga estas directrices para garantizar que su agente funcione correctamente con las funciones de la plataforma, como el registro de auditoría, la aplicación de políticas y la suspensión o reanudación de las ejecuciones del agente:

Enrutar las llamadas a la herramienta y a LLM a través de las funciones app.tool(...) y app.llm(...).

El motor del agente Atlas utiliza estos contenedores para el registro de auditoría, la aplicación de políticas y la reproducción de herramientas y llamadas LLM al reanudar una ejecución suspendida. Las llamadas realizadas fuera de estos contenedores no son auditadas por el motor del agente Atlas y no se reproducen correctamente tras reanudar la ejecución.
Mantén el estado de tu gráfico serializable en formato JSON/BSON.

Los entornos aislados de agentes son efímeros, por lo que el motor de agentes de Atlas guarda los estados de los puntos de control en MongoDB entre las acciones de suspensión y reanudación. Para que el punto de control se complete correctamente, cada valor del estado del gráfico debe ser serializable a JSON o BSON, como por ejemplo, tipos de datos primitivos, listas, diccionarios, datetime, Enum y subclases de LangChain BaseMessage. No almacene expresiones lambda, cierres, identificadores de archivos, conexiones a bases de datos ni clases personalizadas en el estado del gráfico sin compatibilidad con la serialización.
Llamar al app.llm(...) Funciona únicamente mientras su punto de entrada se encuentre en la pila de llamadas.

Cuando se llama a app.llm(...) desde el código de nivel superior del módulo, el cuerpo de una herramienta o cualquier otra función que no se invoque en el punto de entrada, el motor del agente de Atlas genera un error que identifica el archivo y la línea con la llamada no válida. Para obtener más información, consulte Ciclo de vida de la ejecución.

Ciclo de vida de ejecución

El motor de agentes de Atlas carga y ejecuta el código de su agente en puntos definidos del ciclo de vida de los siguientes procesos:

Entorno de pruebas para agentes, que ejecuta el código de tu agente y construye tu gráfico.
Tool Sandbox, que ejecuta los cuerpos de las herramientas remotas en un proceso separado del entorno aislado del agente.

Nota

Este ciclo de ejecución es el mismo en los SDK de Python y TypeScript.

Esta sección describe cuándo se ejecutan las distintas partes del código de su agente en cada proceso y utiliza los siguientes términos:

El código de nivel superior del módulo es el código que se encuentra en los archivos fuente de su agente y que se ejecuta en el momento de la importación, fuera del cuerpo de cualquier función.
El punto de entrada es la función que decoras con @app.entrypoint.
Una herramienta local se ejecuta únicamente dentro del proceso del entorno aislado del agente. Por defecto, cualquier herramienta que registre con el decorador @app.tool() es una herramienta local.
Una herramienta remota es una herramienta que se asigna al entorno aislado de herramientas incluyéndola en el campo sandboxes.tool.tools del archivo agent.yaml. El entorno aislado del agente interpreta las herramientas remotas, pero los cuerpos de las herramientas remotas se ejecutan dentro del entorno aislado de herramientas.

Startup

Tanto en el entorno aislado del agente como en el entorno aislado de la herramienta, el motor del agente de Atlas realiza las siguientes acciones al iniciarse:

Carga los archivos fuente de tu agente.
Ejecuta el código de nivel superior de tu módulo.

La plataforma no realiza las siguientes acciones al iniciarse:

Ejecuta tu punto de entrada.
Ejecuta los cuerpos de tus herramientas. El motor del agente Atlas interpreta las definiciones de las herramientas para registrar sus firmas, pero no las ejecuta.

El código de nivel superior del módulo puede acceder a secretos de todo el proceso, como MONGODB_URI y las credenciales OAuth de MCP, ya que estos valores están disponibles durante toda la vida útil del proceso. El motor del agente Atlas también establece los secretos que se declaran para un entorno aislado, incluidas las claves de API de LLM, cuando se inicia dicho entorno. Como resultado, el código de nivel superior del módulo en un entorno aislado puede acceder a los secretos de ese entorno.

Invocación del entorno aislado del agente

En el entorno aislado del agente, el motor del agente Atlas realiza las siguientes acciones durante una invocación:

Ejecuta tu punto de entrada una sola vez.
Ejecuta los cuerpos de las herramientas locales en el propio proceso del entorno aislado del agente.

La plataforma no realiza las siguientes acciones durante la invocación de un entorno aislado de agente:

Ejecuta los cuerpos de las herramientas remotas. El entorno aislado del agente los interpreta y luego envía la llamada al entorno aislado de la herramienta.

Invocación del entorno aislado de herramientas

En el entorno aislado de la herramienta, el motor del agente Atlas realiza las siguientes acciones durante una invocación:

Carga tu punto de entrada de forma diferida, exactamente una vez durante la vida útil del entorno aislado, activada por la primera llamada a invoke_llm. Esta carga solo descubre tus registros de app.llm(...).
Interpreta los cuerpos de las herramientas remotas y, a continuación, las ejecuta bajo demanda cuando el motor de orquestación dirige una llamada a la herramienta al entorno aislado.

El motor del agente Atlas no realiza las siguientes acciones durante la invocación de un entorno aislado de herramientas:

Ejecuta tu gráfico.
Ejecutar cuerpos de herramientas locales.

El motor del agente Atlas entrega los secretos que usted declara en el campo sandboxes.tool.secrets como variables de entorno en el entorno aislado de la herramienta. Cada cuerpo de herramienta remota que se ejecuta en el entorno aislado puede leer estas variables de entorno. Para obtener más información sobre cómo los entornos aislados comparten secretos entre herramientas, consulte Limitaciones del motor del agente Atlas de MongoDB.

Resumen del ciclo de vida

La siguiente tabla resume cuándo se ejecuta cada parte de su código en cada proceso y fase de ejecución:

Fase	Proceso	Código de nivel superior	Punto de entrada	Cuerpo de la herramienta remota	Cuerpo de herramientas local
Startup	Agent Sandbox	Ejecutado	No ejecutado	Solo interpretado	Solo interpretado
Startup	Entorno de pruebas de herramientas	Ejecutado	No ejecutado	Solo interpretado	Solo interpretado
Por invocación	Agent Sandbox	No ejecutado	Ejecutado una vez	Interpretado, enviado a Tool Sandbox	Ejecutado
Primera llamada `invoke_llm`	Entorno de pruebas de herramientas	No ejecutado	Se ejecuta una vez para registrar las llamadas `app.llm(...)`.	No ejecutado	No ejecutado
Llamada por herramienta	Entorno de pruebas de herramientas	No ejecutado	No ejecutado	Ejecutado bajo demanda	No ejecutado

Esquema YAML del agente

El archivo agent.yaml configura cómo el motor de agentes de Atlas descubre y ejecuta su agente. Admite dos formatos: un manifiesto de agente único para repositorios que contienen un solo agente y un manifiesto de monorepo para repositorios que contienen varios agentes.

Manifiesto de agente único

La siguiente tabla describe los campos disponibles para un archivo agent.yaml de agente único. La columna Required indica si un campo es obligatorio para un archivo agent.yaml mínimo.

Campo	Tipo	Requerido	Descripción y restricciones
`entrypoint`	string	Sí	Ruta del módulo y atributo en formato `module.path:attribute`. Debe coincidir con el patrón de expresión regular `^[\w.]+:[\w]+$`, donde el lado izquierdo es la ruta del módulo separada por puntos y el lado derecho es el nombre del atributo.
`name`	string	no	Nombre del agente. Debe contener únicamente caracteres alfanuméricos en minúscula y guiones. No se permiten guiones al principio ni al final.
`description`	string	no	Descripción del agente. Hasta 500 caracteres.
`agent_card.summary`	string	no	Resumen del propósito del agente. Se muestra en la interfaz de usuario.
`agent_card.capabilities`	list[string]	no	Etiquetas que describen las funciones del agente. Se muestran en la interfaz de usuario.
`features.guardrails`	bool	no	Cuando `true`, habilita la integración de las barandillas de seguridad.
`features.memory`	bool	no	Cuando `true`, inicia un servidor de memoria como un servicio independiente. Los agentes acceden a la memoria a través del cliente `app.memory`. Requiere que `VOYAGE_API_KEY` esté configurado.
`features.deep_agent`	bool	no	Cuando `true`, habilita el método de fábrica del agente profundo. Un gráfico que llama a `app.deep_agent()` o `app.deepAgent()` debe establecer este campo; de lo contrario, el método generará un error durante la compilación. Para obtener más información, consulte la sección "Crear un agente profundo".
`features.playground`	bool	no	Cuando `false`, el motor de agentes de Atlas no proporciona la interfaz de usuario de Playground para el agente. Utilice este campo para los agentes que no generan salida conversacional para previsualizar y, en su lugar, invóquelos mediante la API. El valor predeterminado es `true`.
`features.use_custom_parser`	bool	no	Cuando `true`, habilita la salida de flujo personalizada. Requiere un `OutputParser` registrado con el decorador `@app.output_parser`. Si configura este campo en `true` sin registrar un analizador, la invocación fallará al iniciar el agente. Para obtener más información, consulte Agregar salida de flujo personalizada a su agente.
`mcp.servers.<name>.transport`	string	cuando `mcp.servers.<name>` está definido	Protocolo de transporte para una conexión remota a un servidor MCP. Valor aceptado: `streamable_http`. Para obtener más información, consulte Uso de servidores MCP remotos.
`mcp.servers.<name>.url`	string	cuando `mcp.servers.<name>` está definido	URL del punto final del servidor MCP remoto.
`mcp.servers.<name>.headers`	mapa[cadena, cadena]	no	Encabezados HTTP estáticos enviados con cada solicitud al servidor MCP.
`mcp.servers.<name>.auth.type`	string	Sí	Tipo de autenticación. Los valores aceptados son `bearer_env` y `oauth`.
`mcp.servers.<name>.auth.token_env`	string	cuando `auth.type` es `bearer_env`	Nombre de la variable de entorno que contiene el token de portador. La variable debe estar configurada en su archivo `.env`.
`mcp.servers.<name>.auth.scope`	string	cuando `auth.type` es `oauth`	Ámbitos OAuth separados por espacios que se solicitarán durante el flujo de autorización.
`mcp.servers.<name>.auth.client_name`	string	no	Nombre legible para el cliente OAuth que se muestra en la pantalla de consentimiento.
`mcp.servers.<name>.allowed_tools`	list[string]	no	Lista de herramientas MCP remotas permitidas para el agente. Al configurarla, la plataforma registra solo las herramientas indicadas e ignora las demás que devuelve el servidor. Si se omite, la plataforma muestra todas las herramientas que devuelve el servidor. Utilice este campo para limitar la superficie de herramientas a las que su agente requiere.
`mcp.servers.<name>.timeout_seconds`	Int	no	Tiempo de espera de solicitud en segundos para cada llamada a la herramienta MCP. El valor predeterminado es `30`.
`scaling.replicas`	Int	no	Recuento estático de pods para el despliegue. El motor de agentes de Atlas aplica este valor por separado al entorno aislado del agente y al entorno aislado de la herramienta. Cada sesión reserva un entorno aislado del agente y, si está configurado, un entorno aislado de la herramienta; por lo tanto, este valor representa el número de sesiones concurrentes que puede atender el despliegue. Admite un valor entre 1 y 512. Si se omite, se utiliza 4 por defecto.
`scaling.agent_idle_ttl_seconds`	Int	no	Indica cuánto tiempo, en segundos, conserva una sesión inactiva su espacio de trabajo reservado antes de que el motor de agentes de Atlas lo recupere para otras sesiones. Admite valores entre 1 y 86400. Si se omite, el valor predeterminado es 600. `scaling.agent_idle_ttl_seconds` es un alias antiguo para este campo.
`scaling.tool_idle_ttl_seconds`	Int	no	Indica cuánto tiempo, en segundos, una sesión inactiva conserva su espacio reservado para herramientas antes de que el motor del agente Atlas lo recupere. Acepta un valor entre 1 y 86400. El valor predeterminado es `scaling.agent_idle_ttl_seconds`.
`sandboxes`	mapeo	Sí	Configura los entornos aislados (sandboxes) con nombre que ejecutan tu agente y sus herramientas. El motor del agente Atlas admite dos entornos aislados con nombre: `agent` y `tool`. No puedes definir entornos aislados adicionales, y el motor del agente Atlas rechaza una herramienta que esté asignada a más de un entorno aislado. Para saber cómo los entornos aislados comparten secretos y destinos de salida entre herramientas, consulta Limitaciones del motor del agente Atlas de MongoDB.
`sandboxes.agent`	mapeo	Sí	Configuración del entorno aislado del agente, el entorno aislado por hardware que ejecuta el código de su agente.
`sandboxes.agent.secrets`	list[string]	no	Lista de nombres secretos, o patrones glob que coinciden con los nombres secretos, disponibles para el entorno aislado del agente. Puede usar `*` para que coincida con todos los secretos. MONGODB_URI está disponible automáticamente y no necesita declararse.
`sandboxes.agent.tools`	list[string]	no	Lista de nombres de herramientas, o patrones glob que coincidan con los nombres de las herramientas, para ejecutar en el entorno aislado del agente. Puede usar `*` para que coincida con todas las herramientas. Las herramientas que no coincidan con ningún entorno aislado se ejecutan en el entorno aislado del agente de forma predeterminada.
`sandboxes.agent.network`	mapeo	no	Política de red, incluidas las reglas de salida, para el entorno aislado del agente. Para obtener más información, consulte Administrar políticas de salida de red.
`sandboxes.tool`	mapeo	no	Configuración del entorno aislado de herramientas, el entorno aislado de hardware que ejecuta los cuerpos de las herramientas remotas.
`sandboxes.tool.secrets`	list[string]	no	Lista de nombres secretos, o patrones glob que coinciden con los nombres secretos, disponibles en el entorno aislado de la herramienta. Puede usar `*` para que coincida con todos los secretos. MONGODB_URI está disponible automáticamente y no necesita declararse.
`sandboxes.tool.tools`	list[string]	no	Lista de nombres de herramientas, o patrones glob que coincidan con los nombres de las herramientas, para ejecutar en el entorno aislado de la herramienta. Puede usar `*` para que coincida con todas las herramientas. Para llamar a una LLM desde el cuerpo de una herramienta, incluya la herramienta `invoke_llm` en esta lista y declare su clave API de proveedor de LLM en `sandboxes.tool.secrets`.
`artifact_repositories`	lista[mapeo]	no	Declara registros de paquetes privados para compilaciones gestionadas. Cada entrada asigna un nombre de índice de registro a un secreto de Atlas Agent Engine que contiene su credencial. Atlas Agent Engine inyecta la credencial solo durante la compilación y no la expone a los pods en ejecución. Las URL de los registros se encuentran en las herramientas de su proyecto (`pyproject.toml`, `package.json` o `.npmrc`), no en este bloque. Si omite este campo, Atlas Agent Engine resuelve las dependencias de los registros públicos utilizando la configuración de herramientas existente sin modificaciones.
`artifact_repositories[].name`	string	Sí	Identificador único para la entrada. Para las entradas de PyPI, debe coincidir con un nombre `[[tool.uv.index]]` en `pyproject.toml`. Para las entradas de npm, la validación compara `npm_scope` con el registro con ámbito en `.npmrc` primero, y luego recurre a `name`. Debe coincidir con `^[a-z][a-z0-9-]*$` y ser único en la lista.
`artifact_repositories[].type`	string	Sí	Tipo de repositorio. Los valores aceptados son `pypi` y `npm`.
`artifact_repositories[].secret`	string	Sí	Nombre del secreto de Atlas Agent Engine que contiene la credencial. Debe coincidir con `^[A-Z][A-Z0-9_]{0,127}$`.
`artifact_repositories[].scope`	string	no	Ámbito secreto. Los valores aceptados son `project` y `workspace`. El valor predeterminado es `project`.
`artifact_repositories[].auth`	string	no	Método de autenticación. Los valores aceptados son `token` y `basic`. El valor predeterminado es `token`.
`artifact_repositories[].username`	string	no	Nombre de usuario para la autenticación del registro. Obligatorio cuando `auth` es `basic`. Para la autenticación por token de PyPI con este campo omitido, el valor predeterminado es `__token__`. La autenticación por token de npm no utiliza un nombre de usuario.
`artifact_repositories[].npm_scope`	string	no	Ámbito de npm que se asigna a este registro, como `@acme`. Cuando se proporciona, es la clave que coincide con el registro con ámbito en `.npmrc`. Válido solo cuando `type` es `npm`.

artifact_repositories Las credenciales se resuelven únicamente durante la compilación. Para obtener información sobre cómo funcionan los repositorios de artefactos privados en las compilaciones en la nube y el desarrollo local, consulte la sección "Crear la imagen del agente" y "Ejecutar agentes localmente".

Cada sesión reserva sus propios entornos aislados de agente y herramientas durante su vida útil, y el motor de agentes de Atlas restablece un entorno aislado antes de asignarlo a una nueva sesión. Como resultado, los artefactos que una sesión escribe en un entorno aislado no son visibles para las sesiones posteriores.

Atlas Agent Engine guarda instantáneas de los valores de scaling durante la compilación, por lo que los cambios surten efecto en la siguiente compilación e implementación. Un cambio en la configuración predeterminada de la plataforma no modifica el tamaño de un espacio de trabajo ya implementado. El espacio de trabajo conserva el número de entornos aislados por hardware de su compilación más reciente hasta que se vuelva a compilar e implementar. Los valores de tiempo de vida (TTL) en estado inactivo se aplican a todo el proyecto. Cuando varios agentes de un mismo proyecto establecen valores diferentes, el proyecto aplica los valores del agente implementado más recientemente.

Nota

Debes configurar los ajustes de desarrollo local en un archivo dev.yaml independiente, ubicado en el mismo directorio que el archivo agent.yaml, no en el archivo agent.yaml. Para obtener más información, consulta Configurar los ajustes de desarrollo local.

El siguiente ejemplo muestra un archivo agent.yaml con anulaciones de puertos de servicio, indicadores de características, restricciones de acceso secretas y un repositorio de artefactos 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

Manifiesto de monorepo

Si su repositorio contiene varios agentes, defínalos en un único archivo agent.yaml utilizando una lista agents: de nivel superior. El motor de agentes de Atlas detecta esta lista y trata el archivo como un manifiesto de monorepo en lugar de una configuración de agente único. El siguiente archivo agent.yaml es un ejemplo de un manifiesto de monorepo con varios agentes:

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

Campo	Tipo	Requerido	Descripción
`agents[].name`	string	Sí	Nombre del agente. Debe contener únicamente caracteres alfanuméricos en minúscula y guiones. No se permiten guiones al principio ni al final. Debe ser único en la lista.
`agents[].path`	string	Sí	Ruta al subdirectorio del agente, relativa a la raíz del repositorio. La ruta no puede hacer referencia a ubicaciones fuera del repositorio.

Cada subdirectorio de agente debe contener su propio archivo agent.yaml de agente único.

Requisitos de .env

Debe configurar la variable de entorno MONGODB_URI en su archivo .env para implementar su agente correctamente, si services.mongodb.local está configurado como false en su archivo dev.yaml.

Su agente también requiere una clave API de LLM en el archivo .env para procesar las solicitudes en tiempo de ejecución. La plataforma no valida ni requiere credenciales LLM específicas, pero el agente fallará en tiempo de ejecución sin ellas. Utilice la sintaxis <PROVIDER>_API_KEY para configurar la variable de entorno de su proveedor LLM.

Marcos de referencia y proveedores de LLM

Esta sección describe los marcos de trabajo y los proveedores LLM que puede utilizar con Atlas Agent Engine.

Frameworks

El motor de agentes Atlas admite LangGraph y LangChain a través del paquete agent-engine-sdk-langgraph. El adaptador del marco de trabajo gestiona los siguientes puntos de integración:

interrupt() para pausar la ejecución del agente para su revisión humana antes de que continúe
MongoDBSaver para guardar el estado del gráfico del agente en MongoDB para que pueda restaurarse cuando se reanude una ejecución suspendida.
LangChainInstrumentor para registrar las llamadas a LLM y a las herramientas durante la ejecución para depuración y monitorización.

Proveedores de LLM

Puedes usar cualquier proveedor LLM con tu agente. Para usar un modelo, crea una LangChain BaseChatModel para el proveedor y pásala al método app.llm(). El motor del agente Atlas enruta esa llamada a través del motor de orquestación.

La siguiente tabla muestra ejemplos comunes de proveedores con su clave de entorno y clase LangChain:

Proveedor	Clave del entorno	Clase LangChain
OpenAI	`OPENAI_API_KEY`	`ChatOpenAI`
Anthropic	`ANTHROPIC_API_KEY`	`ChatAnthropic`
Gemini	`GEMINI_API_KEY` (opcional: `GEMINI_MODEL`)	`ChatGoogleGenerativeAI`
Cerebras	`CEREBRAS_API_KEY` (opcional: `CEREBRAS_MODEL`)	`ChatCerebras`

Los siguientes ejemplos de código muestran cómo configurar cada proveedor para el 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 pasos

Para aprender a autenticar e invocar un agente desplegado, consulte la guía "Invocar un agente".

Limitaciones de la vista previa pública