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

Register Agent API

원문 보기 위키 갱신

출처: 문서

본문

Register Agent API

Introduced 2.13 {: .label .label-purple }

이 API를 사용하여 에이전트를 등록하세요.

에이전트는 다음 유형 중 하나일 수 있어요:

  • Flow 에이전트
  • Conversational flow 에이전트
  • Conversational 에이전트
  • Plan-execute-reflect 에이전트
  • AG-UI 에이전트

에이전트에 대한 자세한 내용은 에이전트를 참조하세요.

자동 커넥터 및 모델 생성을 통해 에이전트를 등록하려면 통합 등록 방법을 사용할 수 있어요. 이 방법은 Amazon Bedrock Converse, Google Gemini 및 OpenAI 모델을 지원하며 plugins.ml_commons.unified_agent_api_enabled 클러스터 설정이 활성화되어야 해요. {: .note}

엔드포인트

POST /_plugins/_ml/agents/_register

요청 본문 필드

다음 표는 사용 가능한 요청 필드를 나열해요.

필드 데이터 타입 필수/선택 에이전트 유형 설명
name String 필수 모두 에이전트 이름.
type String 필수 모두 에이전트 유형. 유효한 값은 flow, conversational_flow, conversational, conversational_v2, plan_execute_and_reflect, ag_ui예요. 자세한 내용은 에이전트를 참조하세요.
agent_id String 선택 모두 에이전트의 고유 식별자예요. 생략하면 OpenSearch가 자동으로 생성해요.
description String 선택 모두 에이전트에 대한 설명.
tools Array 선택 모두 에이전트가 실행할 도구 목록.
app_type String 선택 모두 선택적 에이전트 범주를 지정해요. 그런 다음 해당 범주의 모든 에이전트에 대해 작업을 수행할 수 있어요. 예를 들어 RAG 에이전트의 모든 메시지를 삭제할 수 있어요.
memory.type String 선택 conversational_flow, conversational, plan_execute_and_reflect 대화 메모리를 저장할 위치를 지정해요. 지원되는 값은 conversation_index(대화 인덱스에 메모리 저장) 및 agentic_memory(메모리 컨테이너에 메모리 저장)예요.
memory.memory_container_id String 선택 conversational_flow, conversational, plan_execute_and_reflect agentic_memory의 기본 메모리 컨테이너 ID예요. 생략하면 에이전트 실행 시 parameters.memory_container_id를 제공해야 해요. 둘 다 제공되지 않으면 요청이 실패해요.
llm.model_id String 필수 conversational 질문을 보낼 LLM의 모델 ID.
llm.parameters.response_filter String 필수 conversational LLM 응답을 구문 분석하는 패턴이에요. 각 LLM에 대해 응답이 있는 필드를 제공해야 해요. 예를 들어 Anthropic Claude 모델의 경우 응답이 completion 필드에 있으므로 패턴은 $.completion이에요. OpenAI 모델의 경우 패턴은 $.choices[0].message.content예요.
llm.parameters.max_iteration Integer 선택 conversational LLM에 보낼 최대 메시지 수. 기본값은 10이에요.
parameters Object 선택 모두 에이전트 매개변수로, 에이전트가 실행하는 max_steps를 제어하거나 기본 프롬프트를 수정하는 등에 사용할 수 있어요.
parameters.executor_agent_id Integer 선택 plan_execute_and_reflect plan_execute_and_reflect 에이전트는 내부적으로 conversational 에이전트를 사용하여 각 단계를 실행해요. 기본적으로 이 실행 에이전트는 llm 구성에 지정된 계획 모델과 동일한 모델을 사용해요. 단계 실행에 다른 모델을 사용하려면 다른 모델을 사용하여 conversational 에이전트를 생성하고 이 필드에 에이전트 ID를 전달해요. 계획과 실행에 다른 모델을 사용하려는 경우 유용할 수 있어요.
parameters.max_steps Integer 선택 plan_execute_and_reflect LLM이 실행하는 최대 단계 수. 기본값은 20이에요.
parameters.executor_max_iterations Integer 선택 plan_execute_and_reflect 실행 에이전트가 LLM에 보내는 최대 메시지 수. 기본값은 20이에요.
parameters.message_history_limit Integer 선택 plan_execute_and_reflect 계획 수립자에게 컨텍스트로 포함할 대화 메모리의 최근 메시지 수. 기본값은 10이에요.
parameters.executor_message_history_limit Integer 선택 plan_execute_and_reflect 실행자에게 컨텍스트로 포함할 대화 메모리의 최근 메시지 수. 기본값은 10이에요.
parameters._llm_interface String 필수 plan_execute_and_reflect, conversational 함수 호출 사용 시 LLM 출력을 구문 분석하는 방법을 지정해요. 유효한 값은 다음과 같아요:
- bedrock/converse/claude: Amazon Bedrock에 호스팅된 Anthropic Claude 대화 모델
- bedrock/converse/deepseek_r1: Amazon Bedrock에 호스팅된 DeepSeek-R1 모델
- openai/v1/chat/completions: OpenAI에 호스팅된 OpenAI 채팅 완료 모델. 각 인터페이스는 기본 응답 스키마와 함수 호출 파서를 정의해요.
inject_datetime Boolean 선택 conversational, plan_execute_and_reflect 시스템 프롬프트에 현재 날짜를 자동으로 주입할지 여부. 기본값은 false예요.
datetime_format String 선택 conversational, plan_execute_and_reflect inject_datetime이 활성화된 경우 사용되는 날짜 형식 문자열. 기본값은 "yyyy-MM-dd'T'HH:mm:ss'Z'"(ISO 형식)이에요.
model Object 선택 conversational, plan_execute_and_reflect 통합 등록 방법 전용(3.5+): 커넥터와 모델을 자동으로 생성하는 모델 구성. 통합 등록 방법을 참조하세요.
model.model_id String 필수(model 사용 시) conversational, plan_execute_and_reflect 모델 식별자(예: Amazon Bedrock의 경우 us.anthropic.claude-3-7-sonnet-20250219-v1:0, Google Gemini의 경우 gemini-2.5-pro).
model.model_provider String 필수(model 사용 시) conversational, plan_execute_and_reflect 모델 제공자. 지원되는 값: bedrock/converse, gemini/v1beta/generatecontent, openai/v1/chat/completions.
model.credential Object 필수(model 사용 시) conversational, plan_execute_and_reflect 모델에 액세스하기 위한 자격 증명. 커넥터에서 지원하는 모든 자격 증명 형식을 허용해요. 자세한 내용은 커넥터 청사진을 참조하세요.
model.model_parameters Object 선택(model 사용 시) conversational, plan_execute_and_reflect 시스템 프롬프트 및 기타 구성 옵션과 같은 모델별 매개변수.
provisioned_by String 선택 모두 에이전트를 등록한 플러그인 또는 클라이언트를 식별하는 선택적 기여 태그(예: flow-framework). ML 통계 지표에 포함돼요.

Agentic memory 사용

Agentic memory를 사용하려면 Create Memory Container API를 사용하여 메모리 컨테이너를 생성하고 메모리 구성을 다음과 같이 설정해요.

"memory": {
  "type": "agentic_memory",
  "memory_container_id": "<memory_container_id>"
}

{% include copy.html %}

agentic_memory로 구성된 에이전트의 경우 에이전트 실행 후 세션 및 추적 데이터를 검사하는 방법에 대한 정보는 메모리 데이터 검사를 참조해요.

도구 구성

tools 배열에는 에이전트의 도구 목록이 포함돼요. 각 도구에는 다음 필드가 있어요.

필드 데이터 타입 필수/선택 설명
type String 필수 도구 유형. 지원되는 도구 목록은 도구를 참조하세요.
name String 선택 도구 이름. 도구 이름은 기본적으로 type 매개변수 값으로 설정돼요. 에이전트에 동일한 유형의 도구를 여러 개 포함해야 하는 경우 도구에 다른 이름을 지정해요.
description String 선택 도구 설명. 지정된 유형에 대한 기본 제공 설명으로 기본 설정돼요.
parameters Object 선택 이 도구의 매개변수. 매개변수는 도구 유형에 따라 크게 달라져요. 특정 도구 유형에 대한 정보는 도구에서 확인할 수 있어요.
parameters.output_processors Array 선택 도구의 출력을 변환하는 데 사용되는 프로세서 목록. 자세한 내용은 프로세서 체인을 참조하세요.
attributes.input_schema Object 선택 이 도구의 예상 입력 형식으로, JSON 스키마로 정의돼요. LLM이 도구를 호출할 때 따라야 할 구조를 정의하는 데 사용돼요.
attributes.strict Boolean 선택 함수 호출이 입력 스키마를 안정적으로 준수하는지 여부.

예제 요청: Flow 에이전트

POST /_plugins/_ml/agents/_register
{
  "name": "Test_Agent_For_RAG",
  "type": "flow",
  "description": "this is a test agent",
  "tools": [
    {
      "name": "vector_tool",
      "type": "VectorDBTool",
      "parameters": {
        "model_id": "zBRyYIsBls05QaITo5ex",
        "index": "my_test_data",
        "embedding_field": "embedding",
        "source_field": [
          "text"
        ],
        "input": "${parameters.question}"
      }
    },
    {
      "type": "MLModelTool",
      "description": "A general tool to answer any question",
      "parameters": {
        "model_id": "NWR9YIsBUysqmzBdifVJ",
        "prompt": "\n\nHuman:You are a professional data analyst. You will always answer question based on the given context first. If the answer is not directly shown in the context, you will analyze the data and find the answer. If you don't know the answer, just say don't know. \n\n Context:\n${parameters.vector_tool.output}\n\nHuman:${parameters.question}\n\nAssistant:"
      }
    }
  ]
}

{% include copy-curl.html %}

예제 요청: Conversational flow 에이전트

POST /_plugins/_ml/agents/_register
{
  "name": "population data analysis agent",
  "type": "conversational_flow",
  "description": "This is a demo agent for population data analysis",
  "app_type": "rag",
  "memory": {
    "type": "conversation_index"
  },
  "tools": [
    {
      "type": "VectorDBTool",
      "name": "population_knowledge_base",
      "parameters": {
        "model_id": "your_text_embedding_model_id",
        "index": "test_population_data",
        "embedding_field": "population_description_embedding",
        "source_field": [
          "population_description"
        ],
        "input": "${parameters.question}"
      }
    },
    {
      "type": "MLModelTool",
      "name": "bedrock_claude_model",
      "description": "A general tool to answer any question",
      "parameters": {
        "model_id": "your_LLM_model_id",
        "prompt": """

Human:You are a professional data analysist. You will always answer question based on the given context first. If the answer is not directly shown in the context, you will analyze the data and find the answer. If you don't know the answer, just say don't know. 

Context:
${parameters.population_knowledge_base.output:-}

${parameters.chat_history:-}

Human:${parameters.question}

Assistant:"""
      }
    }
  ]
}

{% include copy-curl.html %}

예제 요청: Conversational 에이전트

POST /_plugins/_ml/agents/_register
{
  "name": "Test_Agent_For_ReAct_ClaudeV2",
  "type": "conversational",
  "description": "this is a test agent",
  "app_type": "my chatbot",
  "llm": {
    "model_id": "<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": "<embedding_model_id>",
        "index": "<your_knn_index>",
        "embedding_field": "<embedding_filed_name>",
        "source_field": [
          "<source_filed>"
        ],
        "input": "${parameters.question}"
      }
    },
    {
      "type": "ListIndexTool",
      "name": "RetrieveIndexMetaTool",
      "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)."
    }
  ]
}

{% include copy-curl.html %}

예제 요청: Plan-execute-reflect 에이전트

Introduced 3.0 {: .label .label-purple }

POST /_plugins/_ml/agents/_register
{
  "name": "My plan execute and reflect agent",
  "type": "plan_execute_and_reflect",
  "description": "this is a test agent",
  "llm": {
    "model_id": "<llm_model_id>",
    "parameters": {
      "prompt": "${parameters.question}"
    }
  },
  "memory": {
    "type": "conversation_index"
  },
  "parameters": {
    "_llm_interface": "<llm_interface>"
  },
  "tools": [
    {
      "type": "ListIndexTool"
    },
    {
      "type": "SearchIndexTool"
    },
    {
      "type": "IndexMappingTool"
    }
  ],
  "app_type": "os_chat"
}

{% include copy-curl.html %}

예제 요청: AG-UI 에이전트

Introduced 3.5 {: .label .label-purple }

이 기능은 실험적 기능이며 프로덕션 환경에서 사용하지 않는 것이 좋아요. 기능 진행 상황에 대한 업데이트를 받거나 피드백을 남기려면 OpenSearch 포럼에서 토론에 참여해요. {: .warning}

AG-UI 에이전트는 AI 에이전트를 프론트엔드 애플리케이션과 통합하기 위해 통합 등록 방법을 사용해요. 다음 예제는 기본 구조를 보여줘요.

POST /_plugins/_ml/agents/_register
{
  "name": "AG-UI Agent",
  "type": "AG_UI",
  "description": "An AI agent designed for UI interactions with streaming support",
  "model": {
    "model_id": "<MODEL ID>",
    "model_provider": "bedrock/converse",
    "credential": {
      "access_key": "<AWS ACCESS KEY>",
      "secret_key": "<AWS SECRET KEY>",
      "session_token": "<AWS SESSION TOKEN>"
    },
    "model_parameters": {
      "system_prompt": "You are a helpful assistant and an expert in OpenSearch."
    }
  },
  "parameters": {
    "max_iteration": 5
  },
  "tools": [{
    "type": "ListIndexTool"
  }],
  "memory": {
    "type": "conversation_index"
  }
}

{% include copy-curl.html %}

필드 정의, 전제 조건, 실행 예제 및 AG-UI 프로토콜 형식을 포함한 전체 AG-UI 에이전트 문서는 AG-UI 에이전트를 참조해요.

예제 응답

OpenSearch는 에이전트를 참조하는 데 사용할 수 있는 에이전트 ID로 응답해요.

{
  "agent_id": "bpV_Zo0BRhAwb9PZqGja"
}

통합 에이전트 등록

3.5에서 도입 {: .label .label-purple }

통합 등록 방법은 단일 API 호출로 커넥터와 모델 설정을 자동으로 처리하여 에이전트 생성을 간소화합니다. 이 방법은 Amazon Bedrock Converse API와 Anthropic Claude 모델, Google Gemini 모델, OpenAI 모델을 지원합니다.

통합 에이전트를 사용하기 전에 필요한 클러스터 설정은 Prerequisites를 참조하세요. 자세한 정보와 지원되는 에이전트 유형은 Unified registration method를 참조하세요.

통합 등록 요청 필드

다음 표는 통합 에이전트 등록에 사용 가능한 요청 필드를 보여줍니다.

필드 데이터 타입 필수/선택 설명
name String 필수 에이전트 이름.
type String 필수 에이전트 유형. 지원 값: conversational, conversational_v2, plan_execute_and_reflect, AG_UI.
agent_id String 선택 에이전트의 고유 식별자. 생략하면 OpenSearch가 자동으로 생성합니다.
description String 선택 에이전트 설명.
model Object 필수 통합 등록 방법을 사용한 LLM 모델 구성. 일반 llm 객체를 대체하며 모델 리소스를 자동으로 생성합니다.
model.model_id String 필수 제공자의 모델 식별자. Amazon Bedrock의 경우 전체 모델 ID(예: us.anthropic.claude-3-7-sonnet-20250219-v1:0)를 사용합니다. Google Gemini의 경우 모델 이름(예: gemini-2.5-pro)을 사용합니다. OpenAI의 경우 gpt-4o-mini와 같은 모델 이름을 사용합니다.
model.model_provider String 필수 모델 제공자 유형. 유효 값: bedrock/converse, gemini/v1beta/generatecontent, openai/v1/chat/completions.
model.credential Object 필수 모델 제공자에 대한 자격 증명. 구조는 제공자에 따라 다릅니다.
model.credential.access_key String 필수(Amazon Bedrock) Amazon Bedrock 모델용 AWS 액세스 키.
model.credential.secret_key String 필수(Amazon Bedrock) Amazon Bedrock 모델용 AWS 비밀 키.
model.credential.session_token String 선택(Amazon Bedrock) 임시 자격 증명 사용 시 Amazon Bedrock 모델용 AWS 세션 토큰.
model.credential.openai_api_key String 필수(OpenAI) OpenAI 모델용 API 키.
model.credential.gemini_api_key String 필수(Google Gemini) Google Gemini 모델용 API 키.
model.model_parameters Object 선택 모델별 매개변수 및 구성.
model.model_parameters.system_prompt String 선택 에이전트의 역할과 동작을 정의하는 시스템 프롬프트.
model.model_parameters.temperature Float 선택 모델 응답의 무작위성을 제어합니다(0.0~1.0). 기본값은 모델에 따라 다릅니다.
model.model_parameters.max_tokens Integer 선택 모델 응답의 최대 토큰 수. 기본값은 모델에 따라 다릅니다.
parameters Object 선택 동작 제어를 위한 추가 에이전트 매개변수.
parameters.max_iteration Integer 선택 에이전트가 수행할 수 있는 최대 추론 반복 횟수. 기본값은 10입니다.
parameters.mcp_connectors Array 선택 에이전트 기능을 확장하는 MCP(Model Context Protocol) 커넥터 구성 배열. conversational 및 plan_execute_and_reflect 에이전트의 경우 MCP 도구가 자동으로 검색됩니다. flow 및 conversational_flow 에이전트의 경우 tools 배열에 MCP 도구를 명시적으로 나열하세요. Connecting to an external MCP server를 참조하세요.
parameters.mcp_connectors[].mcp_connector_id String 필수 등록된 MCP 커넥터의 ID.
parameters.mcp_connectors[].tool_filters Array 선택 에이전트에 사용 가능한 MCP 도구를 지정하는 Java 정규 표현식.
parameters.mcp_connectors[].tool_descriptions Array 선택 LLM에 제공되는 MCP 도구 설명을 재정의하는 객체.
tools Array 선택 에이전트에 사용 가능한 도구 배열. 지원되는 도구는 Tools를 참조하세요.
memory Object 선택 대화 메모리 저장소 구성.
memory.type String 선택 메모리 저장소 유형. 지원 값: conversation_index, agentic_memory.

tools 배열의 각 도구에는 다음 필드가 포함됩니다.

필드 데이터 타입 필수/선택 설명
type String 필수 도구 유형(예: ListIndexTool, SearchIndexTool, McpStreamableHttpTool, McpSseTool). flow 및 conversational_flow 에이전트의 MCP 도구는 mcp_streamable_http 커넥터와 함께 McpStreamableHttpTool을 사용하거나 mcp_sse 커넥터와 함께 McpSseTool을 사용하세요.
name String 선택 도구의 사용자 지정 이름. 기본값은 type 값입니다. 동일한 유형의 여러 도구를 사용할 때 필수입니다. flow 에이전트의 MCP 도구는 name을 MCP 서버 도구 이름으로 설정하세요.
description String 선택 LLM이 도구를 사용할 시기와 방법을 이해하는 데 도움이 되는 도구 설명.
parameters Object 선택 도구별 매개변수. 구조는 도구 유형에 따라 다릅니다.

예제 요청: Amazon Bedrock Claude

이 예제는 Amazon Bedrock에서 호스팅되는 Anthropic Claude 모델을 사용하여 에이전트를 생성합니다.

POST /_plugins/_ml/agents/_register
{
  "name": "Claude Research Agent",
  "type": "conversational",
  "description": "An agent using Claude for research tasks",
  "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_AWS_SESSION_TOKEN"
    },
    "model_parameters": {
      "system_prompt": "You are a helpful research assistant with access to OpenSearch data.",
      "temperature": 0.7,
      "max_tokens": 1000
    }
  },
  "parameters": {
    "max_iteration": 5
  },
  "tools": [
    {
      "type": "ListIndexTool"
    },
    {
      "type": "SearchIndexTool"
    },
    {
      "type": "IndexMappingTool"
    }
  ],
  "memory": {
    "type": "conversation_index"
  }
}

{% include copy-curl.html %}

예제 요청: Google Gemini

이 예제는 Google Gemini 모델을 사용하여 에이전트를 생성합니다.

POST /_plugins/_ml/agents/_register
{
  "name": "Gemini Analysis Agent",
  "type": "conversational",
  "description": "An agent using Gemini for data analysis",
  "model": {
    "model_id": "gemini-2.5-pro",
    "model_provider": "gemini/v1beta/generatecontent",
    "credential": {
      "gemini_api_key": "YOUR_GEMINI_API_KEY"
    },
    "model_parameters": {
      "system_prompt": "You are an expert data analyst with access to OpenSearch indices."
    }
  },
  "tools": [
    {
      "type": "SearchIndexTool"
    }
  ],
  "memory": {
    "type": "conversation_index"
  }
}

{% include copy-curl.html %}

예제 요청: OpenAI Chat Completion

이 예제는 OpenAI의 GPT 모델을 사용하여 에이전트를 생성합니다.

POST /_plugins/_ml/agents/_register
{
  "name": "GPT Customer Service Agent",
  "type": "conversational",
  "description": "An agent using GPT for customer service tasks",
  "model": {
    "model_id": "gpt-4o-mini",
    "model_provider": "openai/v1/chat/completions",
    "credential": {
      "openai_api_key": "YOUR_OPENAI_API_KEY"
    },
    "model_parameters": {
      "system_prompt": "You are a helpful customer service agent with access to customer data.",
      "temperature": 0.3,
      "max_tokens": 800
    }
  },
  "parameters": {
    "max_iteration": 10
  },
  "tools": [
    {
      "type": "ListIndexTool"
    },
    {
      "type": "SearchIndexTool"
    }
  ],
  "memory": {
    "type": "conversation_index"
  }
}

{% include copy-curl.html %}

예제 요청: Plan-execute-reflect 에이전트

이 예제는 복잡한 다단계 작업을 위한 plan-execute-reflect 에이전트를 생성합니다.

POST /_plugins/_ml/agents/_register
{
  "name": "Research Planning Agent",
  "type": "plan_execute_and_reflect",
  "description": "An agent that can plan and execute complex research tasks",
  "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_AWS_SESSION_TOKEN"
    },
    "model_parameters": {
      "system_prompt": "You are an expert researcher who can plan and execute multi-step research tasks."
    }
  },
  "parameters": {
    "max_steps": 15,
    "max_iteration": 20
  },
  "tools": [
    {
      "type": "ListIndexTool"
    },
    {
      "type": "SearchIndexTool"
    },
    {
      "type": "IndexMappingTool"
    }
  ],
  "memory": {
    "type": "conversation_index"
  }
}

{% include copy-curl.html %}

관련 문서

더 알아보기 (Learn more)