Invocar un agente

Invoca a tu agente

Para invocar un agente, envíe una solicitud POST al punto final de la API /api/v1/projects/{project_id}/workspaces/{workspace_id}/invoke. La respuesta devuelve el resultado y el estado de la ejecución. La plataforma devuelve el ID de sesión en el encabezado de respuesta X-Session-ID.

El siguiente ejemplo curl utiliza estos marcadores de posición:

• $API_KEY: Su clave API de Atlas Agent Engine

• $PROJECT_ID: ID de tu proyecto

• $WORKSPACE_ID: Tu ID de espacio de trabajo

Seleccione la pestaña correspondiente a su idioma preferido para ver un ejemplo de solicitud de invocación:

curl -s "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/invoke" \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, agent!"}'

import httpx
response = httpx.post(
    f"https://agentengine.mongodb.com/api/v1/projects/{project_id}/workspaces/{workspace_id}/invoke",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"message": "Hello, agent!"},
    timeout=60.0,
)
result = response.json()

La respuesta se asemeja a la siguiente salida:

{
  "success": true,
  "response": "<agent output>",
  "execution_id": "string",
  "status": "completed"
}

Si la ejecución se suspende para revisión humana, la respuesta también incluye los campos suspend_reason y suspend_context. Para obtener más información, consulte el ciclo de vida Suspender, revisar y reanudar en la guía de Interacción Humana.

Transmita la salida de su agente

Para transmitir la salida de un agente a medida que se produce, envíe una solicitud POST al punto final de la API /api/v1/projects/{project_id}/workspaces/{workspace_id}/invokeStream. La plataforma devuelve la respuesta como una secuencia de tramas de eventos enviados por el servidor (SSE). La conexión permanece abierta hasta que la ejecución finaliza o falla.

Cada trama SSE comienza con el prefijo data: y contiene un único objeto JSON. El siguiente ejemplo muestra el formato de una trama de transmisión:

data: {"chunk_type": "text", "content": "Hello, agent!", "metadata": {}, "execution_id": "string"}

Un marco puede incluir los siguientes campos:

Otros puntos finales

El motor de agentes Atlas también expone los siguientes puntos finales de API para la transmisión, el sondeo, la reanudación y la detención de ejecuciones:

Cada punto final executions/** requiere el parámetro de consulta workspace_id. La puerta de enlace utiliza este valor para enrutar la solicitud al motor de orquestación del espacio de trabajo propietario.

Ciclo de vida del estado de ejecución

Una ejecución pasa por los estados pending, running y luego completed o error.

Si la ejecución se suspende para revisión humana, pasa por estados adicionales antes de completarse. Para obtener más información sobre el ciclo de vida de suspensión y reanudación, consulte el apartado "Ciclo de vida de suspensión, revisión y reanudación" en la guía "Intervención humana".

Si cancelas una ejecución, esta alcanza el estado cancelled. Este estado es distinto de completed y error, lo que permite a los clientes de la API y la interfaz de usuario diferenciar una ejecución detenida deliberadamente de una que finalizó o falló. Para obtener más información, consulta Cancelar una sesión.

Errores de saturación del pool

El motor de agentes de Atlas no escala automáticamente las implementaciones de agentes. El campo scaling.replicas del archivo agent.yaml establece un número fijo de entornos aislados (sandboxes), y cada sesión reserva un entorno aislado para agentes y otro para herramientas durante su vida útil. Por lo tanto, este campo determina el número de sesiones que una implementación puede atender simultáneamente.

El campo scaling.replicas acepta un valor entre 1 y 512, y por defecto toma el valor 4 si se omite. Cuando todos los entornos aislados están reservados, una nueva solicitud de invocación falla con un error pool full.

El límite de entornos aislados concurrentes 512 se aplica al Motor de Orquestación, que está vinculado a un proyecto y puede dar servicio a más de un agente. Los valores scaling.replicas de todos los agentes de un proyecto se contabilizan para el mismo límite. Para ejecutar más entornos aislados de los que permite un proyecto, distribuya los agentes entre varios proyectos.

Para evitar que las solicitudes de invocación agoten el grupo de sesiones, reutilice los ID de sesión entre las solicitudes. Las solicitudes que comparten un ID de sesión reutilizan una reserva, pero las que no lo incluyen utilizan un nuevo par de entornos aislados. Un ID de sesión debe tener entre 1 y 128 caracteres y puede contener letras, números, guiones bajos (_) y guiones (-). Pase el ID de sesión en la opción --session del comando agentengine invoke o en el encabezado X-Session-ID de una solicitud de API.

Si sus solicitudes de invocación requieren aislamiento por sesión, no puede reutilizar un ID de sesión. Para atender más sesiones simultáneamente, aumente el valor de scaling.replicas o reduzca los valores de scaling.agent_idle_ttl_seconds y scaling.tool_idle_ttl_seconds para que las sesiones inactivas liberen sus entornos aislados antes.

Dado que Atlas Agent Engine captura los valores de scaling durante la compilación, debe compilar e implementar el agente nuevamente para que los cambios surtan efecto. Para obtener más información sobre estos campos, consulte la Referencia del contrato del agente. Para revisar todas las limitaciones que se aplican durante la vista previa pública, consulte Limitaciones de MongoDB Atlas Agent Engine.

Cómo funciona

En una solicitud de invocación o reanudación, la puerta de enlace API procesa los encabezados HTTP con el prefijo X-Mdb-Agent-Engine-Custom- realizando los siguientes pasos:

1. La puerta de enlace API extrae el encabezado.

2. La puerta de enlace elimina el prefijo y convierte el nombre del encabezado a minúsculas. Por ejemplo, X-Mdb-Agent-Engine-Custom-Authorization se convierte en authorization.

3. La puerta de enlace reenvía los encabezados al agente como un diccionario.

Los encabezados se envían en memoria a través del proceso de ejecución, nunca se almacenan en la base de datos y el proceso los descarta cuando finaliza la ejecución.

Enviar encabezados personalizados

Agregue encabezados con el prefijo X-Mdb-Agent-Engine-Custom- a su solicitud de invocación. La puerta de enlace de API elimina el prefijo antes de que el agente los reciba.

Los siguientes ejemplos utilizan los mismos marcadores de posición que los ejemplos de la API de invocación. También utilizan marcadores de posición para los encabezados personalizados que se desean reenviar.

Seleccione la pestaña correspondiente a su idioma preferido para ver un ejemplo de solicitud de invocación con encabezados personalizados:

curl -s "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/invoke" \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Mdb-Agent-Engine-Custom-Authorization: my-user-id" \
  -H "X-Mdb-Agent-Engine-Custom-Tenant-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, agent!"}'

import httpx
response = httpx.post(
    f"https://agentengine.mongodb.com/api/v1/projects/{project_id}/workspaces/{workspace_id}/invoke",
    headers={
        "Authorization": f"Bearer {api_key}",
        "X-Mdb-Agent-Engine-Custom-Authorization": "my-user-id",
        "X-Mdb-Agent-Engine-Custom-Tenant-Id": "acme-corp",
    },
    json={"message": "Hello, agent!"},
)

El agente recibe el siguiente diccionario después de ejecutar el código anterior:

{"authorization": "my-user-id", "tenant-id": "acme-corp"}

Lea los encabezados en su agente.

Utilice el método get_current_custom_headers() de agent_engine_runner_shared dentro de cualquier herramienta para acceder a los encabezados que la puerta de enlace API reenvió al agente. El siguiente código Python muestra cómo usar get_current_custom_headers() para acceder a los encabezados reenviados:

from agent_engine_sdk_langgraph import App
from agent_engine_runner_shared import get_current_custom_headers
app = App(app_name="My Agent")
@app.tool(is_local=True)
def call_external_api(query: str) -> str:
    """Call an external API using the caller's user ID."""
    headers = get_current_custom_headers()
    user_id = headers.get("authorization", "")
    tenant = headers.get("tenant-id", "")
    response = httpx.get(
        "https://api.example.com/data",
        headers={"Authorization": user_id, "X-Tenant-Id": tenant},
        params={"q": query},
    )
    return response.text

El método get_current_custom_headers() devuelve un dict[str, str]. Si la puerta de enlace no envió ningún encabezado personalizado, el método devuelve un diccionario vacío.

Solicitudes de currículum

El reenvío de encabezados personalizados también funciona con las solicitudes de reanudación. Dado que Atlas Agent Engine no conserva los encabezados personalizados, debe reenviar los mismos encabezados X-Mdb-Agent-Engine-Custom- al reanudar una ejecución suspendida. Para ver un ejemplo de solicitud de reanudación que reenvía encabezados personalizados, consulte la guía «Uso de la API en el bucle humano».

Cancelar una sesión

Para cancelar una ejecución en curso, envíe una solicitud POST al punto final /api/v1/projects/{project_id}/executions/{execution_id}/cancel y configure el parámetro de consulta workspace_id. La solicitud no requiere un cuerpo.

Seleccione la pestaña correspondiente a su idioma preferido para ver un ejemplo de cómo cancelar una ejecución:

curl -X POST "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/executions/$EXECUTION_ID/cancel?workspace_id=$WORKSPACE_ID" \
  -H "Authorization: Bearer $API_KEY"

import httpx
response = httpx.post(
    f"https://agentengine.mongodb.com/api/v1/projects/{project_id}/executions/{execution_id}/cancel",
    params={"workspace_id": workspace_id},
    headers={"Authorization": f"Bearer {api_key}"},
)

La respuesta se asemeja a la siguiente salida:

{
  "execution_id": "string",
  "cancelled": true,
  "status": "cancelled"
}

El campo cancelled indica si esta solicitud cambió el estado de ejecución a cancelled. El valor del campo es true para una ejecución cancelled y false cuando la solicitud no cambió de estado de ejecución porque ya había alcanzado un estado terminal, incluido cancelled de una solicitud anterior. Cuando el valor del campo es false, el campo status informa el estado terminal registrado.

Cuando cancelas una ejecución, el motor del agente de Atlas hace lo siguiente:

• Cancela las llamadas a herramientas o LLM en curso, desmantela el entorno aislado del agente y de la herramienta de la sesión, y libera el espacio de capacidad. Una nueva ejecución puede reutilizar dicho espacio.

• Cancela todas las demás ejecuciones en vivo en la misma sesión, incluidas las ejecuciones de agente profundo y de agente a agente que sean hijas de la ejecución de destino.

• Finaliza una secuencia de respuestas abierta en lugar de dejarla abierta hasta que expire el tiempo de espera.

• Factura el tiempo de ejecución acumulado durante la sesión hasta su cancelación.

Detén una carrera en el patio de recreo

También puedes detener una ejecución desde la interfaz de usuario de Playground en lugar de llamar al punto final de la API cancel. Detener una ejecución desde Playground tiene el mismo efecto que cancelar la sesión. Para obtener más información, consulta Cancelar una sesión.

Para detener una carrera desde el área de juegos, siga los siguientes pasos:

Interrumpir una llamada a una herramienta o LLM

Interrumpir una llamada de herramienta o LLM detiene únicamente esa llamada. La sesión permanece activa y el agente continúa su ejecución desde el resultado de la interrupción. Interrumpa una llamada cuando una llamada individual se bloquea o no es deseada y no desea cancelar toda la sesión.

Para interrumpir una llamada, envíe una solicitud POST al punto final de la API /api/v1/projects/{project_id}/executions/{execution_id}/interrupt. La solicitud toma los siguientes parámetros:

Seleccione la pestaña correspondiente a su idioma preferido para ver un ejemplo de cómo interrumpir una llamada a una herramienta o a LLM:

curl -X POST "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/executions/$EXECUTION_ID/interrupt?workspace_id=$WORKSPACE_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step_number": 12}'

import httpx
response = httpx.post(
    f"https://agentengine.mongodb.com/api/v1/projects/{project_id}/executions/{execution_id}/interrupt",
    params={"workspace_id": workspace_id},
    headers={"Authorization": f"Bearer {api_key}"},
    json={"step_number": 12},
)

La respuesta se asemeja a la siguiente salida:

{
  "execution_id": "string",
  "interrupted": true,
  "interrupted_steps": [ 12 ],
  "pending": false,
  "outcome": "aborted"
}

El campo outcome describe el resultado de la solicitud de interrupción y devuelve uno de los siguientes valores:

La interrupción de una llamada es idempotente y no altera el estado de ejecución. Si se interrumpen todas las llamadas de un paso, el agente finaliza ese turno en lugar de volver a intentar las llamadas. Si se interrumpen solo algunas de las llamadas de un paso, el agente continúa con normalidad.

Marcar una sesión como finalizada por tu agente.

Una sesión mantiene su entorno aislado de agente y su entorno aislado de herramientas hasta que expire el tiempo de espera por inactividad. Si marca una sesión como finalizada, su agente puede liberar ese procesamiento inmediatamente en lugar de esperar a que expire el tiempo de espera.

Seleccione la pestaña correspondiente a su idioma preferido para ver un ejemplo de cómo marcar una sesión como finalizada desde su agente:

status = app.finish_session()

const status = app.finishSession();

El turno actual continúa ejecutándose y devuelve su resultado. Una vez finalizado el turno, el motor del agente Atlas cancela cualquier ejecución de subagentes activa y libera los pods de la sesión.

El método devuelve uno de los siguientes valores:

Este método no genera ningún error ni lanza ninguna excepción cuando no hay ninguna sesión que finalizar.

Un turno que se suspende para revisión humana o falla conserva sus recursos para que puedas reanudarlo y diagnosticarlo. En ese caso, la sesión vuelve al tiempo de espera por inactividad. Para obtener más información sobre los tiempos de espera por inactividad, consulta Errores de Pool lleno.

Sintaxis del comando

agentengine invoke [message] [flags]
agentengine invoke --file <path> [flags]

La siguiente tabla describe las banderas disponibles:

Ejemplos

El siguiente comando invoca al agente con un único mensaje:

agentengine invoke "What can you do?"

El siguiente comando transmite la respuesta del agente a medida que se produce:

agentengine invoke --stream "Draft a release note"

El siguiente comando reanuda o continúa una sesión con nombre:

agentengine invoke --session my-session "Follow up question"

El siguiente comando lee un mensaje de un archivo y genera JSON sin procesar:

cat prompt.txt | agentengine invoke --json

Comandos de carga útil interactivos

Al ejecutar agentengine invoke en modo interactivo, puede gestionar la carga útil entre turnos utilizando uno de los siguientes comandos:

Revisión interactiva de HITL

Cuando un agente se suspende para revisión humana (HITL) en modo interactivo, la interfaz de línea de comandos (CLI) muestra el contexto de suspensión y solicita una decisión en línea. Para saber cómo la CLI presenta la solicitud de revisión y cómo reanudar la ejecución, consulte la guía "Uso de la CLI en la revisión humana".