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

Conversational agents

원문 보기 위키 갱신

출처: 문서

본문

대화형 에이전트

2.13에 도입 {: .label .label-purple }

대화형 에이전트는 대규모 언어 모델(LLM)과 보조 도구 세트를 사용해 반복적으로 추론하고 응답을 제공해요. 에이전트는 Chain-of-Thought(CoT) 프로세스를 사용해 각 질문에 가장 적합한 도구를 선택하고, 대화 기록을 저장해 사용자가 후속 질문을 할 수 있도록 해요. 대화형 에이전트는 function calling을 사용해 도구를 호출해요.

OpenSearch는 두 가지 유형의 대화형 에이전트를 제공해요:

완전한 멀티모달 지원을 갖춘 conversational_v2 에이전트

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

conversational_v2 에이전트는 통합 등록 방식을 통해 커스텀 커넥터 구성 없이도 멀티모달 지원을 기본 제공함으로써 conversational 에이전트를 확장한 거예요. 통합 등록 방식을 사용할 때 일반 텍스트 입력만 받는 conversational 에이전트와 달리, conversational_v2 에이전트는 다음 입력 형식을 지원해요:

  • 일반 텍스트: 단순한 문자열 입력이에요.
  • 콘텐츠 블록: 텍스트, 이미지, 문서를 담고 있는 멀티모달 배열이에요.
  • 메시지: 다중 턴 상호작용을 위해 역할과 멀티모달 콘텐츠 블록이 포함된 전체 대화 기록이에요.

에이전트는 중지 사유, 어시스턴트 메시지, 메모리 세션 ID, 토큰 사용량 지표를 포함하는 응답을 반환해요. conversational_v2 에이전트는 agentic_memory 메모리 유형이 필요해요.

사전 요구 사항

conversational_v2 에이전트는 통합 등록 방식을 사용하며, 통합 에이전트 API가 활성화되어 있어야 해요. 설정 방법은 사전 요구 사항을 참고하세요.

conversational_v2 에이전트 등록하기

conversational_v2 에이전트를 등록하려면 다음 단계를 따르세요.

1단계: 메모리 컨테이너 생성

conversational_v2 에이전트를 등록하기 전에 Create Memory Container API를 사용해 메모리 컨테이너를 생성하세요:

POST /_plugins/_ml/memory_containers/_create
{
  "name": "my-agent-memory"
}

{% include copy-curl.html %}

이 요청은 기본 설정으로 메모리 컨테이너를 생성해요. 사용 사례에 따라 disable_session, embedding_model_id, 메모리 전략 같은 추가 옵션을 구성하고 싶을 수도 있어요. 사용 가능한 모든 옵션은 Create Memory Container API를 참고하세요.

응답에는 에이전트를 등록할 때 사용하는 memory_container_id가 반환돼요:

{
  "memory_container_id": "SdjmmpgBOh0h20Y9kWuN",
  "status": "created"
}

2단계: 에이전트 등록

에이전트를 등록하려면 다음 요청을 보내세요:

POST /_plugins/_ml/agents/_register
{
  "name": "My Conversational Agent V2",
  "type": "conversational_v2",
  "description": "A multimodal conversational agent",
  "model": {
    "model_id": "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
    "model_provider": "bedrock/converse",
    "credential": {
      "access_key": "<YOUR_AWS_ACCESS_KEY>",
      "secret_key": "<YOUR_AWS_SECRET_KEY>",
      "session_token": "<YOUR_SESSION_TOKEN>"
    }
  },
  "memory": {
    "type": "agentic_memory",
    "memory_container_id": "<YOUR_MEMORY_CONTAINER_ID>"
  },
  "tools": [
    {
      "type": "ListIndexTool"
    }
  ]
}

{% include copy-curl.html %}

conversational_v2 에이전트 실행하기

conversational_v2 에이전트는 input 필드를 사용하며 다음 입력 형식을 지원해요:

  • 일반 텍스트 입력:

    POST /_plugins/_ml/agents/{agent_id}/_execute
{
  "input": "What indexes are in my cluster?"
}

    {% include copy-curl.html %}

  • 멀티모달 콘텐츠 블록 입력:

    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 %}

  • 메시지 입력(다중 턴 대화 기록):

    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 sharing that!"}]
    },
    {
      "role": "user",
      "content": [{"type": "text", "text": "What color do I like?"}]
    }
  ]
}

    {% include copy-curl.html %}

conversational_v2 에이전트 응답 형식

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

{
  "inference_results": [
    {
      "output": [
        {
          "name": "response",
          "dataAsMap": {
            "stop_reason": "end_turn",
            "message": {
              "role": "assistant",
              "content": [
                {
                  "text": "Based on your cluster, I found the following indexes..."
                }
              ]
            },
            "memory_id": "test_memory_id",
            "metrics": {
              "total_usage": {
                "inputTokens": 1234,
                "outputTokens": 567,
                "totalTokens": 1801
              }
            }
          }
        }
      ]
    }
  ]
}

conversational_v2 에이전트의 응답 필드에 대한 자세한 내용은 conversational_v2 에이전트 응답 형식을 참고하세요.

제약 사항

conversational_v2 에이전트에는 다음과 같은 제약 사항이 적용돼요:

  • 메모리 유형: agentic_memory만 지원돼요. conversation_index 메모리 유형은 conversational_v2 에이전트와 호환되지 않아요.
  • 스트리밍: 스트리밍 응답은 지원되지 않아요.
  • 훅과 컨텍스트 관리: 에이전트 실행 훅과 컨텍스트 관리는 지원되지 않아요.

conversational 에이전트 (v1)

conversational 에이전트는 각각 다른 기능을 제공하는 두 가지 등록 방식을 지원해요:

  • 통합 등록 방식: 일반 텍스트 입력만 받아요. LLM 구성에는 model 필드를 사용해요.
  • 일반 등록 방식: 입력 기능은 커넥터 구성에 따라 달라져요. LLM 구성에는 llm 필드를 사용해요. 커넥터가 멀티모달 콘텐츠를 LLM에 전달하도록 구성하면 멀티모달 입력을 지원해요.

표준화된 인터페이스를 통한 완전한 멀티모달 지원이 필요하다면 conversational_v2 에이전트를 사용하세요. {: .note}

conversational 에이전트는 대규모 언어 모델(LLM)과 특정 작업을 수행하는 보조 도구 세트를 함께 구성할 수 있어요. 예를 들어 LLM과 ListIndexTool을 설정할 수 있어요. 모델에 질문을 보내면 에이전트가 ListIndexTool을 컨텍스트로 포함해요. 그러면 LLM이 "내 클러스터에 인덱스가 몇 개 있나요?" 같은 질문에 답하기 위해 도구를 사용해야 하는지 판단해요. 이를 통해 LLM은 자체 지식 기반 밖의 질문에도 답할 수 있어요.

통합 등록 방식 사용하기

다음 예제는 통합 등록 방식을 사용해 conversational 에이전트를 등록하는 방법을 보여 줘요:

POST /_plugins/_ml/agents/_register
{
  "name": "My Conversational Agent",
  "type": "conversational",
  "description": "A conversational agent using unified registration",
  "model": {
    "model_id": "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
    "model_provider": "bedrock/converse",
    "credential": {
      "access_key": "<YOUR_AWS_ACCESS_KEY>",
      "secret_key": "<YOUR_AWS_SECRET_KEY>",
      "session_token": "<YOUR_SESSION_TOKEN>"
    }
  },
  "memory": {
    "type": "conversation_index"
  },
  "tools": [
    {
      "type": "ListIndexTool"
    }
  ]
}

{% include copy-curl.html %}

일반 등록 방식 사용하기

다음 예제는 일반 등록 방식을 사용해 conversational 에이전트를 등록하는 방법을 보여 줘요:

POST /_plugins/_ml/agents/_register
{
  "name": "Test_Agent_For_ReAct_ClaudeV2",
  "type": "conversational",
  "description": "This is a test agent",
  "llm": {
    "model_id": "YOUR_LLM_MODEL_ID",
    "parameters": {
      "max_iteration": 5,
      "stop_when_no_tool_found": true,
      "response_filter": "$.completion"
    }
  },
  "memory": {
    "type": "conversation_index"
  },
  "tools": [
    {
      "type": "VectorDBTool",
      "name": "VectorDBTool",
      "description": "A tool to search OpenSearch index with natural language question. If you don't know answer for some question, you should always try to search data with this tool. Action Input: <natural language question>",
      "parameters": {
        "model_id": "YOUR_TEXT_EMBEDDING_MODEL_ID",
        "index": "my_test_data",
        "embedding_field": "embedding",
        "source_field": [ "text" ],
        "input": "${parameters.question}"
      }
    },
    {
      "type": "ListIndexTool",
      "name": "ListIndexTool",
      "description": "Use this tool to get OpenSearch index information: (health, status, index, uuid, primary count, replica count, docs.count, docs.deleted, store.size, primary.store.size)."
    }
  ],
  "app_type": "my app"
}

{% include copy-curl.html %}

토큰 사용량 추적

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

대화형 에이전트는 토큰 사용량 추적을 지원해요. 이 기능은 에이전트 실행 중 각 LLM 호출에서의 토큰 소비에 대한 상세 지표를 제공해요. 이를 통해 비용을 모니터링하고, 성능을 디버깅하고, 모델 효율성을 비교할 수 있어요.

토큰 사용량 추적을 활성화하려면 에이전트를 실행할 때 include_token_usage 파라미터를 true로 설정하세요. 그러면 응답에 턴별 및 모델별 집계 지표가 담긴 token_usage 출력이 포함돼요. 토큰 사용량 필드와 여러 모델 제공자의 토큰 계산 방식에 대한 자세한 내용은 Execute Agent API 문서의 토큰 사용량 추적을 참고하세요.

다음 단계

더 알아보기 (Learn more)

함께 읽는 실무 이야기

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