Configuring agentic search agents

원문 보기 위키 갱신 2026.10.14

출처: 문서

본문

에이전틱 검색 에이전트 구성

모델, 도구, 프롬프트를 커스터마이징해서 에이전틱 검색 에이전트를 구성할 수 있어요:

모델 구성: 다양한 작업에 최적화된 여러 대규모 언어 모델(LLM) 중에서 선택할 수 있어요.
도구 오케스트레이션: 여러 도구를 결합해서 자동화된 워크플로를 만들 수 있어요.
프롬프트 엔지니어링: 커스텀 프롬프트로 에이전트 동작을 세밀하게 조정할 수 있어요.

모델 구성

성능 요구 사항과 사용 사례에 따라 적절한 언어 모델을 선택하세요.

대화형 에이전트와 QueryPlanningTool에 서로 다른 모델을 구성할 수도 있어요. llm.model_id를 지정해서 에이전트의 모델을 설정하고, QueryPlanningTool에서 parameters.model_id를 지정해서 쿼리 플래너 모델을 설정하세요:

{
  "name": "Agentic Search Agent",
  "type": "conversational",
  "description": "Agent using separate models for conversation and query planning",
  "llm": {
    "model_id": "your-conversational-model-id",
    "parameters": {
      "max_iteration": 15
    }
  },
  "memory": {
    "type": "conversation_index"
  },
  "parameters": {
    "_llm_interface": "<llm_interface>"  
  },
  "tools": [
    {
      "type": "QueryPlanningTool",
      "parameters": {
        "model_id": "your-query-planner-model-id"
      }
    }
  ],
  "app_type": "os_chat"
}

{% include copy.html %}

<llm_interface>를 프로바이더에 맞는 인터페이스(예: openai/v1/chat/completions)로 설정한 다음, 다음 옵션 중에서 특정 모델을 선택하세요.

OpenAI GPT 모델

다음 OpenAI GPT 모델이 지원돼요.

GPT-5 (권장)

GPT-5는 고급 추론 기능을 제공하며 프로덕션 사용 사례에 권장돼요.

모델 등록:

POST /_plugins/_ml/models/_register
{
    "name": "My OpenAI model: gpt-5",
    "function_name": "remote",
    "description": "test model",
    "connector": {
        "name": "My openai connector: gpt-5",
        "description": "The connector to openai chat model",
        "version": 1,
        "protocol": "http",
        "parameters": {
            "model": "gpt-5"
        },
        "credential": {
            "openAI_key": "your-openai-api-key"
        },
        "actions": [
            {
                "action_type": "predict",
                "method": "POST",
                "url": "https://api.openai.com/v1/chat/completions",
                "headers": {
                    "Authorization": "Bearer ${credential.openAI_key}"
                },
                "request_body": "{ \"model\": \"${parameters.model}\", \"messages\": [{\"role\":\"developer\",\"content\":\"${parameters.system_prompt}\"},${parameters._chat_history:-}{\"role\":\"user\",\"content\":\"${parameters.user_prompt}\"}${parameters._interactions:-}], \"reasoning_effort\":\"low\"${parameters.tool_configs:-}}"
            }
        ]
    }
}

{% include copy-curl.html %}

추론 모드:

minimal: 가장 빠른 응답 시간으로, 간단한 사용 사례에 적합해요
low(권장): 약간 더 많은 추론으로, 대부분의 쿼리에 적합해요
medium: 복잡한 작업을 위한 향상된 추론이에요
high: 가장 복잡한 시나리오를 위한 최대 추론 성능이에요

더 높은 추론 모드를 선택할수록 전체 지연 시간이 늘어나요. 정확도 요구 사항을 충족하는 가장 낮은 모드를 선택하세요. {: .tip}

Anthropic Claude 모델

Anthropic Claude 모델은 Amazon Bedrock 통합을 통해 사용할 수 있으며, 복잡한 검색 시나리오를 위한 분석 기능을 제공해요.

Claude 4 Sonnet

Amazon Bedrock 커넥터 설정:

POST /_plugins/_ml/connectors/_create
{
    "name": "Bedrock Claude 4 Sonnet Connector",
    "description": "Amazon Bedrock connector for Claude 4 Sonnet",
    "version": 1,
    "protocol": "aws_sigv4",
    "parameters": {
        "region": "your-aws-region",
        "service_name": "bedrock",
        "model": "us.anthropic.claude-sonnet-4-20250514-v1:0"
    },
    "credential": {
        "access_key": "your-aws-access-key",
        "secret_key": "your-aws-secret-key",
        "session_token": "your-aws-session-token"
    },
    "actions": [
        {
            "action_type": "predict",
            "method": "POST",
            "url": "https://bedrock-runtime.${parameters.region}.amazonaws.com/model/${parameters.model}/converse",
            "headers": {
                "content-type": "application/json"
            },
            "request_body": "{ \"system\": [{\"text\": \"${parameters.system_prompt}\"}], \"messages\": [${parameters._chat_history:-}{\"role\":\"user\",\"content\":[{\"text\":\"${parameters.user_prompt}\"}]}${parameters._interactions:-}]${parameters.tool_configs:-} }"
        }
    ]
}

{% include copy-curl.html %}

에이전트 인터페이스 구성

에이전트를 등록할 때 _llm_interface 파라미터를 구성해서 function calling 사용 시 에이전트가 LLM 출력을 파싱하는 방식을 지정하세요. 모델 타입에 맞는 인터페이스를 선택하세요:

"bedrock/converse/claude": Amazon Bedrock에서 호스팅되는 Anthropic Claude 모델
"openai/v1/chat/completions": OpenAI chat completion 모델

각 인터페이스는 해당 모델 패밀리에 최적화된 기본 응답 스키마와 function call 파서를 정의해요.

도구 오케스트레이션

에이전틱 검색을 위해서는 QueryPlanningTool을 반드시 구성해야 해요. 에이전트의 기능을 확장하려면 추가 도구를 구성할 수도 있어요.

QueryPlanningTool

에이전틱 검색 기능에는 QueryPlanningTool이 필요해요. 이 도구는 자연어 쿼리를 OpenSearch 쿼리 도메인 특화 언어(DSL)로 변환해요.

추가 도구

필수인 QueryPlanningTool 외에도, 에이전트의 기능을 확장하려면 추가 도구를 구성할 수 있어요. OpenSearch는 검색 연산, 데이터 분석, 이상 탐지, 웹 통합 등 다양한 사용 사례를 위한 내장 도구를 제공해요. 사용 가능한 모든 도구의 전체 목록은 도구를 참고하세요.

대화형 에이전트는 쿼리 컨텍스트에 따라 적절한 도구를 자동으로 선택하고 오케스트레이션해요.

전체 에이전트 구성

다음 예시는 여러 도구를 갖춘 에이전트를 등록하는 방법을 보여줘요:

POST /_plugins/_ml/agents/_register
{
    "name": "Advanced Agentic Search Agent",
    "type": "conversational",
    "description": "Multi-tool agentic search with index discovery and web integration",
    "llm": {
        "model_id": "your-conversational-model-id",
        "parameters": {
            "max_iteration": 15
        }
    },
    "memory": {
        "type": "conversation_index"
    },
    "parameters": {
        "_llm_interface": "openai/v1/chat/completions"
    },
    "tools": [
         {
            "type": "ListIndexTool",
            "name": "ListIndexTool"
        },
        {
            "type": "IndexMappingTool",
            "name": "IndexMappingTool"
        },
        {
            "type": "WebSearchTool",
            "name": "DuckduckgoWebSearchTool",
            "parameters": {
                "engine": "duckduckgo"
            }
        },
        {
            "type": "QueryPlanningTool",
            "parameters": {
                "model_id": "your-query-planner-model-id"
            }
        }
    ],
    "app_type": "os_chat"
}

{% include copy-curl.html %}

지능형 인덱스 선택

ListIndexTool, IndexMappingTool 또는 기타 관련 도구를 포함하면 에이전트가 올바른 인덱스를 자동으로 선택하고 해당 인덱스에 맞는 쿼리를 생성할 수 있어요.

인덱스를 지정하지 않고 검색하려면 다음 요청을 보내세요:

GET /_search?search_pipeline=agentic-pipeline
{
    "query": {
        "agentic": {
            "query_text": "Find products with high ratings and low prices"
        }
    }
}

{% include copy-curl.html %}

에이전트가 제품 인덱스를 자동으로 발견하고, 구조를 분석하고, 적절한 쿼리를 생성해요.

검색 쿼리에서 인덱스를 지정하지 않으면 클러스터의 모든 샤드에 대해 검색이 실행되는데, 이는 비용이 클 수 있어요. 더 나은 성능을 위해 가능하면 대상 인덱스를 지정하세요. {: .tip}

프롬프트 엔지니어링 및 커스터마이징

모델의 추론 과정을 안내하는 커스텀 프롬프트를 사용해서 에이전트의 동작과 출력 형식을 구성하세요.

QueryPlanningTool 프롬프트를 커스터마이징하려면 QueryPlanningTool을 참고하세요.

시스템 프롬프트 최적화

특정 사용 사례에 맞는 맞춤형 시스템 프롬프트로 에이전트의 동작을 구성하세요.

에이전트 출력 형식

에이전트는 다음 출력 형식을 따라야 해요:

{
    "dsl_query": "<OpenSearch DSL Object>",
    "agent_steps_summary": "<chronological steps taken by the agent>"
}

{% include copy.html %}

커스텀 프롬프트 구성:

프롬프트를 커스터마이징할 때는 시스템 프롬프트와 사용자 프롬프트 모두에서 모델이 항상 앞서 설명한 에이전트 출력 형식으로 결과를 반환하도록 안내해야 해요. 일관된 출력 형식을 위해서는 적절한 프롬프트 엔지니어링이 매우 중요해요.

에이전트 등록 시 커스텀 프롬프트를 다음과 같이 제공하세요:

POST /_plugins/_ml/agents/_register
{
    "name": "Custom Prompt Agent",
    "type": "conversational",
    "description": "Agent with custom system and user prompts",
    "llm": {
        "model_id": "your-model-id",
        "parameters": {
            "max_iteration": 15,
            "system_prompt": "<YOUR CUSTOM SYSTEM PROMPT>",
            "user_prompt": "<YOUR CUSTOM USER PROMPT>"
        }
    },
    "memory": {
        "type": "conversation_index"
    },
    "parameters": {
        "_llm_interface": "openai/v1/chat/completions"
    },
    "tools": [
        {
            "type": "QueryPlanningTool",
            "parameters": {
                "model_id": "your-query-planner-model-id"
            }
        }
    ],
    "app_type": "os_chat"
}

{% include copy-curl.html %}

프롬프트 모범 사례

일관되고 정확한 결과를 만들어내는 효과적인 프롬프트를 작성하려면 다음 가이드라인을 따르세요:

구체적으로 작성: dsl_query와 agent_steps_summary 필드로 기대되는 에이전트 출력 형식을 명확히 정의하세요.
예시 포함: 올바른 에이전트 출력 형식으로 샘플 쿼리와 기대 응답을 제공하세요.
제약 조건 설정: 필드 이름, 데이터 타입, 쿼리 제한을 지정하세요.
JSON에 맞게 최적화: 프롬프트가 모델이 요구되는 에이전트 출력 구조를 갖춘 유효한 JSON을 생성하도록 안내하는지 확인하세요.

기본 시스템 프롬프트

다음 시스템 프롬프트가 기본으로 사용돼요. 이를 커스터마이징해서 에이전트의 동작을 바꿀 수 있어요:

프롬프트

{: .text-delta}

==== PURPOSE ====
Produce correct OpenSearch DSL by orchestrating tools. You MUST call the Query Planner Tool (query_planner_tool, "qpt") to author the DSL.
Your job: (a) gather only essential factual context, (b) compose a self-contained natural-language question for qpt, (c) validate coverage of qpt's DSL and iterate if needed, then (d) return a strict JSON result with the DSL and a brief step trace.

==== OUTPUT CONTRACT (STRICT) ====
Return ONLY a valid JSON object with exactly these keys:
{"dsl_query": <OpenSearch DSL Object>, "agent_steps_summary": "<chronological steps taken by the agent>"}
- No markdown, no extra text, no code fences. Double-quote all keys/strings.
- Escape quotes that appear inside values (including inside agent_steps_summary and inside the inlined qpt.question you report there).
- The output MUST parse as JSON.

==== OPERATING LOOP (QPT-CENTRIC) ====
1) PLAN (minimal): Identify the smallest set of facts truly required: entities, IDs/names, values, explicit time windows, disambiguations, definitions, normalized descriptors.
2) COLLECT (as needed): Use tools to fetch ONLY those facts. Do NOT mention schema fields, analyzers, or DSL constructs to the qpt.
3) SELECT index_name:
   - If provided by the caller, use it as-is.
   - Otherwise, discover and choose a single best index (e.g., list indices, inspect names/mappings) WITHOUT copying schema terms into qpt.question.
4) COMPOSE qpt.question: One concise, clear, self-contained natural-language question containing:
   - The user's request (no schema/DSL hints), and
   - The factual context you resolved (verbatim values, IDs, names, explicit date ranges, normalized descriptors).
   This question is the ONLY context (besides index_name) that qpt relies on.
5) CALL qpt with {question, index_name, embedding_model_id(if available)}.
6) VALIDATE qpt response and ensure it answers user's question else iterate by providing more context
7) FINALIZE when qpt produces a plausible, fully covered DSL.

==== CONTEXT RULES ====
- Use tools to resolve needed facts.
- When tools return user-specific values, RESTATE them verbatim in qpt.question in pure natural language.
- NEVER mention schema/field names, analyzers, or DSL constructs in qpt.question.
- Resolve ambiguous references BEFORE the final qpt call.

==== TRACE FORMAT (agent_steps_summary) ====
- First entry EXACTLY: "I have these tools available: [ToolA, ToolB, ...]"
- Then one entry per step:
  "First I used: <ToolName> — input: <short input>; context gained: <concise result>"
  "Second I used: …"
  …
  "N-th I used: query_planner_tool — qpt.question: <exact text with escaped quotes>; index_name_provided: <index-name>"
- Keep brief and factual. Do NOT restate the DSL. After the final qpt step you may add a short validation note.

==== FAILURE MODE ====
If required context is unavailable or qpt cannot produce a valid DSL
- Set "dsl_query" to {"query":{"match_all":{}}}
- Append a brief error note to agent_steps_summary, e.g., "error: missing relevant indices", "error: unresolved entity ID", "error: qpt failed to converge".

==== STYLE & SAFETY ====
- qpt.question must be purely natural-language and context-only.
- Be minimal and deterministic; avoid speculation.
- Use only the concise step summary.
- Always produce valid JSON per the contract.

==== END-TO-END EXAMPLE RUN (NON-EXECUTABLE, FOR SHAPE ONLY) ====
User question:
"Find shoes under 500 dollars. I am so excited for shoes yay!"

Process (brief):
- Index name not provided → use ListIndexTool to enumerate indices: "products", "machine-learning-training-data", …
- Choose "products" as most relevant for items/footwear.
- Confirm with IndexMappingTool that "products" index has expected data (do not copy schema terms into qpt.question).
- Compose qpt.question with natural-language constraints only.
- Call qpt and validate.

qpt.question (self-contained, no schema terms):
"Find shoes under 500 dollars."

qpt.output:
"{\"query\":{\"bool\":{\"must\":[{\"match\":{\"category\":\"shoes\"}}],\"filter\":[{\"range\":{\"price\":{\"lte\":500}}}]}}}"

Final response JSON:
{
  "dsl_query": {\"query\":{\"bool\":{\"must\":[{\"match\":{\"category\":\"shoes\"}}],\"filter\":[{\"range\":{\"price\":{\"lte\":500}}}]}}}},
  "agent_steps_summary": "I have these tools available: [ListIndexTool, IndexMappingTool, query_planner_tool]\nFirst I used: ListIndexTool — input: \"\"; context gained: \"Of the available indices, products index seems promising\"\nSecond I used: IndexMappingTool — input: \"products\"; context gained: \"index contains relevant fields\"\nThird I used: query_planner_tool — qpt.question: \"Find shoes under 500 dollars.\"; index_name_provided: \"products\"\nValidation: qpt output is valid JSON and reflects the user request."
}

기본 사용자 프롬프트

기본 사용자 프롬프트 템플릿은 자연어 질문과 사용 가능한 파라미터를 에이전트에 전달해요:

"NLQ is: ${parameters.question} and index_name is: ${parameters.index_name:-}, model ID for neural search is: ${parameters.embedding_model_id:-}"

다음 단계

커스터마이징된 에이전트를 실제로 사용하는 포괄적인 예시는 에이전틱 검색 살펴보기 및 대화 이어가기를 참고하세요.
사용 가능한 도구 목록은 도구를 참고하세요.

더 알아보기 (Learn more)

원문 전체: https://docs.opensearch.org/latest/vector-search/ai-search/agentic-search/agent-customization/

Configuring agentic search agents

본문

에이전틱 검색 에이전트 구성

모델 구성

OpenAI GPT 모델

GPT-5 (권장)

Anthropic Claude 모델

Claude 4 Sonnet

에이전트 인터페이스 구성

도구 오케스트레이션

QueryPlanningTool

추가 도구

전체 에이전트 구성

지능형 인덱스 선택

프롬프트 엔지니어링 및 커스터마이징

시스템 프롬프트 최적화

에이전트 출력 형식

프롬프트 모범 사례

기본 시스템 프롬프트

기본 사용자 프롬프트

다음 단계

더 알아보기 (Learn more)

함께 읽는 실무 이야기