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

AG-UI agents

원문 보기 위키 갱신

출처: 문서

본문

AG-UI 에이전트

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

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

Agent-User Interaction (AG-UI) 에이전트는 AI 에이전트를 프런트엔드 애플리케이션과 통합하기 위한 AG-UI 프로토콜을 따라요. 이 구현은 표준화된 스트리밍 상호작용과 정교한 도구 실행을 통해 실시간 AI 에이전트 기능을 사용자 인터페이스에 직접 제공해요.

대화형 에이전트와 비슷하게, AG-UI 에이전트는 대규모 언어 모델(LLM)과 선택적인 도구로 구성돼요. 사용자 입력을 처리할 때 에이전트는 LLM으로 요청을 추론하는데, 이때 대화 기록과 사용 가능한 프런트엔드 컨텍스트를 모두 고려해요. 그런 다음 에이전트는 사용할 도구를 정하고 실행해서 적절한 응답을 제공해요.

AG-UI 에이전트는 두 가지 유형의 도구를 사용할 수 있어요:

  • 백엔드 도구: 에이전트에 등록되는 도구로(ListIndexTool, SearchIndexTool 등), OpenSearch 데이터를 쿼리하고 서버 측 작업을 수행해요.
  • 프런트엔드 도구: 요청마다 제공되며, 대시보드 새로 고침, 필터 적용, 페이지 간 이동처럼 에이전트가 UI와 상호작용할 수 있게 해줘요.

사전 요구 사항

AG-UI 에이전트를 사용하기 전에 클러스터 설정을 업데이트해서 이 기능을 활성화해야 해요. ag_ui_enabled와 stream_enabled 설정은 필수이고, mcp_connector_enabled(Model Context Protocol [MCP] 서버에 연결하는 용도)와 unified_agent_api_enabled는 선택 사항이지만 설정하는 것을 권장해요:

PUT _cluster/settings
{
  "persistent": {
    "plugins.ml_commons.ag_ui_enabled": true,
    "plugins.ml_commons.stream_enabled": true,
    "plugins.ml_commons.mcp_connector_enabled": true,
    "plugins.ml_commons.unified_agent_api_enabled": true
  }
}

{% include copy-curl.html %}

AG-UI 에이전트 생성하기

AG-UI 에이전트는 통합 등록 방식을 사용해서 에이전트 생성을 단일 API 호출로 간소화해요. AG-UI 에이전트를 등록하려면 type 필드를 AG_UI로 설정하고 Unified Agent API로 모델을 구성하세요.

전체 등록 절차, 필드 정의, 지원되는 모든 모델 제공자(Amazon Bedrock, Google Gemini, OpenAI)의 예제는 통합 등록 방식을 참고하세요.

예제 요청: Amazon Bedrock Converse

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,
    "mcp_connectors": [{
        "mcp_connector_id": "<MCP CONNECTOR ID>" 
    }]
  },
  "tools": [{
    "type": "ListIndexTool"
  }],
  "memory": {
    "type": "conversation_index"  
  }
}

{% include copy-curl.html %}

예제 요청: OpenAI Chat Completion

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": "openai/v1/chat/completions",
    "credential": {
      "openai_api_key": "<OPENAI API KEY>"
    },
    "model_parameters": {
      "system_prompt": "You are a helpful assistant and an expert in OpenSearch."
    }
  },
  "parameters": {
    "max_iteration": 50,
    "mcp_connectors": [{
        "mcp_connector_id": "<MCP CONNECTOR ID>"  
    }]
  },
  "tools": [{
    "type": "ListIndexTool"
  }],
  "memory": {
    "type": "conversation_index"  
  }
}

{% include copy-curl.html %}

에이전트 스트림 실행

AG-UI 에이전트는 프런트엔드 애플리케이션을 위해 설계된 특수한 실행 프로토콜을 사용해요. input 필드를 사용하는 일반 에이전트 실행(Execute Agent API)과 달리, AG-UI 에이전트는 프런트엔드 컨텍스트, 도구, 스트리밍 응답을 담은 AG-UI 프로토콜 형식을 사용해요.

AG-UI 프로토콜 형식

AG-UI 실행은 AG-UI 프로토콜 사양을 따르며, 프런트엔드 애플리케이션과 AI 에이전트 사이의 구조화된 통신을 제공해요. 이 프로토콜에는 대화 스레딩, 프런트엔드 도구 통합, 실시간 스트리밍 응답이 포함돼요.

입력 형식 사양에 대해 자세히 알아보려면 AG-UI 문서의 RunAgentInput을 참고하세요.

요청 필드

요청 필드는 다음 표와 같아요.

필드 데이터 타입 필수/선택 설명
threadId String 필수 프런트엔드가 생성하는 대화 스레드의 고유 식별자예요. 여러 요청에 걸쳐 대화 연속성을 유지하고 대화 메모리를 가능하게 하는 데 사용돼요.
runId String 필수 프런트엔드가 생성하는, 이 스레드 내에서 이번 실행을 식별하는 고유 식별자예요. 새 요청마다 새로운 runId를 사용해야 해요.
state Object 필수 에이전트 세션의 현재 내부 상태예요. 동일한 실행 내에서 도구 호출 간에 유지되는 워크플로 상태, 사용자 기본 설정, 세션별 데이터를 저장할 수 있어요.
messages Array 필수 사용자 입력과 이전 어시스턴트 응답을 모두 포함하는 대화 메시지 배열이에요. 각 메시지에는 id, role(user/assistant), content가 있어요.
tools Array 필수 에이전트가 UI와 상호작용하려고 호출할 수 있는 프런트엔드 전용 도구 배열이에요. 각 도구에는 에이전트가 UI 작업을 호출하는 방법을 정의하는 name, description, parameters 스키마가 들어 있어요.
context Array 필수 에이전트에 현재 애플리케이션 상태를 알려 주는 컨텍스트 객체 배열이에요. 활성 대시보드, 적용된 필터, 시간 범위 등 에이전트가 사용자의 현재 상황을 이해하는 데 도움이 되는 UI 컨텍스트 정보가 포함돼요.
forwardedProps Object 필수 프런트엔드 애플리케이션에서 전달하는 추가 속성이에요. 사용자 인증 정보, 권한, 애플리케이션 구성, 에이전트 작업에 필요한 기타 메타데이터 등이 여기에 해당해요.

예제 요청

다음 예제는 프런트엔드 도구, 대화 컨텍스트, 애플리케이션 상태를 포함해 AG-UI 프로토콜 형식으로 AG-UI 에이전트를 실행하는 방법을 보여줘요:

POST /_plugins/_ml/agents/{{agent_id}}/_execute/stream
{
    "threadId": "thread-xxxxx",
    "runId": "run-xxxxx",
    "messages": [
        {
            "id": "msg-xxxxx",
            "role": "user",
            "content": "hello"
        }
    ],
    "tools": [
        {
            "name": "frontend_tool_example",
            "description": "This is a frontend tool",
            "parameters": {
                ...
            }
        }
    ],
    "context": [
        {
            "description": "Page context example",
            "value": "{\"appId\":\"example\",\"timeRange\":{\"from\":\"now-15m\",\"to\":\"now\"},\"query\":{\"query\":\"example\",\"language\":\"PPL\"}}"
        }
    ],
    "state": {},
    "forwardedProps": {}
}

{% include copy-curl.html %}

예제 응답

AG-UI 에이전트는 Server-Sent Events(SSE)를 반환하는데, 이를 통해 에이전트가 요청을 처리하는 동안 프런트엔드가 실시간 피드백을 제공할 수 있어요:

data: {"type":"RUN_STARTED","timestamp":1234567890,"threadId":"thread-xxxxx","runId":"run-xxxxx"}

data: {"type":"TEXT_MESSAGE_START","timestamp":1234567890,"messageId":"msg-xxxxx","role":"assistant"}

data: {"type":"TEXT_MESSAGE_CONTENT","timestamp":1234567890,"messageId":"msg-xxxxx","delta":"Response text here"}

data: {"type":"TEXT_MESSAGE_END","timestamp":1234567890,"messageId":"msg-xxxxx"}

data: {"type":"TOOL_CALL_START","timestamp":1234567890,"toolCallId":"tool-xxxxx","toolCallName":"frontend_tool_example"}

data: {"type":"TOOL_CALL_ARGS","timestamp":1234567890,"toolCallId":"tool-xxxxx","delta":"{\"param\":\"value\"}"}

data: {"type":"TOOL_CALL_END","timestamp":1234567890,"toolCallId":"tool-xxxxx"}

data: {"type":"RUN_FINISHED","timestamp":1234567890,"threadId":"thread-xxxxx","runId":"run-xxxxx"}

응답 필드

각 SSE에는 다음 필드가 담겨 있어요.

필드 데이터 타입 설명
type String 이벤트 타입이에요.
timestamp Long 이벤트가 생성된 시각의 Unix 타임스탬프(밀리초 단위)예요.
threadId String 요청에 담겼던 대화 스레드 ID예요.
runId String 요청에 담겼던 run ID예요.
messageId String 메시지의 고유 식별자예요(메시지 이벤트에 포함돼요).
role String 메시지 발신자의 역할이에요. 보통 "assistant"예요(메시지 시작 이벤트에 포함돼요).
delta String 스트리밍 텍스트나 도구 인자의 증분 콘텐츠예요(content/args 이벤트에 포함돼요).
toolCallId String 도구 호출의 고유 식별자예요(도구 호출 이벤트에 포함돼요).
toolCallName String 호출 중인 도구의 이름이에요(도구 호출 시작 이벤트에 포함돼요).

이벤트 타입

AG-UI 에이전트는 type 필드에 다음 이벤트 타입을 담은 SSE를 반환해요.

이벤트 타입 설명
RUN_STARTED 실행이 시작됐음을 나타내요
TEXT_MESSAGE_START 어시스턴트 메시지의 시작을 표시해요
TEXT_MESSAGE_CONTENT 증분 텍스트 콘텐츠를 담아요(스트리밍)
TEXT_MESSAGE_END 어시스턴트 메시지의 끝을 표시해요
TOOL_CALL_START 도구 호출이 시작됐음을 나타내요
TOOL_CALL_ARGS 증분 도구 호출 인자를 담아요
TOOL_CALL_END 도구 호출의 끝을 표시해요
RUN_FINISHED 실행이 완료됐음을 나타내요

토큰 사용량 추적

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

AG-UI 에이전트는 토큰 사용량 추적을 지원하는데, 이 기능은 에이전트 실행 중 각 LLM 호출에서 소비된 토큰에 대한 상세 지표를 제공해요. 토큰 사용량은 스트리밍 이벤트 시퀀스의 일부로 전달돼요.

AG-UI 에이전트의 경우 에이전트 등록 시 parameters 필드에 "include_token_usage": true를 설정하면 토큰 사용량 추적이 활성화돼요. 이 설정은 통합 등록 방식(새 인터페이스)과 일반 등록 방식(기존 인터페이스) 모두에 적용돼요. 에이전트가 한 번 등록되면 이 설정은 에이전트 실행 중에 바꿀 수 없으므로 반드시 등록 시점에 설정해야 해요.

등록 시 토큰 사용량 추적 활성화하기(통합 방식)

통합 등록 방식으로 AG-UI 에이전트의 토큰 사용량 추적을 활성화하려면 등록할 때 parameters 필드에 include_token_usage 파라미터를 포함하세요:

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,
    "include_token_usage": true
  },
  "tools": [{
    "type": "ListIndexTool"
  }],
  "memory": {
    "type": "conversation_index"  
  }
}

{% include copy-curl.html %}

등록 시 토큰 사용량 추적 활성화하기(일반 방식)

또는 일반 등록 방식을 사용해 에이전트의 parameters에 include_token_usage를 포함하는 방법으로도 토큰 사용량 추적을 활성화할 수 있어요:

POST /_plugins/_ml/agents/_register
{
  "name": "AG-UI Agent",
  "type": "AG_UI",
  "llm": {
    "model_id": "<MODEL_ID>",
    "parameters": {
      "max_iteration": 5
    }
  },
  "tools": [{
    "type": "ListIndexTool"
  }],
  "parameters": {
    "include_token_usage": true
  },
  "memory": {
    "type": "conversation_index"
  }
}

{% include copy-curl.html %}

스트리밍 응답의 토큰 사용량

토큰 사용량 추적이 활성화되면 스트리밍 응답에서 RUN_FINISHED 이벤트 다음에 토큰 사용량 지표가 담긴 Custom 이벤트가 포함돼요. 이 지표에는 턴별 토큰 소비량과 모델별 토큰 소비량이 담겨 있어요:

data: {"type":"RUN_STARTED","timestamp":1775501029508,"threadId":"thread-agui-new-agmem-postman","runId":"run-postman-agui-new-am"}

data: {"type":"TOOL_CALL_START","timestamp":1775501031547,"toolCallId":"tooluse_Z8ov0YNqeAW8B2h1qNH49w","toolCallName":"ListIndexTool"}

data: {"type":"TOOL_CALL_ARGS","timestamp":1775501031549,"toolCallId":"tooluse_Z8ov0YNqeAW8B2h1qNH49w","delta":""}

data: {"type":"TOOL_CALL_ARGS","timestamp":1775501031814,"toolCallId":"tooluse_Z8ov0YNqeAW8B2h1qNH49w","delta":"{\"indi"}

data: {"type":"TOOL_CALL_ARGS","timestamp":1775501031814,"toolCallId":"tooluse_Z8ov0YNqeAW8B2h1qNH49w","delta":"ces\": []}"}

data: {"type":"TOOL_CALL_END","timestamp":1775501031893,"toolCallId":"tooluse_Z8ov0YNqeAW8B2h1qNH49w"}

data: {"type":"TOOL_CALL_RESULT","timestamp":1775501031911,"messageId":"msg_66642762007875","toolCallId":"tooluse_Z8ov0YNqeAW8B2h1qNH49w","content":"..."}

data: {"type":"TEXT_MESSAGE_START","timestamp":1775501033817,"messageId":"msg_66644668213500","role":"assistant"}

data: {"type":"TEXT_MESSAGE_CONTENT","timestamp":1775501033818,"messageId":"msg_66644668213500","delta":"Here are all the indices..."}

data: {"type":"TEXT_MESSAGE_END","timestamp":1775501041102,"messageId":"msg_66644668213500"}

data: {"type":"Custom","timestamp":1775501041115,"name":"token_usage","value":{"per_turn_usage":[{"model_name":"Auto-generated model for us.anthropic.claude-sonnet-4-5-20250929-v1:0","model_url":"https://bedrock-runtime.us-east-1.amazonaws.com/model/us.anthropic.claude-sonnet-4-5-20250929-v1:0/converse","total_tokens":4806.0,"output_tokens":54.0,"turn":1.0,"model_id":"9RIbZJ0B1Feno22Ak-7G","input_tokens":4752.0},{"model_name":"Auto-generated model for us.anthropic.claude-sonnet-4-5-20250929-v1:0","model_url":"https://bedrock-runtime.us-east-1.amazonaws.com/model/us.anthropic.claude-sonnet-4-5-20250929-v1:0/converse","total_tokens":6262.0,"output_tokens":898.0,"turn":2.0,"model_id":"9RIbZJ0B1Feno22Ak-7G","input_tokens":5364.0}],"per_model_usage":[{"model_name":"Auto-generated model for us.anthropic.claude-sonnet-4-5-20250929-v1:0","model_url":"https://bedrock-runtime.us-east-1.amazonaws.com/model/us.anthropic.claude-sonnet-4-5-20250929-v1:0/converse","call_count":2.0,"total_tokens":11068.0,"output_tokens":952.0,"model_id":"9RIbZJ0B1Feno22Ak-7G","input_tokens":10116.0}]}}

data: {"type":"RUN_FINISHED","timestamp":1775501041116,"threadId":"thread-agui-new-agmem-postman","runId":"run-postman-agui-new-am"}

token_usage 이벤트에는 다음 내용이 담겨 있어요:

  • per_turn_usage: 에이전트 실행 중 각 개별 턴의 토큰 지표예요. turn 번호, model_id, model_name, model_url, input_tokens, output_tokens, total_tokens가 포함돼요.
  • per_model_usage: 모델별로 그룹화한 집계 토큰 지표예요. model_id, model_name, model_url, call_count, input_tokens, output_tokens, total_tokens가 포함돼요.

토큰 사용량 필드와 모델 제공자별 토큰 계산 방식에 대한 자세한 내용은 Execute Agent API 문서의 토큰 사용량 추적을 참고하세요.

다음 단계

더 알아보기 (Learn more)

함께 읽는 실무 이야기

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