invoke-agent

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!-- Tab options on this page. Append to the .md URL to filter: ?tabs=<id,...> select specific tabs (e.g. ?tabs=nodejs,shell) ?allTabs=true include every tab (no param) default: one tab per tabset

Available tabs: other tabs: invoke-curl, invoke-python, custom-headers-curl, custom-headers-python, cancel-curl, cancel-python, interrupt-curl, interrupt-python, finish-session-python, finish-session-typescript -->

Invoke an Agent

MongoDB Atlas Agent Engine is in Public Preview and intended for evaluation and prototyping purposes only. We do not recommend production deployments during preview and expect to communicate breaking changes with you periodically. To learn more about preview feature considerations, see Preview Features.

Overview

In this guide, you can learn how to invoke a deployed agent on the MongoDB Atlas Agent Engine. The guide shows how to call the invocation API, invoke an agent from the CLI, forward custom headers to your agent, and resume suspended executions.

To create the service account credentials that these requests use, see [Manage Service Account Credentials](https://www.mongodb.com/docs/agentengine/api-keys-service-accounts.md#std-label-agent-engine-api-keys-service-accounts. To keep your integration compatible with future API versions, see [Pin an API Contract.](https://www.mongodb.com/docs/agentengine/reference/limitations.md#std-label-agent-engine-api-contract-pinning

Invocation API

The invocation API is the API that clients use to call a deployed agent. The Atlas Agent Engine exposes these endpoints on behalf of the agent, so your agent code does not need to define any HTTP routes or start a web server.

Invoke Your Agent

To invoke an agent, send a POST request to the /api/v1/projects/{project_id}/workspaces/{workspace_id}/invoke API endpoint. The response returns the execution result and the execution status. The platform returns the session ID in the X-Session-ID response header.

The following curl example uses these placeholders:

• $ACCESS_TOKEN: Your service account access token

• $PROJECT_ID: Your project ID

• $WORKSPACE_ID: Your workspace ID

Select the tab for your preferred language to view a sample invoke request:

cURL

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

The response resembles the following output:

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

If the execution suspends for human review, the response also includes suspend_reason and suspend_context fields. To learn more, see [Suspend, Review, and Resume Lifecycle](https://www.mongodb.com/docs/agentengine/deploy/human-in-the-loop.md#std-label-agent-engine-hitl-lifecycle in the Human-in-the-Loop guide.

Stream Your Agent's Output

To stream an agent's output as it's produced, send a POST request to the /api/v1/projects/{project_id}/workspaces/{workspace_id}/invokeStream API endpoint. The platform returns the response as a stream of Server-Sent Events (SSE) frames. The stream keeps the connection open until the run completes or fails.

Each SSE frame begins with the data: prefix and contains a single JSON object. The following example shows the format of a streaming frame:

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

A frame can include the following fields:

Chunk Types

The following table describes the chunk types that a stream can carry:

If the run fails, the stream sends an error chunk that includes the error message. Then, the stream closes.

Custom Output for Opted-In Agents

If you set the features.use_custom_parser flag to true in your agent.yaml file, the stream carries only the custom events that the agent's output parser or its emit_custom_event() calls produce. The platform forwards each custom event as a single data: frame, so the frame contains exactly the JSON object that the agent emitted. The stream does not include the standard chunks such as text, step, or done frames, and it closes when the run completes.

The platform delivers custom events only on the invokeStream endpoint. The synchronous invoke endpoint returns the agent's final output instead.

When this feature flag is not enabled, the stream uses the chunk format described earlier in this section. The stream does not deliver custom events, and an emit_custom_event() call in agent code raises an error.

Other Endpoints

The Atlas Agent Engine also exposes the following API endpoints for streaming, polling, resuming, and stopping executions:

Every executions/** endpoint requires the workspace_id query parameter. The gateway uses this value to route the request to the owning workspace's Orchestration Engine.

Note:

Cancelling or interrupting an execution that already reached a terminal status is idempotent. The request response reports that the request made no change.

Execution Status Lifecycle

An execution moves through the statuses pending, running, and then completed or error.

If the execution suspends for human review, it moves through additional statuses before it completes. To learn about the suspend and resume lifecycle, see [Suspend, Review, and Resume Lifecycle](https://www.mongodb.com/docs/agentengine/deploy/human-in-the-loop.md#std-label-agent-engine-hitl-lifecycle in the Human-in-the-Loop guide.

If you cancel an execution, it reaches the cancelled status. This status is distinct from completed and error, so API and UI clients can distinguish a deliberately stopped execution from one that finished or failed. To learn more, see [Cancel a Session.](https://www.mongodb.com/docs/agentengine/deploy/invoke-agent.md#std-label-agent-engine-invoke-agent-cancel

Pool-Full Errors

The Atlas Agent Engine does not autoscale agent deployments. The scaling.replicas field in the agent.yaml file sets a fixed sandbox count, and each session reserves one agent sandbox and one tool sandbox for its lifetime. As a result, this field sets the number of sessions that a deployment can serve concurrently.

The scaling.replicas field accepts a value from 1 to 512 and defaults to 4 when you omit it. When every sandbox is reserved, a new invoke request fails with a pool full error.

The 512 concurrent sandbox limit applies to the Orchestration Engine, which is scoped to a project and can serve more than one agent. The scaling.replicas values of all agents in a project count toward the same ceiling. To run more sandboxes than one project allows, distribute your agents across multiple projects.

The Orchestration Engine also limits the number of concurrent requests that it can serve. As a result, a project might not be able to run 512 agents at the same time. To learn about this limit, see [Orchestration Engine Capacity.](https://www.mongodb.com/docs/agentengine/reference/limitations.md#std-label-agent-engine-limitations-oe-capacity

If you have capacity issues, choose one of the following options:

A session ID must be 1 to 128 characters long and can contain letters, numbers, underscores (_), and hyphens (-). Pass the session ID in the --session option of the agentengine invoke command, or in the X-Session-ID header of an API request.

Because the Atlas Agent Engine snapshots scaling values at build time, you must build and deploy the agent again for a change to take effect. To learn more about these fields, see [Agent Contract Reference](https://www.mongodb.com/docs/agentengine/reference/agent-contract.md#std-label-agent-engine-agent-contract. To review all limitations that apply during Public Preview, see [MongoDB Atlas Agent Engine Limitations.](https://www.mongodb.com/docs/agentengine/reference/limitations.md#std-label-agent-engine-limitations

Forward Custom Headers

In this section, you can learn how to pass custom HTTP headers, such as user IDs, from your application to an agent running on the Atlas Agent Engine. Your agent can then read those headers at runtime by using the get_current_custom_headers() method.

How It Works

On an invoke or resume request, the API Gateway processes HTTP headers with the prefix X-Mdb-Agent-Engine-Custom- by performing the following steps:

1. The API Gateway extracts the header.

2. The gateway strips the prefix and makes the header name lowercase. For example, X-Mdb-Agent-Engine-Custom-Authorization becomes authorization.

3. The gateway forwards the headers to the agent as a dictionary.

Headers are forwarded in-memory through the execution pipeline, never persisted to the database, and discarded by the pipeline when the execution completes.

Note:

The Atlas Agent Engine does not persist custom headers. Your application must resend them on every request, including resume requests.

Limits

The following table shows the limits for custom headers:

Send Custom Headers

Add X-Mdb-Agent-Engine-Custom- prefixed headers to your invoke request. The API Gateway strips the prefix before the agent receives them.

The following examples use the same placeholders as the [invocation API examples](https://www.mongodb.com/docs/agentengine/deploy/invoke-agent.md#std-label-agent-engine-invocation-api. They also use placeholders for the custom headers that you want to forward.

Select the tab for your preferred language to see an example invoke request with custom headers:

cURL

curl -s "https://agentengine.mongodb.com/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/invoke" \
  -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -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!"}'

The agent receives the following dictionary after you run the preceding code:

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

Read Headers in Your Agent

Use the get_current_custom_headers() method from agent_engine_runner_shared inside any tool to access the headers that the API Gateway forwarded to the agent. The following Python code shows how to use get_current_custom_headers() to access the forwarded headers:

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

The get_current_custom_headers() method returns a dict[str, str]. If the gateway did not send any custom headers, the method returns an empty dictionary.

Resume Requests

Forwarding custom headers also works with resume requests. Because the Atlas Agent Engine does not persist custom headers, you must resend the same X-Mdb-Agent-Engine-Custom- headers when you resume a suspended execution. For an example resume request that forwards custom headers, see [Use the API](https://www.mongodb.com/docs/agentengine/deploy/human-in-the-loop.md#std-label-agent-engine-hitl-resume-api in the Human-in-the-Loop guide.

Stop a Running Agent

Cancelling a request from your client closes only your side of the connection. The execution keeps running on the server until you stop it through the Atlas Agent Engine.

The Atlas Agent Engine provides the following ways to stop work that is already running:

• Cancel the session to end the execution and release its compute. To learn more, see [Cancel a Session.](https://www.mongodb.com/docs/agentengine/deploy/invoke-agent.md#std-label-agent-engine-invoke-agent-cancel

• Stop the run from the Playground UI. To learn more, see [Stop a Run in the Playground.](https://www.mongodb.com/docs/agentengine/deploy/invoke-agent.md#std-label-agent-engine-invoke-agent-stop-playground

• Interrupt a single in-progress tool or LLM call and let the agent continue the run. To learn more, see [Interrupt a Tool or LLM Call.](https://www.mongodb.com/docs/agentengine/deploy/invoke-agent.md#std-label-agent-engine-invoke-agent-interrupt

• Mark the session finished from your agent code when the agent does not need it anymore. To learn more, see [Mark a Session Finished from Your Agent.](https://www.mongodb.com/docs/agentengine/deploy/invoke-agent.md#std-label-agent-engine-invoke-agent-finish-session

Cancel a Session

To cancel an in-progress execution, send a POST request to the /api/v1/projects/{project_id}/executions/{execution_id}/cancel endpoint and set the workspace_id query parameter. The request does not take a body.

Select the tab for your preferred language to see an example of cancelling an execution:

cURL

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

The response resembles the following output:

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

The cancelled field reports whether this request set the execution status to cancelled. The field value is true for a cancelled execution and false when the request did not transition the execution because it had already reached a terminal status, including cancelled from an earlier request. When the field value is false, the status field reports the recorded terminal status instead.

When you cancel an execution, the Atlas Agent Engine does the following:

• Cancels in-progress tool or LLM calls and tears down the session's agent sandbox and tool sandbox, and releases the capacity slot. A new execution can reuse the slot.

• Cancels every other live execution on the same session, including deep-agent and agent-to-agent executions that are children of the target execution.

• Ends an open response stream instead of leaving the stream open until it times out.

• Bills the runtime that the session accrued until cancellation.

Note:

You cannot resume a cancelled execution. To send another message to the agent, invoke the agent again. The request starts a new execution instead of resuming the cancelled one.

Stop a Run in the Playground

You can also stop a run from the Playground UI instead of calling the cancel API endpoint. Stopping a run from the Playground has the same effect as cancelling the session. To learn more, see [Cancel a Session.](https://www.mongodb.com/docs/agentengine/deploy/invoke-agent.md#std-label-agent-engine-invoke-agent-cancel

To stop a run from the Playground, perform the following steps:

1. Open the Playground.

Go to the playground UI URL for your deployment.

1. Click the stop button.

While the run is in progress, click the red stop button in the chat bar to open the confirmation dialog.

1. Confirm that you want to stop the run.

In the dialog, click Stop run. This stops the run and releases the session's compute resources.

Interrupt a Tool or LLM Call

Interrupting a tool or LLM call stops that call only. The session stays active and the agent continues its run from the interrupted result. Interrupt a call when a single call is stuck or unwanted and you don't want to cancel the whole session.

To interrupt a call, send a POST request to the /api/v1/projects/{project_id}/executions/{execution_id}/interrupt API endpoint. The request takes the following parameters:

Select the tab for your preferred language to see an example of interrupting a tool or LLM call:

cURL

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

The response resembles the following output:

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

The outcome field describes the result of the interrupt request and returns one of the following values:

Interrupting a call is idempotent and does not change the execution status. If you interrupt every call in a step, the agent ends that turn instead of retrying the calls. If you interrupt only some of the calls in a step, the agent continues normally.

Tool Call Interruption Support

LLM calls and other I/O-bound calls are always interruptible. Support for tool call interruption depends on the language and tool type, and the following behavior applies:

• In Python, tools that you write as asynchronous functions are interruptible by default. The runtime raises a CancelledError inside the tool body when the tool reaches its next await expression. During cleanup, if your tool handles CancelledError exceptions, raise the error again when the cleanup completes. A tool that continues running after the CancelledError is still reported as interrupted, but the tool runs longer than necessary.

• In Python, tools that you write as synchronous functions run on a worker thread. The Atlas Agent Engine cannot interrupt these tools while they run, so the tool reports that it cannot be stopped and runs to completion.

• In TypeScript, tools are interruptible only when you update them to support interruption. Pass the tool body to the withCallInterruptSupport() function when you register the tool, and call the getCallAbortSignal().throwIfAborted() function at each point in a loop where the tool can safely stop. Without the withCallInterruptSupport() function, the tool reports that it cannot be stopped. If the tool is registered with the withCallInterruptSupport() function but does not check the signal, the call is still reported as stopped, and the run continues. However, the tool body keeps running until it finishes.

When you stop a single call, the Atlas Agent Engine displays one of the following statuses in the UI:

Example

The following example shows a TypeScript tool that supports interruption:

import {
  withCallInterruptSupport,
  getCallAbortSignal,
} from "@mongodb-js/agent-engine-sdk-langgraph";

app.tool()(
  withCallInterruptSupport(async function slowCheck(args) {
    for (const batch of batches) {
      // Stop here if the call was interrupted
      getCallAbortSignal()?.throwIfAborted();
      await processBatch(batch);
    }
  })
);

When you stop a call, the model decides what happens next and might end the turn itself. To instruct the agent to skip the stopped call and continue the remaining work, add that instruction to the system prompt in your agent code.

Mark a Session Finished from Your Agent

A session holds its agent sandbox and tool sandbox until the idle timeout expires. If you mark a session as finished, your agent can release that compute immediately instead of waiting for the timeout.

Select the tab for your preferred language to see an example of marking a session finished from your agent:

Python

status = app.finish_session()

The current turn keeps running and returns its result. After the turn completes, the Atlas Agent Engine cancels any live sub-agent executions and releases the session's pods.

The method returns one of the following values:

The method does not raise an error or throw an exception when there is no session to finish.

A turn that suspends for human review or fails keeps its resources so that you can resume and diagnose it. That session falls back to the idle timeout. To learn more about idle timeouts, see [Pool-Full Errors.](https://www.mongodb.com/docs/agentengine/deploy/invoke-agent.md#std-label-agent-engine-invoke-pool-full

Invoke an Agent from the CLI

The agentengine invoke command invokes a deployed agent from the terminal without writing any HTTP client code. It reads the workspace from the current directory's .agentengine/state.json file by default.

If you run the command without a message in an interactive terminal, it starts a streaming chat session and reuses the returned session ID across turns. In this interactive mode, the CLI automatically presents an inline review prompt when the agent suspends invocation for human-in-the-loop (HITL) review.

Command Syntax

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

The following table describes the available flags:

Examples

The following command invokes the agent with a single message:

agentengine invoke "What can you do?"

The following command streams the agent's response as it is produced:

agentengine invoke --stream "Draft a release note"

The following command resumes or continues a named session:

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

The following command reads a message from a file and outputs raw JSON:

cat prompt.txt | agentengine invoke --json

Interactive Payload Commands

When running agentengine invoke in interactive mode, you can manage the payload between turns by using one of the following commands:

Interactive HITL Review

When an agent suspends for human-in-the-loop (HITL) review in interactive mode, the CLI prints the suspend context and prompts you for a decision inline. To learn how the CLI presents the review prompt and how to resume the execution, see [Use the CLI](https://www.mongodb.com/docs/agentengine/deploy/human-in-the-loop.md#std-label-agent-engine-hitl-resume-cli in the Human-in-the-Loop guide.

Next Steps

After you invoke an agent, you can monitor your agent's performance and activity. To learn more, see the [Monitor](https://www.mongodb.com/docs/agentengine/manage/monitor.md#std-label-agent-engine-monitor guide.