エージェントの呼び出し

エージェントを呼び出す

エージェントを呼び出すには、/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とUIクライアントは、意図的に停止された実行と、完了または失敗した実行を区別できます。詳細については、「 セッションのキャンセル 」を参照してください。

プール フル エラー

Atlas Agent Engine はエージェントの配置をオートスケールしません。 agent.yamlファイルの scaling.replicasフィールドは固定のサンドボックス数を設定し、各セッションはその有効期間中に 1 つのエージェントサンドボックスと 1 つのツール サンドボックスを予約します。その結果、このフィールドは配置が同時に処理できるセッション数を設定します。

scaling.replicasフィールドは1 から 512 までの値を受け入れ、省略した場合はデフォルトで 4 になります。すべてのサンドボックスが予約されると、新しい呼び出しリクエストはpool full エラーで失敗します。

512 の同時サンドボックス制限は、スコープがプロジェクトに限定され、複数のエージェントをサポートできるオーケストレーション エンジンに適用されます。プロジェクト内のすべてのエージェントの scaling.replicas 値は同じ上限にカウントされます。 1 つのプロジェクトで許可される複数のサンドボックスを実行するには、エージェントを複数のプロジェクトに分散します。

プールが枯渇するリクエストを呼び出すには、リクエスト全体でセッション ID を再利用します。セッションIDを共有するリクエストは 1 つの予約を再利用しますが、セッションIDを省略するリクエストでは新しいサンドボックスのペアが使用されます。セッションID は1 から 128 文字の長さで、文字、数字、アンダースコア（_）、ハイフン（-）を含めることができます。セッションID は、agentengine invoke コマンドの --session オプション、またはAPIリクエストの X-Session-ID ヘッダーで渡します。

呼び出しリクエストに セッションごとの分離が必要な場合は、 セッションID を再利用することはできません。より多くのセッションを同時に処理するには、scaling.replicas の値を増やすか、scaling.agent_idle_ttl_seconds と scaling.tool_idle_ttl_seconds の値を減らして、アイドル状態のセッションがサンドボックスをより早く解放してください。

Atlas Agent Enginescaling はビルド時に の値をスナップショットするため、変更を有効にするにはエージェントを再度ビルドして配置する必要があります。これらのフィールドの詳細については、「 エージェント契約リファレンス 」を参照してください。パブリック プレビュー中に適用されるすべての制限を確認するには、 「 MongoDB Atlas Agent の制限 」を参照してください。

仕組み

呼び出しまたは再開リクエストにおいて、 API Gateway は次の手順を実行して、プレフィックス X-Mdb-Agent-Engine-Custom- を持つHTTPヘッダーを処理します。

1. API Gateway は ヘッダーを抽出します。

2. ゲートウェイはプレフィックスを削除し、ヘッダー名を小文字にします。例、X-Mdb-Agent-Engine-Custom-Authorization は authorization になります。

3. ゲートウェイはヘッダーを辞書としてエージェントに転送します。

ヘッダーは 実行パイプラインを介してメモリ内に転送され、データベースに永続化されることはなく、実行が完了するとパイプラインによって破棄されます。

カスタム ヘッダーの送信

X-Mdb-Agent-Engine-Custom- のプレフィックス付きヘッダーを 呼び出しリクエストに追加します。 API Gateway は、エージェントがプレフィックスを受信する前にプレフィックスを削除します。

次の例では、呼び出し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 Gateway がエージェントに転送したヘッダーにアクセスします。次の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 Agent はカスタム ヘッダーを保持しないため、中断された実行を再開するときに同じ ヘッダーを再送信する必要があります。カスタムX-Mdb-Agent-Engine-Custom- ヘッダーを転送する再開リクエストの例については、 ループ内の人間によるガイドの「 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 であり、リクエストがすでにターミナルステータス（以前のリクエストの cancelled を含む）に達していて実行を移行しなかった場合は false です。フィールド値が false の場合、代わりに statusフィールドは記録されたターミナルステータスを報告します。

実行をキャンセルすると、Atlas Agent エンジンは次の処理を実行します。

• 進行中のツールまたは LM の呼び出しをキャンセルし、セッションのエージェントサンドボックスとツール サンドボックスを破棄して、キャパシティースロットを解放します。新たに実行するとスロットは再利用できます。

• ターゲット実行の子であるディープエージェントやエージェント間実行など、同じセッション上の他のすべてのライブ実行をキャンセルします。

• タイムアウトするまでストリームを開いたままにするのではなく、開いている応答ストリームを終了します。

• セッションがキャンセルされるまで、セッションが発生したランタイムを請求します。

プレイグラウンドでの実行の停止

APIエンドポイントを呼び出す代わりに、プレイグラウンドUIから実行を停止することもできます。 Playground から実行を停止すると、セッションがキャンセルされるのと同じ効果があります。詳細については、「 セッションのキャンセルcancel 」を参照してください。

プレイグラウンドから実行を停止するには、次の手順を実行します。

ツールまたは LM 呼び出しの中断

ツールまたは LM 呼び出しを中断すると、その呼び出しのみが停止します。セッションはアクティブのままとなり、エージェントは中断された結果から実行を続行します。 1 回の呼び出しが停止したり不要で、セッション全体をキャンセルしたくない場合は、呼び出しを中断します。

呼び出しを中断するには、/api/v1/projects/{project_id}/executions/{execution_id}/interrupt APIエンドポイントに POSTリクエストを送信します。リクエストは、次のパラメーターを取ります。

ツールまたは LVM 呼び出しを中断する例を確認するには、ご希望言語のタブを選択します。

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 Agent Engine はライブでのサブエージェントの実行をキャンセルし、セッションのポッドを解放します。

このメソッドは、次のいずれかの値を返します。

メソッドは、終了するセッションがない場合でも、エラーを発生させたり例外をスローしたりしません。

人間のレビューのために一時停止または失敗したタームは、再開して診断できるようにリソースを保持します。そのセッションはアイドル タイムアウトに戻ります。アイドル タイムアウトの詳細については、「 プールがフル エラー 」を参照してください。

コマンド構文

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

次の表では、使用可能なフラグについて説明しています。

例

次のコマンドは、1 つのメッセージを使用してエージェントを呼び出します。

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 の使用 」を参照してください。