본문 바로가기
WIKI 기술 지식 베이스

Execute Agent API

원문 보기 위키 갱신

출처: 문서

본문

에이전트 실행 API

2.13부터 도입 {: .label .label-purple }

에이전트를 실행하면 그 에이전트에 구성된 도구들이 실행돼요. async 쿼리 파라미터를 true로 설정하면 에이전트를 비동기로 실행할 수 있어요.

통합 등록 방식으로 만든 에이전트는 일반 텍스트, 멀티모달 콘텐츠, 메시지 기반 대화를 받을 수 있는 표준화된 input 필드를 지원해요. 이를 위해서는 plugins.ml_commons.unified_agent_api_enabled 클러스터 설정이 활성화되어 있어야 해요. {: .note}

엔드포인트

POST /_plugins/_ml/agents/{agent_id}/_execute

쿼리 파라미터

사용할 수 있는 쿼리 파라미터는 다음 표와 같아요.

파라미터 | 데이터 타입 | 필수/선택 | 설명 :--- | :--- | :--- async | Boolean | 선택 | true이면 에이전트를 비동기로 실행하고 실행 추적용 task_id를 반환해요. 태스크 상태를 확인하려면 ML 태스크 조회 API를 사용하세요. 기본값은 false예요.

요청 본문 필드

사용할 수 있는 요청 필드는 다음 표와 같아요.

필드 데이터 타입 필수/선택 설명
parameters Object 선택 에이전트에 필요한 파라미터예요. 등록 때 설정한 에이전트 파라미터는 이 필드로 재정의할 수 있어요. 일반 등록 방식과 함께 사용하세요.
parameters.question String 선택 에이전트에게 던질 질문이에요. 일반 등록 방식과 함께 사용하세요.
parameters.verbose Boolean 선택 상세한 출력을 제공해요.
parameters.memory_id String 선택 기존 대화를 이어가는 데 쓰이는 메모리 세션 ID예요. 이 필드는 conversation_index, agentic_memory 등 대화형 메모리 백엔드에서 지원돼요. 새 세션을 시작하려면 이 파라미터를 생략하세요.
parameters.memory_container_id String 선택 에이전트가 agentic_memory를 사용할 때 이 실행에 한해 구성된 메모리 컨테이너를 재정의해요.
parameters.include_token_usage Boolean 선택 true로 설정하면 응답에 각 대규모 언어 모델(LLM) 호출의 상세한 토큰 소비 지표가 포함돼요. conversational(v1), plan-execute-reflect, AG-UI 에이전트에서 지원돼요. conversational_v2 에이전트는 응답 형식에 항상 토큰 사용량이 포함되므로 이 파라미터가 필요 없어요. 기본값은 false예요. 토큰 사용량 추적을 참조하세요.
input String or Array 선택 일반 텍스트, 멀티모달 콘텐츠 블록, 메시지 기반 대화를 지원하는 표준화된 입력 필드예요. 통합 등록 방식과 함께 사용하세요.

conversation_index 또는 agentic_memory가 구성되어 있으면 응답에 memory_id가 포함돼요. 같은 세션을 계속하려면 이후 요청에 memory_id를 포함하세요. 새 세션을 시작하려면 memory_id를 생략하세요.

agentic_memory를 사용할 때는 메모리 컨테이너 ID도 함께 제공해야 해요. 에이전트 등록 시(memory.memory_container_id) 또는 각 요청에서(parameters.memory_container_id) 지정할 수 있어요. 메모리 컨테이너 ID가 제공되지 않으면 요청이 실패해요. {: .note}

일반 에이전트 실행

일반 등록 방식(에이전트 등록 API의 다단계 과정)으로 만든 에이전트는 parameters 필드를 사용하세요:

POST /_plugins/_ml/agents/879v9YwBjWKCe6Kg12Tx/_execute
{
  "parameters": {
    "question": "what's the population increase of Seattle from 2021 to 2023"
  }
}

{% include copy-curl.html %}

응답 예시

{
  "inference_results": [
    {
      "output": [
        {
          "result": """ Based on the given context, the key information is:

The metro area population of Seattle in 2021 was 3,461,000.
The metro area population of Seattle in 2023 is 3,519,000.

To calculate the population increase from 2021 to 2023:

Population in 2023 (3,519,000) - Population in 2021 (3,461,000) = 58,000

Therefore, the population increase of Seattle from 2021 to 2023 is 58,000."""
        }
      ]
    }
  ]
}

응답 필드

에이전트 실행의 기본 응답 필드는 다음 표와 같아요.

필드 데이터 타입 설명
inference_results Array 에이전트의 실행 결과가 담겨 있어요.
inference_results.output Array 이름-값 쌍으로 이루어진 출력 객체가 담겨 있어요.
inference_results.output.name String 출력 필드 이름이에요. 흔한 값으로는 response, memory_id, parent_interaction_id, token_usage가 있어요.
inference_results.output.result String 단순 문자열 결과에 해당하는 출력 값이에요(name이 response, memory_id, parent_interaction_id일 때 표시돼요).
inference_results.output.dataAsMap Object 구조화된 결과에 해당하는 출력 값이에요. 토큰 사용량 응답 필드와 conversational_v2 에이전트 응답 형식을 참조하세요.

통합 에이전트 실행

3.5부터 도입 {: .label .label-purple }

통합 등록 방식으로 만든 에이전트는 input 필드를 사용하세요. 지원되는 입력 형식은 에이전트 타입마다 달라요:

  • conversational 및 기타 V1 에이전트 타입: 일반 텍스트 입력만 지원해요.
  • conversational_v2(3.6부터 도입): 일반 텍스트, 멀티모달 콘텐츠 블록, 메시지 기반 대화 — 세 가지 입력 형식을 모두 지원해요.

일반 텍스트 입력

모든 통합 에이전트는 일반 텍스트 입력을 지원해요. 간단한 텍스트 프롬프트라면 문자열을 input 필드에 바로 전달하세요:

POST /_plugins/_ml/agents/{agent_id}/_execute
{
  "input": "What tools do you have access to?"
}

{% include copy-curl.html %}

응답 예시: 일반 텍스트 입력

{
  "inference_results": [
    {
      "output": [
        {
          "result": "I have access to the following tools:\n\n1. ListIndexTool - Lists all indices in the cluster\n2. SearchIndexTool - Searches within OpenSearch indices\n3. IndexMappingTool - Retrieves index mapping information"
        }
      ]
    }
  ]
}

멀티모달 콘텐츠 블록

통합 등록 방식을 쓸 때는 멀티모달 콘텐츠 블록과 메시지 기반 입력에 conversational_v2 에이전트가 필요해요. 다른 통합 에이전트 타입은 일반 텍스트 입력만 받아요. 일반 등록 방식을 쓸 때는 커넥터가 멀티모달 콘텐츠를 LLM에 전달하도록 구성되어 있으면 멀티모달을 지원할 수 있고, 입력 형식은 커넥터 구성에 따라 정해져요. {: .note}

멀티모달 입력(텍스트, 이미지, 문서)에는 콘텐츠 블록 배열을 사용하세요:

POST /_plugins/_ml/agents/{agent_id}/_execute
{
  "input": [
    {
      "type": "text",
      "text": "What can you see in this image?"
    },
    {
      "type": "image",
      "source": {
        "type": "base64",
        "format": "png",
        "data": "iVBORw0KGgoAAAANSUhEUgAA..."
      }
    }
  ]
}

{% include copy-curl.html %}

지원되는 콘텐츠 타입

지원되는 콘텐츠 타입은 다음 표와 같아요.

콘텐츠 타입 설명 필드
text 일반 텍스트 콘텐츠 text: 텍스트 문자열이에요.
image 이미지 데이터 image.type: 소스 타입이에요. 유효한 값은 base64예요.
image.format: 이미지 형식이에요(예: jpeg, png, gif, webp).
image.data: Base64로 인코딩된 이미지 데이터예요.
video 비디오 데이터 video.type: 소스 타입이에요. 유효한 값은 base64예요.
video.format: 비디오 형식이에요(예: mp4, mov, avi).
video.data: Base64로 인코딩된 비디오 데이터예요.
document 문서 데이터 document.type: 소스 타입이에요. 유효한 값은 base64예요.
document.format: 문서 형식이에요(예: pdf, docx, txt).
document.data: Base64로 인코딩된 문서 데이터예요.

메시지 기반 대화

멀티턴 대화에는 역할이 있는 메시지 배열을 제공하세요:

POST /_plugins/_ml/agents/{agent_id}/_execute
{
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "I like the color red"
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "Thanks for telling me that! I'll remember it."
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What color do I like?"
        }
      ]
    }
  ]
}

{% include copy-curl.html %}

이 메시지들은 에이전트의 메모리에 저장돼요.

메시지 필드

지원되는 메시지 필드는 다음 표와 같아요.

필드 데이터 타입 필수/선택 설명
role String 필수 메시지 역할이에요. 유효한 값: user, assistant.
content Array 필수 콘텐츠 블록(텍스트, 이미지 등)의 배열이에요.

응답 예시: 메시지 기반 대화

에이전트가 이전 메시지의 맥락을 기억해요:

{
  "inference_results": [
    {
      "output": [
        {
          "name": "memory_id",
          "result": "iEgpJZwBZx9B0F4spD5v"
        },
        {
          "name": "parent_interaction_id",
          "result": "ikgpJZwBZx9B0F4spT61"
        },
        {
          "name": "response",
          "result": "You like the color red, which you mentioned earlier in our conversation."
        }
      ]
    }
  ]
}

conversational_v2 에이전트 응답 형식

conversational_v2 에이전트는 다음과 같은 표준화된 응답 형식을 반환해요:

{
  "inference_results": [
    {
      "output": [
        {
          "name": "response",
          "dataAsMap": {
            "stop_reason": "end_turn",
            "message": {
              "role": "assistant",
              "content": [
                {
                  "text": "Here is what I found..."
                }
              ]
            },
            "memory_id": "abc123xyz",
            "metrics": {
              "total_usage": {
                "inputTokens": 1234,
                "outputTokens": 567,
                "totalTokens": 1801
              }
            }
          }
        }
      ]
    }
  ]
}

conversational_v2 에이전트의 응답 필드는 다음 표와 같아요.

필드 데이터 타입 설명
stop_reason String 에이전트가 응답 생성을 멈춘 이유예요. 유효한 값은 end_turn(정상 완료), max_iterations(반복 한도 도달), tool_use(도구 호출 중 중단)예요.
message Object 어시스턴트의 최종 응답 메시지예요.
message.role String 항상 assistant예요.
message.content Array 응답 텍스트나 기타 콘텐츠가 담긴 콘텐츠 블록 배열이에요.
memory_id String 메모리 세션 ID예요. 대화를 이어가려면 이후 요청의 parameters.memory_id 필드에 이 ID를 포함하세요.
metrics.total_usage.inputTokens Integer 소비된 입력 토큰 수예요.
metrics.total_usage.outputTokens Integer 생성된 출력 토큰 수예요.
metrics.total_usage.totalTokens Integer 사용된 총 토큰 수예요.

통합 등록 방식과 입력 형식에 대해 더 알아보려면 통합 등록 방식을 참조하세요.

토큰 사용량 추적

3.6에 도입됨 {: .label .label-purple }

include_token_usage를 true로 설정하면 응답에 비용 모니터링, 성능 디버깅, 모델 효율성 비교에 도움이 되는 상세한 토큰 소비 지표가 포함돼요. 이 파라미터는 일반 등록 방식과 통합 등록 방식을 모두 사용하는 conversational(v1), plan-execute-reflect, AG-UI 에이전트에서 지원돼요.

conversational_v2 에이전트는 metrics 필드를 통해 응답 형식에 토큰 사용량을 자동으로 포함하므로 이 파라미터가 필요하지 않아요. 자세한 내용은 conversational_v2 에이전트 응답 형식을 참조하세요. {: .note}

예제 요청: 일반 등록

3.6에 도입됨 {: .label .label-purple }

일반 등록으로 생성한 에이전트의 경우 parameters 객체에서 include_token_usage를 true로 설정하세요.

이 예제는 WebSearchTool로 구성된 conversational 에이전트의 멀티턴 실행 과정을 보여줘요. 멀티턴 실행이 발생하는 이유는 에이전트가 다음과 같이 동작하기 때문이에요:

  1. 턴 1: 질문을 받고, 어떤 정보가 필요한지 추론한 뒤, 인구 데이터를 찾기 위해 WebSearchTool을 사용하기로 결정해요.
  2. 턴 2: 도구 결과를 받고, 검색 결과를 분석하고 종합해서 최종 답변을 생성해요.
POST /_plugins/_ml/agents/879v9YwBjWKCe6Kg12Tx/_execute
{
  "parameters": {
    "question": "what's the population increase of Seattle from 2021 to 2023",
    "include_token_usage": true
  }
}

{% include copy-curl.html %}

예제 요청: 통합 등록

3.6에 도입됨 {: .label .label-purple }

통합 등록으로 생성한 에이전트의 경우 input 필드와 include_token_usage를 true로 설정한 parameters 객체를 모두 전달하세요:

POST /_plugins/_ml/agents/{agent_id}/_execute
{
  "input": "What tools do you have access to?",
  "parameters": {
    "include_token_usage": true
  }
}

{% include copy-curl.html %}

예제 응답: 토큰 사용량 추적

{
  "inference_results": [
    {
      "output": [
        {
          "name": "response",
          "result": """ Based on the given context, the key information is:

The metro area population of Seattle in 2021 was 3,461,000.
The metro area population of Seattle in 2023 is 3,519,000.

To calculate the population increase from 2021 to 2023:

Population in 2023 (3,519,000) - Population in 2021 (3,461,000) = 58,000

Therefore, the population increase of Seattle from 2021 to 2023 is 58,000."""
        },
        {
          "name": "token_usage",
          "dataAsMap": {
            "per_turn_usage": [
              {
                "turn": 1,
                "model_id": "rk6okJwB_kOxOUbO6853",
                "model_name": "Sonnet 4",
                "model_url": "https://bedrock-runtime.us-east-1.amazonaws.com/model/us.anthropic.claude-sonnet-4-20250514-v1:0/converse",
                "input_tokens": 1042,
                "output_tokens": 69,
                "total_tokens": 1111,
                "cache_read_input_tokens": 0,
                "cache_creation_input_tokens": 0
              },
              {
                "turn": 2,
                "model_id": "rk6okJwB_kOxOUbO6853",
                "model_name": "Sonnet 4",
                "model_url": "https://bedrock-runtime.us-east-1.amazonaws.com/model/us.anthropic.claude-sonnet-4-20250514-v1:0/converse",
                "input_tokens": 1541,
                "output_tokens": 269,
                "total_tokens": 1810,
                "cache_read_input_tokens": 0,
                "cache_creation_input_tokens": 0
              }
            ],
            "per_model_usage": [
              {
                "model_id": "rk6okJwB_kOxOUbO6853",
                "model_name": "Sonnet 4",
                "model_url": "https://bedrock-runtime.us-east-1.amazonaws.com/model/us.anthropic.claude-sonnet-4-20250514-v1:0/converse",
                "call_count": 2,
                "input_tokens": 2583,
                "output_tokens": 338,
                "total_tokens": 2921,
                "cache_read_input_tokens": 0,
                "cache_creation_input_tokens": 0
              }
            ]
          }
        }
      ]
    }
  ]
}

토큰 사용량 출력 응답 필드

token_usage 출력에는 다음 필드들이 포함돼요.

필드 데이터 타입 설명
per_turn_usage Array 단일 에이전트 실행 내에서 각 LLM 호출(턴)에 대한 토큰 사용량 기록의 배열이에요. 에이전트가 추론하고, 도구를 사용한 다음, 최종 응답을 생성해야 할 때 여러 턴이 발생하는데, 각 LLM 상호작용이 하나의 턴으로 계산돼요. 자세한 내용은 토큰 사용량 응답 필드를 참조하세요.
per_model_usage Array 모델별로 그룹화된 집계 토큰 사용량이에요. 자세한 내용은 토큰 사용량 응답 필드를 참조하세요.

토큰 사용량 응답 필드

다음 표는 per_turn_usage와 per_model_usage 배열에 나타나는 필드를 정리한 거예요.

필드 데이터 타입 포함 위치 설명
input_tokens Integer 둘 다 모델에 전송된 입력/프롬프트의 토큰 수예요.
output_tokens Integer 둘 다 모델의 출력/컴플리션에 포함된 토큰 수예요.
total_tokens Integer 둘 다 전체 토큰 수(입력 + 출력)예요.
cache_read_input_tokens Integer 둘 다 프롬프트 캐시에서 제공된 입력 토큰 수예요. Anthropic(Bedrock 경유), OpenAI, Gemini에서 지원돼요. 캐시된 토큰은 일반 입력 토큰보다 저렴한 경우가 많아요.
cache_creation_input_tokens Integer 둘 다 새 캐시 엔트리를 생성하는 데 사용된 토큰 수예요. Anthropic(Bedrock 경유)에서 지원돼요.
reasoning_tokens Integer 둘 다 추론이나 사고에 사용된 토큰 수예요. OpenAI 모델(completion_tokens_details.reasoning_tokens에서)과 Gemini 모델(thoughtsTokenCount에서)에 대해서만 추출돼요.
turn Integer per_turn_usage 에이전트 실행 내에서 이 LLM 호출의 순번이에요.
call_count Integer per_model_usage 이 모델을 사용해 수행한 LLM 호출의 총 횟수예요.
model_id String 둘 다 OpenSearch 내부 모델 ID예요.
model_name String 둘 다 사람이 읽을 수 있는 모델 이름(예: Sonnet 4, GPT-4)이에요.
model_url String 둘 다 모델 서비스의 엔드포인트 URL이에요.

토큰 계산 방식

토큰 수는 모델 제공자가 계산하며, 토크나이제이션 방식에 따라 달라질 수 있어요. 토큰 계산 방식에 대한 자세한 내용은 모델 제공자의 문서를 참조하세요:

더 알아보기 (Learn more)

함께 읽는 실무 이야기

우리 조직에도 적용하고 싶다면, AI 시스템 구축 서비스를 살펴보세요.