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 %}
관련 문서
agentic_memory로 구성된 에이전트는 Inspecting memory data를 참조하세요.