调用代理

调用您的代理

要调用代理，请向 /api/v1/projects/{project_id}/workspaces/{workspace_id}/invoke API端点发送 POST请求。响应返回执行结果和执行状态。平台在 X-Session-ID 响应标头中返回会话ID 。

以下 curl示例就使用了这些占位符：

• $API_KEY：您的Atlas Agent Engine API密钥

• $PROJECT_ID：您的项目ID

• $WORKSPACE_ID：您的工作区ID

选择首选语言对应的标签页，查看示例请求：

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()

响应输出类似于以下内容：

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

如果暂停执行以供人工查看，则响应还包括 suspend_reason 和 suspend_context 字段。要学习；了解更多信息，请参阅《人在环》指南中的暂停、查看和恢复生命周期。

流式传输助手的输出

要在代理生成后流输出，请向 /api/v1/projects/{project_id}/workspaces/{workspace_id}/invokeStream API端点发送 POST请求。平台以服务器发送事件 (SSE) 帧流的形式返回响应。流保持连接打开状态，直到运行完成或失败。

每个 SSE 框架都以 data: 前缀开头，并包含一个JSON对象。以下示例显示了流媒体帧的格式：

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

帧可以包含以下字段：

其他端点

Atlas Agent Engine 还公开以下API端点，用于流媒体、轮询、恢复和停止执行：

每个 executions/** 端点都需要 workspace_id查询参数。网关使用此值将请求路由到所属工作区的编排引擎。

执行状态生命周期

执行会在 pending、running、completed 或 error 状态之间切换。

如果执行暂停以进行人工查看，则它会在完成之前经历其他状态。要学习；了解暂停和恢复生命周期，请参阅“人在环”指南中的暂停、查看和恢复生命周期。

如果取消执行，它将进入 cancelled 状态。此状态不同于 completed 和 error，因此API和用户界面客户端可以区分故意停止的执行和已完成或失败的执行。要学习；了解更多信息，请参阅取消会话。

池已满错误

Atlas Agent Engine 不会自动伸缩代理部署。 agent.yaml文件中的 scaling.replicas字段设置固定的沙箱数量，每个会话在其生命周期内保留一个代理沙箱和一个工具沙箱。因此，该字段设置部署可以同时提供服务的会话数。

scaling.replicas字段接受从 1 到 512 之间的值，如果省略，则默认为 4。当每个沙箱都被保留时，新的调用请求将失败并显示 pool full 错误。

512 并发沙箱限制适用于业务流程引擎，其范围仅限于一个项目，并且可以为多个代理提供服务。项目中所有代理的 scaling.replicas 值计入相同的上限。要运行的沙箱数量超过一个项目允许的数量，请将代理分布在多个项目中。

为防止调用请求耗尽池，请在请求之间重复使用会话 ID。股票会话ID的请求会重复使用一个预留，但省略会话ID的请求会使用一对新的沙箱。会话ID 的长度必须为 1 到 128 个字符，可以包含字母、数字、下划线 (_) 和连字符 (-)。在 agentengine invoke 命令的 --session 选项或API请求的 X-Session-ID 标头中传递会话ID 。

如果您的调用请求需要按会话隔离性，则无法重复使用会话ID。要同时为更多会话提供服务，请增加 scaling.replicas 值，或减少 scaling.agent_idle_ttl_seconds 和 scaling.tool_idle_ttl_seconds 值，以便空闲会话更快发布其沙箱。

由于Atlas助手引擎会在构建时对 scaling 值进行快照，因此您必须再次构建并部署代理才能使更改生效。要学习；了解有关这些字段的更多信息，请参阅代理合同参考。要查看公开预览版期间应用的所有限制，请参阅MongoDB Atlas助手引擎限制。

如何操作

在调用或恢复请求， API Gateway 通过执行以下步骤处理带有前缀 X-Mdb-Agent-Engine-Custom- 的HTTP 头部：

1. API网关提取标头。

2. 网关去掉前缀，并将标头名称小写。示例，X-Mdb-Agent-Engine-Custom-Authorization 变为 authorization。

3. 网关将标头作为字典转发给代理。

标头通过执行管道在内存中转发，从不持久保存到数据库，并在执行完成时被管道丢弃。

发送自定义标头

将 X-Mdb-Agent-Engine-Custom- 前缀标头添加到您的调用请求。 API网关会在代理收到前缀之前将其去掉。

以下示例使用与调用API示例相同的占位符。它们还为您要转发的自定义标头使用占位符。

选择首选语言的标签页，查看带有自定义标头的调用请求：

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!"},
)

运行上述代码后，代理会收到以下字典：

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

读取代理中的标头

使用任何工具内 agent_engine_runner_shared 的 get_current_custom_headers() 方法访问权限API网关转发给代理的标头。以下Python代码展示了如何使用 get_current_custom_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

get_current_custom_headers() 方法返回一个 dict[str, str]。如果网关未发送任何自定义标头，该方法将返回一个空字典。

恢复请求

转发自定义标头也适用于恢复请求。由于Atlas助手引擎不会保留自定义标头，因此在恢复暂停的执行时，您必须重新发送相同的 X-Mdb-Agent-Engine-Custom- 标头。有关转发自定义标头的恢复请求示例，请参阅《Human-in-the-Loop》指南中的“使用API” 。

取消会话

要取消正在进行的执行，请向 /api/v1/projects/{project_id}/executions/{execution_id}/cancel 端点发送 POST请求并设立workspace_id查询参数。该请求不带正文。

选择您的首选语言的标签页，查看取消执行的示例：

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}"},
)

响应输出类似于以下内容：

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

cancelled字段报告此请求是否将执行状态设立为 cancelled。对于 cancelled 执行，字段值为 true；当请求由于已达到最终状态而未转换执行时，字段值为 false，包括先前请求中的 cancelled。当字段值为 false 时，status字段会报告记录的终端状态。

取消执行时， Atlas助手引擎会执行以下操作：

• 取消正在进行的工具或 LLM 调用，拆除会话的代理沙箱和工具沙箱，并释放容量插槽。新的执行可以重复使用该槽。

• 取消同一会话上的所有其他实时执行，包括作为目标执行子项的深度代理和代理到代理执行。

• 结束打开的响应流，而不是让流保持打开状态直到超时。

• 对取消之前会话所累积的运行时间进行计费。

在 Playground 中停止运行

您还可以从 Playground用户界面停止运行，而不是调用 cancel API端点。从 Playground 停止运行与取消会话具有相同的效果。要学习；了解更多信息，请参阅取消会话。

要从 Playground 停止运行，请执行以下步骤：

中断工具或 LLM 调用

中断工具或 LLM 调用仅会停止该调用。会话保持活动状态，代理从中断的结果中继续运行。当单个呼叫卡住或不需要并且您不想取消整个会话时，请中断呼叫。

要中断调用，请向 /api/v1/projects/{project_id}/executions/{execution_id}/interrupt API端点发送 POST请求。该请求采用以下参数：

选择您的首选语言的标签页，查看中断工具或 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},
)

响应输出类似于以下内容：

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

outcome字段描述中断请求的结果并返回以下值之一：

中断调用是幂等的，不会更改执行状态。如果您中断步骤中的每个调用，则代理会结束该回合而不是重试调用。如果在一个步骤中仅中断部分调用，代理将正常继续。

通过代理将会话标记为已完成

会话会保留其代理沙箱和工具沙箱，直到空闲超时时间到期。如果将会话标记为已完成，则代理可以立即发布该计算，而不是等待超时。

选择首选语言的标签页，查看代理将会话标记为已完成的示例：

status = app.finish_session()

const status = app.finishSession();

当前回合继续运行并返回结果。轮次完成后， Atlas助手引擎会取消任何活动的子助手执行并释放会话的 Pod。

该方法返回以下值之一：

当没有要完成的会话时，该方法不会引发错误或异常。

暂停以供人工查看或失败的轮次会保留其资源，以便您可以恢复和诊断它。该会话回退到空闲超时时间。要学习；了解有关空闲超时的更多信息，请参阅池已满错误。

命令语法

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

下表描述了可用标志：

示例

以下命令使用一条消息调用代理：

agentengine invoke "What can you do?"

以下命令在生成代理响应时流式传输响应：

agentengine invoke --stream "Draft a release note"

以下命令可恢复或继续命名会话：

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

以下命令从文件中读取消息并输出原始JSON：

cat prompt.txt | agentengine invoke --json

交互式有效负载命令

在交互模式下运行agentengine invoke 时，您可以使用以下命令之一管理轮次之间的有效负载：

交互式 HITL 审核

当代理在交互模式下暂停以进行人工参与环路 (HITL)查看， CLI会打印暂停上下文并提示您做出内联决策。要学习；了解CLI如何显示查看提示以及如何恢复执行，请参阅《人机交互指南》中的使用CLI 。