에이전트 호출

에이전트 호출

에이전트 호출하려면 /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 필드도 포함됩니다. 자세한 학습 은 휴먼인더루프(Human-in-the-Loop) 가이드 의 수명 주기 일시 중단, 검토 및 재개를 참조하세요.

에이전트 출력 스트리밍

에이전트의 출력이 생성될 때 스트림 하려면 /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 상태를 차례로 이동합니다.

사람의 검토 위해 실행이 일시 중단되면 완료되기 전에 추가 상태를 거치게 됩니다. 일시 중단 및 재개 수명 주기에 대해 학습 휴먼 인 더 루프(Human-in-the-Loop) 가이드 의 수명 주기 일시 중단, 검토 및 재개를 참조하세요.

실행을 취소하면 cancelled 상태에 도달합니다. 이 상태는 completed 및 error와 구별되므로 API 및 UI 클라이언트는 의도적으로 중지된 실행과 완료되거나 실패한 실행을 구분할 수 있습니다. 자세히 학습 세션 취소를 참조하세요.

풀 전체 오류

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 Agent Engine은 빌드 시 scaling 값을 스냅샷하므로 변경 사항을 적용하려면 에이전트 다시 빌드 하고 배포 해야 합니다. 이러한 필드에 대해 자세히 학습 에이전트 계약 참조를 확인하세요. 공개 미리 보기 중에 적용 모든 제한 사항을 검토 하려면 MongoDB Atlas Agent 엔진 제한 사항을 참조하세요.

작동 방법

호출 또는 재개 요청 에서 API 게이트웨이는 다음 단계를 수행하여 접두사가 X-Mdb-Agent-Engine-Custom-인 HTTP headers 처리합니다.

1. API 게이트웨이가 헤더를 추출합니다.

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 게이트웨이가 에이전트 에 전달한 헤더에 액세스 합니다. 다음 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 Engine은 사용자 지정 헤더를 유지하지 않으므로 일시 중단된 실행을 재개할 때 동일한 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이고, 요청 이전 요청 의 cancelled를 포함하여 이미 터미널 상태에 도달했기 때문에 실행을 전환하지 않은 경우에는 false입니다. 필드 값이 false인 경우 status 필드 대신 기록된 터미널 상태를 보고합니다.

실행을 취소하면 Atlas Agent Engine이 다음을 수행합니다.

• 진행 중인 도구 또는 LLM 호출을 취소하고 세션의 에이전트 샌드박스 및 도구 샌드박스를 해체한 다음 용량 슬롯을 해제합니다. 새 실행은 슬롯을 재사용할 수 있습니다.

• 대상 실행의 하위 항목인 딥 에이전트 및 에이전트 간 실행을 포함하여 동일한 세션에서 다른 모든 실시간 실행을 취소합니다.

• 시간이 초과될 때까지 스트림 열린 상태로 두는 대신 열린 응답 스트림 종료합니다.

• 취소할 때까지 세션이 발생한 런타임을 청구합니다.

플레이그라운드에서 실행 중지

cancel API 엔드포인트를 호출하는 대신 플레이그라운드 UI 에서 실행 중지할 수도 있습니다. 플레이그라운드에서 실행 중지하면 세션을 취소하는 것과 동일한 효과가 있습니다. 자세히 학습 세션 취소를 참조하세요.

플레이그라운드에서 실행 중지하려면 다음 단계를 수행하세요.

도구 또는 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 Agent Engine이 모든 라이브 하위 에이전트 실행을 취소하고 세션의 파드를 해제합니다.

이 메서드는 다음 값 중 하나를 반환합니다.

완료해야 할 세션이 없을 때 메서드는 오류를 발생시키거나 예외를 발생시키지 않습니다.

인적 검토 위해 일시 중단되거나 실패한 턴은 재개하고 진단할 수 있도록 리소스를 유지합니다. 해당 세션은 유휴 시간 제한으로 돌아갑니다. 유휴 시간 제한에 대해 자세히 학습 풀 전체 오류를 참조하세요.

명령 구문

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(Human-in-the-Loop) 검토 위해 일시 중단되면 CLI 일시 중단 컨텍스트를 출력하고 인라인으로 결정을 묻는 메시지를 표시합니다. CLI 검토 프롬프트를 표시하는 방법과 실행을 다시 시작하는 방법을 학습 휴먼인더루프(Human-in-the-Loop) 가이드 의 CLI 사용을 참조하세요.