에이전트 도구 정보

18 에이전트 도구 정보

Oracle AI Data Platform Workbench는 데이터에 액세스하고 사용 사례에 맞게 구성할 수 있는 도구 템플릿을 지원합니다.

에이전트는 하나 이상의 도구와 연결할 수 있는 단일 에이전트로 구성된 구성을 지원합니다. AI 데이터 플랫폼 워크벤치는 시각적 흐름 또는 코드를 통해 사용하도록 구성할 수 있는 세 가지 도구 템플리트를 제공합니다.

사용자정의 코드: AI 개발자는 사용자정의 코드 도구를 사용하여 Python을 사용하여 도구를 구현할 수 있습니다. 개발자는 도구를 ZIP에 패키지화하여 작업영역에 업로드하고 에이전트에서 노드로 구성합니다. 사용자정의 코드 도구는 내장된 도구가 필요한 통합을 제공하지 않는 경우에 사용됩니다.
HTTP 요청: HTTP 요청 도구는 개발자가 AI Data Platform 워크벤치 API 및 해당 도구가 제공하는 기능을 활용하여 에이전트에서 지원되는 REST API 호출을 사용할 수 있게 해 줍니다. 에이전트는 REST API를 사용하여 작업영역 객체를 생성하거나, 세부정보를 확인하거나, 목록을 풀링하거나, 기존 객체를 수정할 수 있습니다. 사용 가능한 API의 전체 목록은 Oracle AI Data Platform Workbench용 REST API를 참조하십시오.
프롬프트: 프롬프트 도구를 사용하면 AI 개발자가 선택한 LLM에 실행할 수 있는 매개변수화된 프롬프트를 정의할 수 있습니다. 프롬프트 도구의 일반적인 사용 사례에는 전자메일 제도 태스크, 번역 태스크, 스타일 변환, Git 커밋 메시지 및 코드 설명이 포함됩니다.
RAG: 에이전트는 RAG 도구를 사용하여 응답을 생성하기 전에 관련 외부 지식을 가져올 수 있습니다. AI 데이터 플랫폼 워크벤치에서 RAG 도구는 지식 기반(26ai Vector Search)을 쿼리하고 의미상 관련된 문서 청크를 검색합니다. 그런 다음 이러한 청크는 응답 생성을 위해 에이전트로 전달됩니다.
SQL: 에이전트는 SQL 도구를 사용하여 Oracle Autonomous AI Lakehouse, Oracle Autonomous AI Transaction Processing, Oracle Autonomous AI Database 등 외부 카탈로그를 통해 등록된 구조화된 데이터 소스에 대해 SQL 쿼리를 실행할 수 있습니다. 이 도구는 SQL query가 미리 정의되어 있고 파라메트화할 수 있는 시나리오를 위한 것입니다. 목표는 에이전트가 매개변수에 값을 할당하도록 하는 것입니다. 이 도구는 자연어 프롬프트를 기반으로 SQL query를 생성하는 NL2SQL 도구가 아닙니다.

주:
SQL 도구는 외부 카탈로그의 데이터에 대해서만 query를 수행합니다. 표준 카탈로그에 저장된 데이터는 지원하지 않습니다.

시각적 플로우를 통한 에이전트 플로우 도구

시각적 흐름을 통해 에이전트에 툴을 추가하는 경우 에이전트의 도구 템플리트에서 툴을 찾을 수 있습니다. 시각적 흐름 캔버스로 툴을 끌어 놓아 에이전트에 툴을 추가합니다. 캔버스에서 도구 노드를 끌어온 후 노드가 에이전트와 자동으로 연결됩니다.

도구 템플리트 섹션이 강조 표시된 에이전트 페이지와 도구에서 캔버스로 향하는 화살표

각 도구는 Parameters 탭에서 구성할 수 있으며 Test 탭을 눌러 에이전트와 독립적으로 테스트할 수 있습니다.

주:

시스템 툴을 테스트하려면 먼저 에이전트에 AI 컴퓨트를 연결해야 합니다. 연결된 컴퓨트가 없는 경우 Test(테스트) 탭이 사용 안함으로 설정됩니다.

LangGraph 코드를 통한 에이전트 도구

AIDPToolConf() 클래스의 인스턴스를 통해 LangGraph 코딩된 에이전트에 도구를 추가합니다.

from aidputils.agents.toolkit.configs import AIDPToolConf
aidp_tool =  AIDPToolConf(name, description, tool_class, conf, params)

매개변수는 도구에 대한 시각적 흐름 환경을 미러링합니다. 각 도구에 대해 다음을 제공해야 합니다.

이름: 사용자와 LLM이 도구의 목적을 이해하는 데 도움이 되는 설명형 이름입니다.
설명: 사용자와 LLM이 도구의 기능을 이해할 수 있도록 충분한 정보를 제공하는 철저한 요약입니다.
tool_class: 지원되는 도구 유형 PromptTool, SQLTool, RAGTool, HTTPTool 및 MCPTool입니다.
conf: 도구 구성입니다. 이 정보는 LLM에서 숨겨집니다.
params: LLM에 노출된 매개변수입니다.

사용자정의 도구

사용자 정의 코드 도구를 사용하면 에이전트 개발자가 자체 Python 코드로 AI 데이터 플랫폼을 확장할 수 있습니다.

도구 구현을 ZIP 파일로 패키지화하고 작업 영역에 업로드한 다음 에이전트에서 사용자 정의 코드 도구 노드로 구성합니다. 에이전트는 런타임 시 LLM에서 제공하는 매개변수를 사용하여 코드를 도구로 호출합니다.

사용자 정의 코드 도구는 내장 도구(HTTP, SQL, RAG, MCP)가 필요한 통합을 포함하지 않는 경우에 사용됩니다. 예를 들어 로컬 계산을 수행하거나, 도메인 특정 형식을 구문 분석하거나, 에이전트에 단일 도구 호출로 표시되어야 하는 여러 단계를 구성해야 하는 경우입니다.

AI Data Platform Workbench는 사용자정의 코드 툴에 대한 Python 코드가 포함된 ZIP 파일을 업로드할 때 다음과 같은 제한이 있습니다.

제약 조건	제한
최대 ZIP 크기	10 MB
ZIP 내의 최대 파일 크기	파일당 10MB
최대 총 압축되지 않은 크기	500 MB
경로 순번	차단됨(../ 거부됨)

주:

사용자정의 코드 툴은 에이전트에 연결된 AI 컴퓨트에서 실행됩니다. 코드에는 작업 영역 네트워킹 구성에 따라 컴퓨트 환경 및 아웃바운드 네트워크 액세스에 대한 액세스 권한이 있습니다. 신뢰할 수 있는 소스에서만 코드를 업로드 합니다.

사용자정의 코드 도구 매개변수

Parameters 탭에서는 패키지의 각 도구 클래스에 대한 정적 설정을 구성합니다. 도구 클래스 드롭다운을 사용하면 패키지에서 검색된 도구 간에 전환할 수 있습니다.

사용자정의 코드 도구 페이지가 열려 있습니다. Parameters 탭이 선택됩니다. Configuration 창은 왼쪽에 표시됩니다. 오른쪽에 AI 도구 정의 창이 표시됩니다.

사용자 정의 코드 도구 매개변수 탭에는 다음 섹션이 포함됩니다.

도구 클래스: 구성할 도구 클래스를 선택합니다. 드롭다운은 tool_implementation.py에 등록된 클래스에서 채워집니다.
설명: 도구의 작업에 대한 명확하고 간결한 설명입니다. 이 설명은 에이전트에 제공되며 LLM이 도구 호출 시기를 결정하는 데 도움이 됩니다. 기본 설명은 tool_config.json에서 읽혀지며 여기에서 대체할 수 있습니다.
구성: 런타임 시 도구에 필요한 정적 설정입니다. tool_config.json의 conf 객체에 정의된 키입니다. 예를 들어 시간 초과, base_dir, max_output_lines 및 인증서 참조가 있습니다. 구성 값은 {{variable}} 런타임 매개변수 참조를 지원합니다. 세션 변수는 현재 사용자 정의 도구 구성으로 대체되지 않습니다. 세션 값이 필요한 경우 에이전트에서 런타임 매개변수로 전달하십시오.
AI 도구 정의: 에이전트가 전달할 수 있는 도구 이름, 설명 및 런타임 매개변수를 포함하여 에이전트에 노출된 스키마입니다. 스키마는 tool_config.json의 스키마 배열에서 자동으로 렌더링됩니다.

사용자정의 코드 도구 작성

사용자 정의 코드 도구 패키지는 다음 구조를 가진 ZIP 파일입니다.

my_tool.zip 
├── tool_implementation.py    # Required. Contains the tool class(es). 
├── tool_config.json          # Required. Tool metadata and schema. 
├── requirements.txt          # Optional. Python dependencies. 
├── utils/                    # Optional. Helper modules. 
│   ├── __init__.py 
│   └── helpers.py 
├── config/                   # Optional. Static configuration files. 
│   └── settings.yaml 
└── wheels/                   # Optional. Bundled wheel files for offline install. 
    └── humanize-4.15.0-py3-none-any.whl

도구_구현.py

각 도구 클래스는 CustomToolBase를 확장하고 @BaseTool.register로 장식됩니다. 클래스는 도구 구성, 에이전트로부터의 런타임 파라미터 및 시스템 컨텍스트 변수를 수신하고 dict, str 또는 list와 같은 값을 반환하는 _execute_tool 클래스 메소드를 구현해야 합니다.

다음은 tool_implementation.py의 빈 예제 템플리트입니다.

"""Custom Code tool implementation.""" 
from aidputils.agents.tools.custom_tools.base import CustomToolBase 
 
 
@BaseTool.register 
class MyTool(CustomToolBase): 
    """Brief description of what the tool does.""" 
 
    @classmethod 
    def _validate_config(cls, conf, runtime_params, **context_vars): 
        """Optional. Validate configuration before execution. 
        Raise ValueError to abort the call. 
        """ 
        # Example: require an api_key in the tool configuration 
        if not conf.get("conf", {}).get("api_key"): 
            raise ValueError("api_key is required") 
 
    @classmethod 
    def _execute_tool(cls, conf, runtime_params, **context_vars): 
        """Required. Implement the tool logic. 
 
        Args: 
            conf: the AIDPToolConf dict. User configuration values 
                live under conf["conf"] when the tool is invoked from 
                a deployed agent. During a Test run the tool may 
                receive a flat conf dict; the Developer Toolkit example 
                below uses a small _get_cfg helper that tolerates both 
                shapes. 
            runtime_params: the runtime parameters passed by the 
                agent at invocation time. 
            context_vars: system context (such as datalake_id). 
 
        Returns: 
            Any value (dict, str, list, ...). It will be wrapped into 
            the MCP response by the framework. 
 
            To signal a failure, raise an exception: 
              - ValueError -> INVALID_CONFIG 
              - any other exception -> TOOL_EXECUTION_ERROR 
            Do NOT return {"error": "..."}; the framework wraps a 
            successful return in {"response": ..., "success": True}, 
            so a returned error dict is treated as a normal payload 
            and the agent will not see it as a failure. 
        """ 
        tool_conf = conf.get("conf", conf) 
        param_value = runtime_params.get("my_param", "") 
        # Tool logic here 
        return {"output": f"Processed: {param_value}"} 
 
    @classmethod 
    def _transform_response(cls, response): 
        """Optional. Transform the response before MCP formatting.""" 
        return response

도구_config.json

tool_config.json 파일은 패키지의 도구(표시 이름, 설명, 버전, 런타임 매개변수 스키마 및 기본 구성 값)에 대해 설명합니다. tool_implementation.py에 등록된 각 도구는 tools 배열의 해당 항목을 가져야 합니다.

다음은 tool_config.json의 빈 예제 템플리트입니다.

{
   "displayName": "My Tool Package",
   "description": "Brief description of the tool package.",
   "tools": [
     {
       "toolClassName": "MyTool",
       "displayName": "My Tool",
       "description": "Clear description of when the agent should call this tool.",
       "version": "1.0.0",
       "schema": [
         {
           "name": "my_param",
           "type": "string",
           "description": "What this parameter is for."
         }
       ],
       "conf": {
         "timeout": 30
       }
     }
   ]
 }

스키마 필드 유형

Visual Builder의 Parameters 탭은 문자열, 숫자 및 부울을 받아들입니다. int, integer, float, double, number, numeric, bytes, list, array, sequence, dict, map, mapping, set, tuple, none, null 및 list[int]와 같은 일반 폼을 손으로 작성할 때 런타임이 더 넓은 세트를 허용합니다. 이러한 더 넓은 유형은 JSON에서 사용할 수 있지만 UI 드롭다운에 노출되지 않습니다.

요구 사항.txt

requirements.txt 파일은 도구에 필요한 Python 종속성을 나열합니다. 버전 지정자 및 설명을 비롯한 표준 파이프 구문이 지원됩니다. 파일은 선택 사항입니다. 도구가 Python 표준 라이브러리 또는 사전 설치된 패키지만 사용하는 경우 requirements.txt가 필요하지 않습니다.

다음은 requirements.txt의 빈 예입니다.

# List third-party dependencies one per line. 
# Examples: 
# humanize>=4.0 
# python-dateutil>=2.8,<3.0 
# beautifulsoup4==4.12.3

AI Data Platform Workbench는 AI 컴퓨트에 설치하기 전에 requirements.txt의 종속성을 필터링하여 런타임이 플랫폼 자체와 충돌하지 않도록 합니다. 필터링 규칙은 다음과 같습니다.

Category	예	작업
플랫폼 패키지	langgraph, langchain 핵심, langchain-oci, langchain_mcp_adapters, pyyaml	폐기됨(에이전트 런타임을 중단해야 함).
사전 설치된 패키지	oci, requests, requests-toolbelt, websockets, cryptography, certifi, pyopenssl, urllib3, pydantic, pydantic-core, pydantic-settings, numpy, oracledb, sqlalchemy, aiohttp, httpx, httpx-sse, anyio, jsonschema, orjson	건너뜀(이미 사용할 수 있으므로 선언할 필요가 없음).
URL 또는 VCS 설치	git+https://..., -e ./local_pkg	차단됨(보안).
기타 모든 것	인간화, beautifulsoup4, jmespath	설치되었습니다.

주:

requirements.txt에 선언된 종속성은 에이전트의 전체 배치 중에 설치됩니다. 구성 패널에서 단일 테스트 실행 중에는 종속성이 설치되지 않습니다. 도구가 타사 패키지에 종속된 경우 먼저 에이전트를 배치한 다음 Playground에서 도구를 실행합니다.

사전 설치되지 않은 종속성 및 결정적인 오프라인 설치가 중요한 도구의 경우 ZIP 루트의 휠/ 디렉토리 내에 .whl 파일을 묶을 수 있습니다. 플랫폼은 먼저 로컬 휠 디렉토리에서 설치되며 필요한 경우에만 패키지 인덱스로 폴백됩니다. 이는 프로덕션 도구에 권장되는 접근 방식입니다.

오프라인 설치를 위한 번들 휠

pip download \
  --dest wheels/ \
  --platform manylinux_2_28_x86_64 \
  --python-version 3.11 \
  --only-binary=:all: \
  -r requirements.txt

도구 수명 주기 후크

사용자정의 코드 도구는 세 가지 수명 주기 방법을 지원합니다. _execute_tool만 필요합니다.

방법	호출 시	용도
_검증_구성	_execute_tool 이전	구성을 검증합니다. 호출이 실행되기 전에 호출을 중단하려면 ValueError를 발생시킵니다.
실행 도구(_E)	모든 도구 호출 시	필수입니다. 도구의 동작을 구현합니다. 모든 값(dict, str, list)을 반환하고 오류를 알리는 예외를 발생시킵니다(ValueError → INVALID_CONFIG, 기타 예외 → TOOL_EXECUTION_ERROR). 반환된 {"error": "..."} dict는 일반 페이로드로 처리되므로 사용하지 마십시오.
_transform_response	_execute_tool 이후	응답이 MCP 형식으로 래핑되어 에이전트로 반환되기 전에 변환합니다.
prompt_template	string	동적 삽입을 위해 변수가 {{variable}} 형식인 LLM에서 사용하는 프롬프트 템플리트

구성 값과 런타임 파라미터 비교

사용자정의 코드 도구에는 혼동하기 쉬운 두 가지 고유한 입력 소스가 있습니다. 구성 값은 [매개변수] 탭의 [구성] 섹션에서 가져오며 에이전트가 배치될 때 도구에 적용됩니다. 런타임 매개변수는 호출 시 에이전트에서 가져오며 호출 시마다 다릅니다.

구성 값은 conf.get("conf", conf)를 통해 액세스됩니다. 기본 URL, 자격 증명 참조, 시간 초과, 출력 제한 등 호출 간에 변경되지 않는 경우에 사용합니다.
런타임 매개변수는 runtime_params.get("name")을 통해 액세스됩니다. 에이전트가 호출 시 실제로 결정하는 값(질의, 파일 경로, 요청 본문)에 사용합니다.

주:

구성 값은 템플리트 대체를 통과할 수 있으며 숫자로 정의한 경우에도 문자열로 도착할 수 있습니다. 항상 숫자 구성 값을 방어적으로 강제 적용합니다(예: int(tool_conf.get("timeout", 30))).

패키지당 여러 도구

단일 ZIP에는 여러 도구 클래스가 포함될 수 있습니다. @CustomToolBase.register에 등록된 각 클래스는 에이전트에서 별도의 도구가 됩니다. [패키지] 탭의 [도구] 패널에는 검색된 모든 도구가 나열되며 각 도구를 독립적으로 사용으로 설정할 수 있습니다. 각 도구는 도구 클래스 드롭다운을 통해 매개변수 탭에서 별도로 구성됩니다.

LangGraph 코드를 통한 코드 도구

코드 빌더에서 사용자 정의 코드 도구는 업로드된 패키지를 참조하고 해당 도구 클래스 중 하나를 선택하여 aidpUtils Python 라이브러리를 통해 등록됩니다.

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
 from aidputils.agents.toolkit.configs import AIDPToolConf
 
hello_tool_conf = AIDPToolConf(
     name="hello_tool",
     description="Returns a hello world greeting.",
     tool_class="HelloTool",  # the class registered with @BaseTool.register
     conf={},                  # values from tool_config.json "conf"; supports {{variable}} substitution
     params=[
         {"name": "name", "type": "string",
          "description": "Name to greet."}
     ],
 )
 
hello_tool = create_langgraph_tool(hello_tool_conf.model_dump())

tool_class은 tool_implementation.py에서 @BaseTool.register를 통해 등록된 정확한 클래스 이름이어야 합니다. 프레임워크는 BaseTool.tool_class_registry[tool_class]에서 클래스를 조회합니다. conf는 tool_config.json에서 일치하는 항목의 conf 객체를 미러링합니다.

주:

package_path 또는 tool_class_name는 소비되지 않으므로 conf 내에 배치하지 마십시오.

테스트 에이전트 사용자 정의 코드 도구

테스트 탭에서는 전체 에이전트를 실행하지 않고도 툴을 실행할 수 있습니다. 런타임 매개변수 및 구성에서 참조된 모든 세션 변수에 대한 값을 제공한 다음 Run을 눌러 툴을 호출하고 응답을 봅니다.

사용자정의 코드 도구 페이지가 열려 있습니다. Test 탭이 선택되어 있습니다. 테스트 매개변수는 왼쪽 창에 표시됩니다. 테스트 결과가 오른쪽 창에 표시됩니다.

주:

도구가 requirements.txt에 선언된 타사 패키지에 의존하는 경우 단일 테스트 실행 중이 아니라 에이전트의 전체 배치 중에 종속성이 설치됩니다. 추가 패키지에 종속된 코드를 테스트하려면 먼저 에이전트를 배치한 다음 Playground에서 도구를 호출합니다.

에이전트에 사용자 정의 도구 추가

자체 Python 코드를 사용하여 AI 데이터 플랫폼을 확장할 수 있도록 에이전트에 사용자정의 도구를 추가할 수 있습니다.

주:

사용자정의 코드 툴을 추가하기 전에 AI 컴퓨트를 에이전트에 연결해야 합니다. 종속성을 설치하고 툴을 실행하려면 AI 컴퓨트가 필요합니다.

에이전트로 이동합니다.
Tool Templates에서 Custom 도구를 캔버스로 끌어 놓습니다.
패키지 탭에서 사용자 정의 코드가 포함된 ZIP 파일을 눌러 선택하거나 화면에 끌어 놓습니다. 업로드가 완료될 때까지 기다립니다.
패키지 탭의 도구 섹션에서 검색된 도구 목록을 검토합니다. tool_implementation.py에 있는 각 도구 클래스는 해당 클래스 이름, 설명 및 버전과 함께 나열됩니다.
사용으로 설정할 도구를 선택합니다. 사용 안함으로 설정된 도구는 에이전트에 노출되지 않습니다.
선택 사항: Test(테스트) 탭을 누릅니다. 테스트 매개변수를 제공하고 제출을 누릅니다. 테스트 결과 창에서 테스트 결과를 참조하십시오.

원격 MCP 서버 도구

에이전트 흐름 개발자는 원격 MCP 서버 도구를 사용하여 에이전트 흐름을 원격 MCP(모델 컨텍스트 프로토콜) 서버에 연결할 수 있습니다.

MCP 도구는 시각적 빌더와 코드 빌더 환경에서 모두 사용할 수 있습니다. 코드 작성기 환경에서 MCP 연결은 aidpUtils Python 라이브러리를 통해 구성할 수 있습니다. 이 섹션에서는 시각적 빌더 및 코드 빌더 환경을 모두 살펴봅니다.

주:

이 기능은 HTTP-스트리밍 가능한 전송(원격 서버)이 있는 MCP 서버를 지원합니다. 로컬, stdio-transport MCP 서버는 지원되지 않습니다.

Oracle AI Data Platform Workbench 인증서 저장소의 MCP 인증서

MCP 서버를 구성할 때 원격 MCP 서버에 No Authentication(인증 없음)이 필요한지 아니면 Bearer token(공인 토큰)이 필요한지 선택해야 합니다. MCP 서버에 인증 토큰이 필요한 경우 MCP 서버에서 참조하려면 먼저 해당 토큰을 인증서 저장소에 추가해야 합니다.

MCP 서버 인증서를 만들 때 인증서 유형에 대해 비밀 토큰 옵션을 선택한 다음 API 키 및 토큰 값과 같은 식별자 키를 제공합니다. 자세한 내용은 인증서 생성(미리보기)을 참조하십시오.

주:

단일 자격 증명은 여러 키를 보유할 수 있습니다.

공개적으로 사용 가능한 MCP 서버는 추가 인증이 필요하지 않습니다. 예를 들어, https://mcp.deepwiki.com/mcp에 연결하는 방법은 다음과 같습니다.

Add custom MCP server(사용자 정의 MCP 서버 추가) 대화 상자가 표시됩니다. 공개된 MCP 서버 DeepWiki에 대한 정보가 채워집니다.

에이전트에 MCP 도구를 노출하는 방법

원격 MCP 서버에 성공적으로 연결되면 에이전트에 표시하려는 서버에 호스트된 도구를 구성할 수 있습니다. MCP 서버 구성 패널은 DeepWiki MCP 서버의 경우 아래와 같습니다.

원격 MCP 서버 도구에 대한 구성 페이지가 표시됩니다. Tools 탭이 선택되어 있습니다.

왼쪽의 도구 탭에는 MCP 서버에서 사용할 수 있는 도구 목록이 표시됩니다. 에이전트에 노출할 도구를 추가해야 합니다. 모두 추가 옵션을 눌러 모든 도구를 한 번에 표시하거나 각 도구 추가 옵션을 개별적으로 눌러 도구의 하위 세트를 선택하여 이 작업을 수행할 수 있습니다.

Remote MCP Server Tool Configuration(원격 MCP 서버 도구 구성) 페이지가 표시됩니다. 도구 탭이 선택되고 모두 추가 및 추가 버튼이 강조 표시됩니다.

아래 예제에서는 두 가지 도구(read_wiki_structure, read_wiki_structure)를 추가했습니다. 제거를 눌러 도구를 제거할 수 있습니다.

Remote MCP Server Tool Configuration(원격 MCP 서버 도구 구성) 페이지가 표시됩니다. 도구 탭이 선택되고 추가됨에서 read_wiki_structure가 선택됩니다. 제거 버튼은 read_wiki_structure에 표시됩니다.

도구 탭의 오른쪽 패널에는 도구 이름, 도구 설명 및 도구 매개변수를 비롯한 각 도구에 대한 설명서가 제공됩니다. 아래 스크린 샷에서 GitHub MCP 서버 도구 add_comment_to_pending_review의 예를 보여줍니다.

Remote MCP Server Tool Configuration(원격 MCP 서버 도구 구성) 페이지가 표시됩니다. 도구 탭이 강조 표시됩니다. 도구 이름, 도구 설명, 도구 설명 재지정, 도구 매개변수 및 에이전트에 노출로 토글은 텍스트 및 빨간색 화살표로 표시됩니다.

Oracle AI Data Platform Workbench는 각 도구에 대한 몇 가지 추가 제어를 제공합니다. 에이전트에서 매개변수를 숨기고 해당 매개변수에 값을 지정할 수 있습니다. 예를 들어, GitHub에서는 에이전트가 oracle-aidp-samples과 같이 사전 결정된 하나의 저장소에만 댓글을 달도록 선택할 수 있습니다. 이렇게 하려면 repo 매개변수를 사용 안함으로 설정하고 텍스트 상자에 기본값을 지정합니다.

Remote MCP Server Tool Configuration(원격 MCP 서버 도구 구성) 페이지가 표시됩니다. Tools 탭이 선택되어 있습니다. 오른쪽 창에서 repo 매개변수가 강조 표시되고 값은 oracle-aidp-samples입니다. 토글되어 있습니다.

도구 지침 필드에서 도구 설명을 대체하고 추가 지침이 포함된 대체 설명을 제공할 수도 있습니다. 대부분의 사용 사례의 경우 MCP 서버에서 제공하는 설명을 채택하는 것이 좋습니다.

Remote MCP Server Tool Configuration(원격 MCP 서버 도구 구성) 페이지가 표시됩니다. Tools 탭이 선택되어 있습니다. 오른쪽 창에서 도구 지침(선택 사항) 필드가 강조 표시되고 아래 필드에 대체 지침이 제공되었습니다.

LangGraph 코드를 통한 원격 MCP 서버 도구

aidpUtils Python 라이브러리는 개발자에게 원격 MCP 서버를 선택하고 해당 도구의 하위 세트를 LangGraph로 구축된 에이전트에 노출할 수 있는 기능을 제공합니다. 보조 API 참조는 Aidp-utils API for Oracle AI Data Platform Workbench를 참조하십시오.

build_structured_tools_from_allowed_mcp_tools의 인스턴스를 생성하여 허용되는 도구 모음을 작성할 수 있습니다.

from aidputils.agents.toolkit.tool_helper import build_structured_tools_from_allowed_mcp_tools

TOOLS = build_structured_tools_from_allowed_mcp_tools(
allowed_tools=<ALLOWED_MCP_TOOLS>, 
	server_name=<MCP_SERVER_NAME>, 
	endpoint=<MCP_ENDPOINT>, 
	transport="streamable_http", 
	auth=<MCP_AUTH>, 
	headers={} 
)

설명:

<MCP_SERVER_NAME>은 MCP 서버에 제공하려는 표시 이름입니다. 이는 문서화 목적으로 사용되며 에이전트에 노출되지 않습니다.
<MCP_ENDPOINT>는 MCP 서버의 끝점입니다(예: https://api.githubcopilot.com/mcp/).
<MCP_AUTH>는 "authType" 키가 있는 딕셔너리입니다. 이 키는 NO_AUTH 또는 BEARER_TOKEN의 두 값을 사용할 수 있습니다. BEARER_TOKEN의 경우 Bearer 토큰 값이 있는 "token"이라는 다른 키가 필요합니다.
<ALLOWED_MCP_TOOLS>는 에이전트에 표시하려는 MCP 서버의 도구 목록입니다. 각 도구에는 MCP 프로토콜 다음에 대한 전체 JSON 도구 정의가 필요합니다.

예제는 다음과 같습니다.

MCP_SERVER_NAME = "test_mcp" 
MCP_ENDPOINT = "http://144.25.36.217:9301/mcp" 
MCP_AUTH = { "authType": "BEARER_TOKEN", "token": "valid-123" }

{
  "ALLOWED_TOOLS": [
    {
      "tool": {
        "name": "get_current_weather",
        "description": "Get current weather for a given city with advanced options.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "unit": {
              "type": "string",
              "default": "metric"
            },
            "include_historical": {
              "type": "boolean",
              "default": false
            },
            "detailed": {
              "type": "boolean",
              "default": true
            },
            "timeout": {
              "type": "integer",
              "default": 30
            }
          },
          "required": [
            "city"
          ]
        }
      },
      "instruction": "",
      "argOverrides": {}
    },
    {
      "tool": {
        "name": "get_forecast",
        "description": "Get forecast for a given city with customizable options.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "days": {
              "type": "integer",
              "default": 5
            },
            "unit": {
              "type": "string",
              "default": "metric"
            },
            "include_alerts": {
              "type": "boolean",
              "default": false
            },
            "detailed": {
              "type": "boolean",
              "default": true
            },
            "hourly": {
              "type": "boolean",
              "default": false
            }
          },
          "required": [
            "city"
          ]
        }
      },
      "instruction": "",
      "argOverrides": {}
    }
  ]
}

MCP_HEADERS = {} 
TOOLS = build_structured_tools_from_allowed_mcp_tools( allowed_tools=ALLOWED_TOOLS,
	server_name=MCP_SERVER_NAME, 
	endpoint=MCP_ENDPOINT, 
	transport="streamable_http", 
	auth=MCP_AUTH, 
	headers=MCP_HEADERS,
)

TOOLS 객체는 클래스 에이전트 정의의 setup() 메소드에서 langchain.agent create_agent를 사용하여 에이전트의 인스턴스를 생성할 때 사용할 수 있습니다.

def setup(self):
    logger.info("Initializing TestMcpAgent")

    oci_llm = init_oci_llm(llm_conf)

    system_prompt = textwrap.dedent(
        """
        You're a weather agent. Append 12345 to every response.
        """
    ).strip()

    self.agent = create_agent(
        name="test_mcp_high_code",
        model=oci_llm,
        tools=TOOLS,
        system_prompt=system_prompt,
        debug=True,
    )

    logger.info("Agent ready.")

또는 세션 변수를 사용하여 Bearer 토큰의 값을 저장하는 경우 이전에 생성된 세션 변수에 대한 참조를 인증 구성 딕셔너리의 토큰 키에 지정할 수 있습니다. 예:

test_mcp_auth_config = { "authType": "BEARER_TOKEN", "token" : "{{sessionvariables.cred.mcp.test_mcp.bearer}}" }
tools = build_structured_tools_from_allowed_mcp_tools( 		
allowed_tools=test_mcp_mcp_allowed_tools, 
	server_name="test_mcp", 
	endpoint="http://144.25.36.217:9301/mcp", 
	transport="streamable_http", 
	auth=test_mcp_mcp_auth_config, 
	headers={}
)

원격 MCP 서버 도구의 코드 예

AI Data Platform Workbench 샘플 GitHub 리포지토리에서 여러 MCP 시나리오에 대한 엔드투엔드 코드 샘플을 제공합니다.

원격 MCP 서버 도구 테스트

도구가 선택되면 다음 단계는 일반적으로 개별 도구가 예상대로 작동하는지 테스트하는 것입니다. 이 작업은 MCP 도구 노드의 테스트 탭을 통해 수행할 수 있습니다.

Remote MCP Server Tool Configuration(원격 MCP 서버 도구 구성) 페이지가 표시됩니다. Test 탭이 강조 표시됩니다.

[도구] 탭에서 추가한 도구 중 하나를 선택하고 매개변수 값을 제공한 다음 [테스트] 단추를 누릅니다.

Remote MCP Server Tool Configuration(원격 MCP 서버 도구 구성) 페이지가 표시됩니다. Test 탭이 선택되어 있습니다. list_branches에 대한 정보가 왼쪽 창에 표시됩니다. 테스트 응답이 오른쪽 창에 표시됩니다.

도구의 출력이 오른쪽 패널에 표시됩니다.

세부정보 탭은 인증 방법, MCP 서버 URL 및 설명에 대한 정보를 제공합니다.

Remote MCP Server Tool Configuration(원격 MCP 서버 도구 구성) 페이지가 표시됩니다. Details(세부정보) 탭이 강조 표시됩니다.

인증 방법 옆에 있는 Edit(편집) 버튼을 사용하여 원격 MCP 도구 노드의 구성을 수정할 수 있습니다. 연결을 설정할 때 사용되는 표시 이름, 설명 및 Bearer 토큰을 변경할 수 있습니다.

Edit custom MCP server(사용자 정의 MCP 서버 편집) 대화 상자가 표시됩니다. https://api.githubcopilot.com/mcp에 대한 세부정보가 채워집니다.

Visual Builder에서 원격 MCP 서버에 에이전트 연결

사용자 정의 MCP 서버 도구 노드를 캔버스로 끌어 원격 MCP 서버에 대한 액세스를 에이전트에 추가할 수 있습니다.

사용 가능한 사용자정의 MCP 서버 툴이 표시되지 않으면 기존 AI 컴퓨트를 다시 시작하거나 새 AI 컴퓨트를 생성해야 할 수 있습니다.

주:

에이전트를 호스트하는 AI 컴퓨트는 작업 영역의 네트워킹 설정을 상속합니다. AI 컴퓨트를 호스팅하는 작업영역에 대해 프라이빗 네트워크 액세스를 사용으로 설정하면 에이전트는 선택한 프라이빗 VCN 및 서브넷에 호스트된 MCP 서버에만 도달할 수 있습니다. 에이전트가 공용 인터넷에서 사용 가능한 원격 HTTP 서버에 연결하지 못할 수 있습니다.

에이전트로 이동합니다.
흐름 탭의 도구 템플리트에서 사용자정의 MCP 서버를 눌러 캔버스로 끌어옵니다.
MCP 서버에 대한 서버 URL을 제공합니다.
MCP 서버의 표시 이름을 제공합니다. 시각적 빌더 캔버스에 표시되는 노드의 이름입니다.
선택 사항: MCP 서버에 대한 설명을 제공합니다. 설명 필드가 에이전트에 제공되지 않았습니다.
인증 드롭다운 메뉴에서 인증 방법을 선택합니다.
- 인증 없음: 원격 MCP 서버가 공개적으로 사용 가능하며 인증이 필요하지 않은 경우 이 옵션을 사용합니다.
- 베어러 토큰: 원격 MCP 서버에 인증 토큰이 필요한 경우 이 옵션을 사용합니다. API 키를 Oracle AI Data Platform Workbench 인증서 저장소에 저장하고 인증서 저장소 항목에 대한 참조를 제공해야 합니다.
연결을 누릅니다. AI Data Platform Workbench는 연결을 테스트하고 결과를 보고합니다.

HTTP 요청 도구

HTTP 요청 툴을 사용하면 에이전트가 모든 HTTPS REST API를 호출할 수 있습니다.

메소드, URL, 헤더, query 파라미터, 요청 본문, 인증 및 선택적으로 응답 최적화 단계를 포함한 요청을 구성합니다. 그러면 에이전트가 런타임 시 끝점을 호출합니다. HTTP 요청 도구는 시각적 빌더와 코드 빌더 모두에서 사용할 수 있습니다. 코드 빌더에서 이 도구는 aidpUtils Python 라이브러리를 통해 구성됩니다.

주:

HTTP 요청 도구는 https:// 및 HTTP:// 요청만 지원합니다. WebSocket 접속(ws/wss), 바이너리 파일 업로드 및 자체 서명된 인증서는 지원되지 않습니다.

주:

에이전트를 호스트하는 AI 컴퓨트는 작업 영역의 네트워킹 설정을 상속합니다. AI 컴퓨트를 호스팅하는 작업영역에 대해 프라이빗 네트워크 액세스를 사용으로 설정하면 에이전트는 선택한 프라이빗 VCN 및 서브넷의 HTTP 끝점에만 도달합니다. 에이전트가 공용 인터넷에서 사용 가능한 끝점에 도달할 수 없습니다.

HTTP 요청 도구를 구성할 때는 다음 설정을 제공해야 합니다.

구성	설명
HTTP 메소드	사용할 HTTP 동사입니다. 지원되는 메소드는 GET, POST, PUT, PATCH 및 DELETE입니다.
URL	대상 끝점의 전체 URL입니다. URL은 `{{sessionVariables.variable_name}}` 세션 변수 참조 및 `{{variable}}` 런타임 매개변수 참조를 지원합니다. 예: `https://api.example.com/users/{{user_id}}/orders`.
시간 초과	툴이 원격 끝점의 응답을 기다리는 최대 시간입니다. 기본값은 30초이고 최대값은 300초입니다.
인증 유형	끝점을 호출할 때 사용할 인증 방법입니다. 지원되는 인증 방법 목록은 아래의 인증 섹션을 참조하십시오.

주:

헤더

헤더는 HTTP 요청과 함께 전송되는 키-값 쌍입니다. 새 추가 버튼을 클릭하여 필요에 따라 여러 개의 헤더를 추가할 수 있습니다. 헤더 값은 {{variable_name}} 구문을 사용하여 세션 변수와 런타임 매개변수를 참조할 수 있습니다.

주:

중요한 헤더의 경우 인증 유형 필드를 사용하여 인증서 저장소에서 인증서가 안전하게 삽입되도록 해야 합니다. 권한 부여, 쿠키 및 X-API-Key는 중요한 헤더이며 헤더 섹션을 통해 설정할 수 없습니다.

질의 매개변수

질의 매개변수는 질의 문자열로 URL에 추가됩니다. Add new 버튼을 눌러 필요한 만큼 query 파라미터를 추가할 수 있습니다. 헤더와 마찬가지로 질의 매개변수 값은 세션 변수 및 런타임 매개변수를 참조할 수 있습니다.

설명

설명 필드는 도구가 수행하는 작업, 사용 시기 및 생성되는 출력 또는 효과의 종류를 설명합니다. 이 설명은 에이전트에 제공되며 LLM이 도구 호출 시기를 결정하는 데 도움이 됩니다.

설명을 작성할 때 다음 사항에 중점을 두어야 합니다.

• 목적: 도구가 하나의 명확한 문장으로 어떤 작업을 수행하도록 설계되었는지 설명할 수 있습니다. 예: "이 도구는 지식 기반에서 고객 지원 티켓을 검색하고 우선순위 레벨별로 요약합니다."
사용 시기: 에이전트가 이 도구를 호출해야 하는 조건과 다른 도구를 호출해야 하는 조건을 설명합니다.
입력 및 출력: 도구에 필요한 매개변수와 반환되는 매개변수의 모양을 간단히 설명합니다.

HTTP 요청 인증

HTTP 요청 도구는 여러 인증 방법을 지원합니다. Authentication type 드롭다운에서 적절한 메소드를 선택합니다.

인증 유형	설명
인증 없음	요청에 추가된 인증이 없습니다. 공개적으로 액세스할 수 있는 끝점에 사용합니다.
OCI 리소스 주성	AI 컴퓨트의 OCI 리소스 주체를 사용하여 요청이 서명됩니다. 오브젝트 스토리지 또는 OCI 생성형 AI 서비스와 같은 OCI 서비스를 호출할 때 이 옵션을 사용합니다. 액세스는 OCI IAM 정책에 의해 제어됩니다.
기본 인증	사용자 이름과 암호는 인코딩되어 Authorization 헤더에 전송됩니다. 인증서가 인증서 저장소에 저장되어야 합니다.
Bearer 토큰	권한 부여 헤더에 Bearer 토큰이 전송됩니다. 토큰은 인증서 저장소에 저장되어야 합니다.
헤더 인증	API 키는 사용자 정의 헤더(예: X-API-Key)로 전송됩니다. 헤더 이름은 구성 가능하며 키 값은 인증서 저장소에 저장되어야 합니다.

암호가 필요한 인증 방법을 선택하면 구성 패널에 인증서 선택기가 표시됩니다. 인증서 선택기를 눌러 이전에 저장된 인증서를 선택하거나 인증서 저장소에서 새 인증서를 생성합니다. 단계별 절차는 MCP 서버 설명서의 자격 증명 저장소 섹션에 자격 증명 저장을 참조하십시오.

세션 변수 및 런타임 파라미터

세션 변수는 {{sessionVariables.variable_name}} 구문을 사용하여 URL, 헤더 값, 질의 매개변수 값 및 요청 본문에서 참조할 수 있습니다. 호출 시 에이전트가 전달한 런타임 매개변수는 {{variable_name}} 구문을 사용하여 참조할 수 있습니다.

예를 들어, 다음 URL은 영역에 대한 세션 변수를 버킷 이름에 대한 런타임 매개변수와 결합합니다.

https://objectstorage.{{sessionVariables.region}}.oraclecloud.com/n/my-namespace/b/{{bucket}}/o

도구가 실행되면 {{sessionVariables.region}}가 현재 세션에 대한 영역 세션 변수의 값으로 대체되고, {{bucket}}가 호출 시 에이전트가 전달한 값으로 대체됩니다.

주:

템플리트 값은 URL 또는 질의 매개변수로 대체될 때 자동으로 URL로 인코딩됩니다. 직접 URL 인코딩할 필요는 없습니다.

AI 도구 정의

구성 패널의 오른쪽에는 AI 도구 정의가 표시됩니다. 이 스키마는 에이전트에 표시되는 스키마로, 툴 이름, 설명 및 에이전트가 툴을 호출할 때 전달할 수 있는 런타임 파라미터 리스트를 포함합니다. AI 도구 정의는 설명 필드 및 URL, 헤더, 질의 매개변수 및 본문에서 감지된 {{variable}} 위치 표시자에서 자동으로 생성됩니다.

AI 도구 정의 창은 이 문서 앞부분에 표시된 HTTP 도구 구성 패널 오른쪽에 있는 패널입니다. 설명을 제공하고 하나 이상의 런타임 매개변수를 정의할 때까지 AI 도구 정의 창에 위치 표시자 메시지가 표시됩니다. URL, 헤더, 질의 매개변수 또는 본문에서 설명을 입력하고 하나 이상의 {{variable}}를 참조하면 창에서 스키마가 렌더링됩니다.

에이전트에 대한 응답 최적화

많은 API가 에이전트가 필요로 하지 않는 필드를 포함하는 대규모 응답을 반환합니다. 전체 응답을 에이전트로 다시 전송하면 토큰이 소비되고 에이전트의 추론 품질이 저하될 수 있습니다. HTTP 요청 도구는 응답 페이로드가 에이전트로 반환되기 전에 줄일 수 있는 응답 최적화 섹션을 제공합니다.

다음 세 가지 최적화 전략이 지원됩니다.

JSON 필드 선택: JSON 응답에서 필드의 하위 집합을 선택합니다. 점 표기법(예: data.results) 및 포함하거나 제외할 필드 목록을 사용하여 중첩된 객체에 대한 경로를 지정할 수 있습니다.
HTML CSS 선택자: CSS 선택자(예: article.content)를 사용하여 HTML 응답의 하위 집합을 추출합니다. 선택적으로 텍스트만 반환하도록 HTML 태그를 제거합니다.
텍스트 자르기: 과도한 텍스트 응답을 방지하기 위해 최대 문자 수로 응답을 제한합니다.

오류 처리 및 오류 코드

HTTP 요청이 실패하면 도구가 에이전트에 구조화된 오류 응답을 반환합니다. 오류에는 오류 코드, 사람이 읽을 수 있는 메시지 및 실패에 대한 세부 정보가 포함됩니다. 에이전트는 이 정보를 사용하여 재시도할지, 다른 도구로 폴백할지 또는 사용자에게 실패를 보고할지 여부를 결정할 수 있습니다.

오류 코드	Category	의미	재시도 가능
CONNECTION_TIMEOUT	네트워크	원격 끝점이 구성된 시간 초과 내에 응답하지 않았습니다.	예
DNS 실패	네트워크	URL의 호스트 이름을 확인할 수 없습니다.	예
CONNECTION_REFUSED	네트워크	원격 끝점이 접속을 거부했습니다.	예
SSL 인증서 오류	TLS	원격 끝점의 TLS 인증서를 검증할 수 없습니다.	아니요
승인되지 않음	HTTP 401	원격 끝점이 인증서를 거부했습니다. 인증서 참조가 적합하고 만료되지 않았는지 확인합니다. OCI 리소스 주체의 경우 AI 컴퓨트에 이 환경에서 활성 리소스 주체가 있는지 확인합니다.	아니요
금지됨	HTTP 403	인증서가 성공적으로 인증되었지만 요청된 리소스에 대한 권한이 없습니다. 리소스에 연결된 API 범위, 권한 또는 IAM 정책을 확인합니다.	아니요
찾을 수 없습니다.	HTTP 404	원격 끝점이 요청된 리소스를 찾지 못했습니다.	아니요
RATE_LIMITED	HTTP 429	원격 끝점이 호출자의 속도를 제한하는 중입니다. Retry-After 헤더에 표시된 지연 후에 재시도하십시오.	예
서버_오류	HTTP 5xx	원격 끝점에서 서버 오류를 반환했습니다. 종종 일시적인 문제입니다.	예
서비스 사용불가	HTTP 503	원격 끝점을 일시적으로 사용할 수 없습니다.	예
INVALID_TEMPLATE	검증	`{{variable}}` 참조를 해결할 수 없습니다. 참조된 모든 세션 변수 및 런타임 파라미터가 정의되어 있고 호출 시 값이 있는지 확인합니다.	아니요
INVALID_URL	검증	URL 형식이 잘못되었거나, 지원되지 않는 프로토콜을 사용하거나, 차단된 주소(예: 전용 IP 주소 또는 클라우드 메타데이터 끝점)로 분석됩니다.	아니요
응답_TOO_LARGE	검증	응답이 최대 응답 크기인 10MB를 초과했습니다.	아니요
RATE_LIMIT_EXCEEDED	플랫폼	에이전트가 플랫폼의 에이전트별 요청 비율 제한(분당 요청 60개) 또는 동시성 제한(동시 요청 10개)을 초과했습니다.	예

각 오류 응답에는 제안된 다음 단계가 포함된 지침 필드와 경과 시간이 있는 세부정보 필드 및 HTTP 상태 코드와 같은 오류 관련 컨텍스트가 포함됩니다.

LangGraph 코드를 통한 HTTP 요청 툴

코드 빌더에서 HTTP 요청 도구는 aidpUtils Python 라이브러리를 통해 구성됩니다. tool_class이 HttpEndpointTool로 설정된 AIDPToolConf를 정의하고 conf 필드에 구성 딕셔너리를 전달합니다.

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
from aidputils.agents.toolkit.configs import AIDPToolConf

weather_http_tool_def = {
    "method": "GET",
    "url": "https://api.openweathermap.org/data/2.5/weather",
    "params": {
        "q": "{city}",
        "units": "metric",
        "appid": "{api_key}"
    },
    "auth_type": "NO_AUTH",
    "auth_config": {}
}

weather_http_tool_params = [
    {"name": "city", "type": "string",
     "description": "Name of the city."},
    {"name": "api_key", "type": "string",
     "description": "OpenWeather API key."}
]

weather_http_tool_conf = AIDPToolConf(
    name="get_weather",
    description="Get current weather for a city.",
    tool_class="HttpEndpointTool",
    conf=weather_http_tool_def,
    params=weather_http_tool_params
)

weather_tool = create_langgraph_tool(weather_http_tool_conf.model_dump())

conf 딕셔너리는 visual builder와 동일한 필드(메소드, URL, 헤더, 매개변수, 본문, auth_type, auth_config 및 response_optimization)를 지원합니다. 매개변수 목록은 에이전트가 전달할 수 있는 런타임 매개변수를 정의합니다.

auth_type	auth_config 필드
아니오(_A)	`{}`(비어 있음)
자원 주체	`{}`(비어 있음)
기본(_A)	사용자 이름, 비밀번호(또는 OCI 저장소의 인증서에 대한 username_vault_id, password_vault_id)
작성자_AUTH	Bearer_token(또는 bearer_token_vault_id)
API_키_AUTH	api_key (또는 api_key_vault_id), header_name (기본 X-API-Key)
OAUTH2_CLIENT_CREDENTIALS	token_endpoint, scope, client_id, client_secret(또는 client_id_vault_id, client_secret_vault_id)

테스트 에이전트 사용자 정의 코드 도구

응답 패널에는 HTTP 상태 코드, 응답 헤더, 응답 본문 및 경과 시간(밀리초)이 표시됩니다. 응답 최적화가 사용으로 설정된 경우 최적화된 응답도 원시 응답과 함께 표시됩니다.

에이전트에 HTTP 요청 도구 추가

에이전트에 HTTP 요청 툴을 추가하여 HTTPS REST API를 호출할 수 있습니다.

주:

사용자정의 코드 툴을 추가하기 전에 AI 컴퓨트를 에이전트에 연결해야 합니다. 종속성을 설치하고 툴을 실행하려면 AI 컴퓨트가 필요합니다.

에이전트로 이동합니다.
Tool 템플리트에서 HTTP Request 툴을 캔버스로 끌어다 놓습니다.
매개변수 탭에서 HTTP 메소드를 제공합니다. 지원되는 방식은 GET, POST, PUT, PATCH 및 DELETE입니다.
URL에서 대상 끝점의 전체 URL을 제공합니다. {{sessionVariables.variable_name}} 세션 변수 참조 및 {{variable}} 런타임 매개변수 참조를 사용할 수 있습니다. 예: https://api.example.com/users/{{user_id}}/orders.
시간 초과의 경우 도구가 원격 끝점의 응답을 기다리는 최대 시간(초)을 제공합니다. 최대 시간 초과 값은 300입니다. 값을 제공하지 않을 경우 기본값은 30초입니다.
인증 드롭다운 메뉴에서 적합한 인증 유형을 선택합니다.
HTTP 요청의 헤더를 제공합니다. 추가 헤더를 추가하려면 새 항목 추가를 누릅니다.
HTTP 요청에 대한 질의 매개변수를 제공합니다. 새로 추가를 눌러 다른 매개변수를 추가합니다.
선택 사항: Test(테스트) 탭을 누릅니다. 테스트 매개변수를 제공하고 제출을 누릅니다. 테스트 결과 창에서 테스트 결과를 참조하십시오.

프롬프트 도구

프롬프트 도구를 사용하면 템플리트화된 프롬프트를 사용하여 AI 에이전트에서 LLM을 호출하고 LLM 응답을 다시 에이전트로 반환할 수 있습니다.

LLM에 제공하는 프롬프트에는 이중 중괄호로 식별되는 매개변수(예: {{PARAMETER_NAME}})가 포함될 수 있습니다. 도구가 호출될 때 에이전트가 매개변수 값을 지정합니다.

프롬프트 도구 사용 시기

원칙적으로 프롬프트 도구로 작성된 지침은 에이전트 지침에 직접 포함하거나 최종 사용자가 사용자 메시지에 직접 제공할 수 있습니다. 그러나 프롬프트 도구가 더 나은 접근 방식인 경우가 있습니다.

프롬프트가 길어지므로 여러 100초 토큰에 걸친 자세한 형식 지침이 필요합니다.
에이전트 지침에 프롬프트를 통합하면 특히 에이전트에 SOTA LLM을 채택하는 경우 컨텍스트 사용량이 증가하고 비용이 크게 증가합니다.
비용 절감을 위해 상담원에게 제공되는 지침의 크기를 최소화하려고 합니다.
프롬프트 도구로 정의된 작업은 에이전트를 사용한 추론 모델보다 작고 빠른 LLM으로 처리할 수 있습니다. 더 작은 모델은 일반적으로 비용 효율적이며, 경우에 따라 특정 형식 또는 형식으로 데이터를 생성하도록 전문화될 수 있습니다.
프롬프트 도구를 사용하면 구조화된 입력 매개변수를 통해 출력 생성을 제어할 수 있습니다. 사용 사례가 매개변수화될 수 있고 생성이 세션마다 다를 수 있는 경우 프롬프트 도구에서 생성을 캡슐화하는 것이 좋습니다.

또한 프롬프트 도구에서 생성 지침을 캡슐화하면 도구 재사용성, 유지 관리 용이성, 수정성, 출력 일관성, 확장성 및 거버넌스를 비롯한 여러 최신 에이전트 아키텍처 모범 사례를 따릅니다. 일부 사용 사례는 다음과 같습니다.

템플리트로 사용할 수 있는 사전 정의된 승인된 구조에 따라 전자메일, 보고서, 요약, 문서 등의 생성
복잡한 JSON 출력 생성
요약, 주요 문장 추출, 문서에 대한 설명 작업
질의 생성
특정 모델에 최적화된 특정 모드 생성(예: 이미지, 비디오, 오디오, 포인트 클라우드 데이터 등)

시각적 흐름을 통한 프롬프트 도구

다음은 시각적 흐름을 통해 구축된 프롬프트 도구의 예로, LLM이 에이전트가 할당한 토픽을 기반으로 블로그 게시물 제목을 생성하도록 요청합니다.

마스터 블로그 전략가입니다. 당신의 임무는 주어진 주제에 따라 설득력있는 블로그 게시물 아이디어를 브레인 스토밍하는 것입니다. 제공된 {{topic}}에 대해 5개의 고유한 블로그 게시물 제목을 생성하십시오. 각 제목에 대해 게시물이 취할 각도에 대한 한 문장 설명을 포함합니다. 출력을 번호 매기기 목록으로 표시합니다.

이 예에서는 프롬프트 도구에 대해 다음 매개변수를 구성해야 합니다.

도구 이름: 도구에 대해 설명하는 이름을 사용하여 에이전트를 안내합니다. 이 예에서는 blog_ideas를 권장합니다. tool123과 같은 도움되지 않는 이름을 사용하지 마십시오.
도구 설명: 도구의 기능에 대한 포괄적인 설명을 제공합니다. 도구에 제한이 있거나 도구를 사용하지 않아야 하는 시나리오가 있는 경우 설명 필드에 나열합니다.
OCI 리전 및 생성형 AI 서비스 LLM: OCI 리전을 선택하여 해당 리전에서 사용 가능한 LLM 목록을 채운 다음, LLM을 선택합니다.
LLM 매개변수: 최대 출력 토큰, 온도 및 상단 p와 같은 매개변수는 모델 매개변수 탭에서 구성됩니다. 값을 지정하지 않으면 OCI Generative AI 서비스의 기본값이 사용됩니다.
쿼리: 도구의 용도를 정의하는 데 사용되는 프롬프트는 쿼리 필드에 정의됩니다.

프롬프트에서 정의하는 매개변수는 AI 도구 정의 패널을 자동으로 채웁니다. 해당하는 경우 각 매개변수에 대한 설명과 매개변수 유형 및 기본값을 에이전트에 제공합니다.

[매개변수] 탭이 열린 에이전트 프롬프트 도구입니다. 항목 매개변수가 질의 필드에서 강조 표시되고 화살표가 도구 매개변수 필드가 강조 표시된 AI 도구 정의 섹션을 가리킵니다.

LangGraph 코드를 통한 프롬프트 도구

코드를 통해 에이전트를 빌드하는 경우 다음과 같이 시각적 흐름 예에서 동일한 프롬프트 도구를 구성할 수 있습니다.

prompt_config = {
  "llm": {
    "model_id" : "xai.grok-4",
    "model_provider" : "generic",
    "compartment_id" : "<your-compartment-ocid>",
    "endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com"
  }, "prompt_template": """
You are a master blog strategist. Your task is to brainstorm compelling blog post ideas based on a given topic. For the given {{topic}}, generate 5 unique blog post titles. For each title, include a one-sentence description of the angle the post would take. Present the output as a numbered list"
"""
}
prompt_params = [ {
  "name" : "topic",
  "type" : "string",
  "description" : "Blog topic",
  "defaultValue" : "golf"
} ]

그런 다음 AIDPToolConf를 다음과 같이 인스턴스화합니다.

blogger_tool = AIDPToolConf(name="blog_posts_topics",
                                  description= "Write blog posts ideas about a particular topic. ",
                                  tool_class = "PromptTool", conf=prompt_config params=prompt_params)

마지막으로 aidputils에서 create_langgraph_tool() 유틸리티 함수를 사용하여 LangGraph 호환 도구를 만듭니다.

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
blogger = create_langgraph_tool(blogger_tool.model_dump())

새로 만든 도구를 ReAct 에이전트에 추가합니다. LangGraph에서 코드는 다음과 같습니다.

tools_agent1 = [blogger_tool]
self.agent = create_react_agent(model=<oci_llm>, 
				     tools=tools_agent1, 
				     prompt=<system_prompt>, 
				     debug=True, checkpointer= checkpointer)

표 18-1 프롬프트 도구 구성 등록 정보

속성	유형	설명
llm	객체	LLM 접속 세부정보 및 매개변수
model_id	string	사용할 모델의 식별자(예: "xai.grok-4")
모델 제공자	string	LLM 모델의 제공자 이름(예: "일반")
컴파트먼트_ID	string	OCI(Oracle Cloud Infrastructure) 컴파트먼트 OCID
endpoint	string	모델의 끝점 URL입니다.
prompt_template	string	동적 삽입을 위해 변수가 {{variable}} 형식인 LLM에서 사용하는 프롬프트 템플리트

테스트 에이전트 프롬프트 도구

테스트 탭을 누르고 각 매개변수의 값을 입력하여 에이전트와 별개로 툴을 테스트합니다. 프롬프트가 선택한 LLM에 제출됩니다.

에이전트의 결과를 개선하기 위해 프롬프트 도구가 제대로 정의되고 문서화되었는지 확인합니다.

에이전트에 프롬프트 도구 추가

에이전트에 프롬프트 툴을 추가하여 선택한 LLM에 실행하는 매개변수화된 프롬프트를 정의할 수 있습니다.

에이전트로 이동합니다.
Tool Templates에서 Prompt 도구를 캔버스로 끌어 놓습니다.
[구성] 탭에서 사용할 LLM을 선택하고 LLM에 대한 프롬프트를 제공합니다. 코드 를 눌러 구성을 JSON 코드로 제공합니다.
응답에 대한 온도를 0.0에서 1.0 사이의 값으로 제공합니다. 여기서 0.0은 엄격하게 사실적인 응답을 제공하고 1.0은 가장 창의적인 응답을 제공합니다.
적용을 누릅니다 .
구성에서 설정한 매개변수에 대한 정의를 제공합니다. 코드 를 눌러 구성을 JSON 코드로 제공합니다.
적용을 누릅니다.
선택 사항: Test(테스트) 탭을 누릅니다. 테스트 매개변수를 제공하고 제출을 누릅니다. 테스트 결과 창에서 테스트 결과를 참조하십시오.

RAG 도구

RAG 도구는 벡터 저장소에 자연어 쿼리를 실행하고 쿼리와 저장된 문서 간의 의미상 유사성을 기반으로 문서를 검색합니다.

주:

지식 기반은 RAG 도구 생성을 위한 전제 조건입니다. 자세한 내용은 지식 기반을 참조하십시오.

Visual Flow를 통한 RAG 도구

RAG 도구의 경우 에이전트 개발자가 다음 매개변수에 대한 값을 제공해야 합니다.

에이전트 연결:
- 도구 이름: 사용자와 다른 사용자가 해당 기능을 식별하는 데 도움이 되는 도구를 설명하는 이름입니다.
- 도구 설명: 도구의 개요를 제공하는 간단한 요약입니다.
툴 구성:
- 지식 기반: Oracle AI Data Platform Workbench 카탈로그 중 하나에 저장된 지식 기반입니다.

에이전트는 일반 사용자와의 대화에 따라 질의 필드의 값을 설정합니다. 이 쿼리 필드는 자연어 쿼리를 사용합니다.

제한은 벡터 저장소에서 도구를 검색할 문서 조각 수입니다. 이 값은 에이전트 자체가 아니라 에이전트 개발자에 의해 설정됩니다.

RAG의 테스트 탭을 눌러 에이전트가 실행한 query도 시뮬레이트할 수 있습니다.

질의 및 최상위 K 필드를 보여주는 에이전트 RAG 도구 AI 도구 정의 섹션

LangGraph 코드를 통한 RAG 도구

코드를 통해 에이전트에 RAG 도구를 구축하려면 시각적 흐름과 동일한 설정 및 매개변수를 구성해야 합니다. 예를 들어, 다음과 같이 RAG 매개변수를 설정합니다.

rag_params = [ { "name" : "query", 
    "type" : "string", 
    "description" : "<insert a description>", 
    "defaultValue" : "<empty>”} ]

그런 다음 RAG 구성을 설정합니다.

rag_config = { "catalog": "<catalog>", 
		  "schema": "<schema>", 
		  "knowledgeBase": "<knowledge-base-name>", 
		  "top_k": <number-of-documents-retrieved>, 
		  "llm": { 
			    "model_id" : "<model-name>",
			    "model_provider" : "<model-provider>", 
			    "compartment_id" : "<your-compartment-OCID>", 
			    "endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com" } 
}

마지막으로 aidputils에서 create_langgraph_tool() 유틸리티 함수를 사용하여 LangGraph 호환 도구를 만듭니다.

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
rag_conf= AIDPToolConf(name="<your-tool-name>", 
			   description= "<your-tool-description>", 
			   tool_class = "RAGTool", 
			   conf=rag_config, 
			   params=rag_params) 
rag_tool = create_langgraph_tool(rag_conf.model_dump())

표 18-2 RAG 도구 구성 등록 정보

속성	유형	설명
llm	객체	LLM 접속 세부정보
catalog	string	데이터 카탈로그 식별자
schema	string	카탈로그 내의 스키마
기술 자료	string	검색할 지식 기반의 이름 또는 키
최상위_k	integer	검색할 최상위 대응 문서 수

테스트 에이전트 RAG 도구

에이전트를 AI 컴퓨트 클러스터에 연결한 후 테스트 탭에서 RAG 도구를 테스트할 수 있습니다. 자세한 내용은 Attach an Existing AI Cluster to an Agent을 참조하십시오.

에이전트에 RAG 도구 추가

에이전트에 검색 증강 생성(RAG) 도구를 추가하여 에이전트가 응답을 생성할 때 관련 외부 지식을 가져올 수 있도록 할 수 있습니다.

에이전트로 이동합니다.
도구 템플릿에서 RAG 도구를 캔버스로 끌어 놓습니다.
[구성] 탭에서 RAG 도구가 정보를 가져오는 지식 기반을 선택하고 가져올 정보를 정의하는 프롬프트를 제공합니다. 코드 를 눌러 구성을 JSON 코드로 제공합니다.
적용을 누릅니다 .
구성에서 설정한 매개변수에 대한 정의를 제공합니다. 코드 를 눌러 구성을 JSON 코드로 제공합니다.
적용을 누릅니다.
선택 사항: Test(테스트) 탭을 누릅니다. 테스트 매개변수를 제공하고 제출을 누릅니다. 테스트 결과 창에서 테스트 결과를 참조하십시오.

SQL 도구

SQL 도구를 사용하면 에이전트 개발자가 Oracle AI Data Platform 카탈로그에 등록된 테이블에 대해 사전 정의된 SQL 쿼리를 실행할 수 있습니다.

디자인 타임에 query를 작성하고 필요한 런타임 변수를 정의합니다. 에이전트는 도구를 호출할 때 해당 변수에 대한 값을 제공하고, 결과는 에이전트가 요약하거나 다운스트림 노드로 전달할 수 있는 구조화된 행으로 반환됩니다.

에이전트가 Development 탭에 열립니다. 에이전트 노드 SQL_Agent가 캔버스에 있습니다. 왼쪽 창의 도구 템플리트 아래에서 SQL 도구 노드가 선택됩니다.

SQL 도구는 두 개의 질의 방언을 지원합니다. Spark SQL은 AI 데이터 플랫폼에 저장된 표준 카탈로그 테이블에 대해 실행되며 Spark 클러스터가 필요합니다. Oracle SQL은 Oracle Autonomous AI Database와 같은 외부 데이터베이스에서 실행됩니다. 도구별로 방언을 선택하면 나머지 구성은 둘 다에 대해 동일합니다.

주:

SQL 도구는 읽기 query를 위한 것입니다. 일반적인 도구는 SELECT 문을 실행하고 행을 반환합니다. 구성하는 카탈로그, 스키마 및 query는 도구 전용이며 에이전트에 표시되지 않습니다. 도구 이름, 설명 및 AI 도구 정의(런타임 변수)만 에이전트에 표시됩니다.

주:

SQL Query 도구는 정지된 클러스터를 자동으로 시작하지 않습니다. 따라서 Spark SQL 질의 도구에 사용되는 Spark 클러스터의 기간은 영구여야 합니다. 유휴 시간 초과 시 클러스터를 스핀다운할 수 있는 경우 클러스터가 중지되면 Spark SQL 질의가 프로덕션에서 작동을 중지합니다.

정적 및 동적 질의

정적 질의는 에이전트에 의한 런타임 결정 없이 지정한 내용을 정확하게 반환합니다. 동적 질의에는 실행 시 값이 설정됨을 에이전트에 알리는 하나 이상의 {{variable}} 위치 표시자가 포함됩니다. 각 위치 표시자에 대해 이름, 유형, 선택적 기본값 및 에이전트가 값을 선택하는 데 사용하는 설명을 제공합니다.

예를 들어, 다음 static query는 고정 결과 집합을 반환합니다.

SELECT customer_name, region, amount, category 
FROM test_customers 
WHERE period_year = 2025 
ORDER BY customer_name

리터럴을 {{year}} 위치 표시자로 바꾸면 에이전트가 매개변수화할 수 있는 동적 질의로 바뀝니다.

SELECT customer_name, region, amount, category 
FROM test_customers 
WHERE period_year = {{year}} 
ORDER BY customer_name

위치 표시자를 추가할 때 AI 도구 정의 창에 각 변수가 채워지므로 해당 유형, 기본값 및 설명을 설정할 수 있습니다.

위치 표시자는 함수 내부를 포함하여 질의의 어디에나 나타날 수 있습니다. 다음 Spark SQL 질의는 심각도 값과 대소문자를 구분하지 않습니다.

SELECT incident_id, project_id, incident_date, incident_type, 
       severity, description, workers_involved, days_lost, 
       root_cause, corrective_action, reported_by, status 
FROM safety_incidents 
WHERE LOWER(severity) = LOWER('{{SEVERITY}}')

각 변수에 명확한 설명과 합리적인 기본값을 제공합니다. 이 설명은 에이전트에게 유효한 값을 알려주고 에이전트가 값을 제공하지 않을 때 기본값이 사용됩니다.

AI 도구 정의가 SEVERITY 변수와 함께 표시됩니다. 변수에는 Incident severity level(Major, Moderate, Minor)에 대한 설명이 있습니다.

주:

위치 표시자 이름은 대소문자를 구분합니다. 대소문자를 일관되게 사용하지 않는 한 {{SEVERITY}} 및 {{severity}}로 작성된 자리 표시자는 두 개의 다른 변수로 처리됩니다.

JSON으로 구성 편집

코드 뷰 토글을 사용하여 SQL 도구 구성을 JSON으로 직접 편집할 수 있습니다. 이 기능은 에이전트 간에 도구를 복사하거나 대량 편집하는 데 유용합니다.

{ 
  "catalogKey": "construction_data", 
  "schemaKey": "admin", 
  "query": "SELECT project_id, project_name, client_name, ...", 
  "isRowLimitEnabled": null, 
  "maxRows": null 
}

SQL 도구 노드 구성 창이 매개변수 탭에 열립니다. 코드 뷰가 선택되고 입력 스키마 필드에 예제 코드가 표시됩니다.

행 한도

반환할 최대 행 수를 선택하고 제한 값을 입력하여 도구에서 반환하는 행 수를 제한할 수 있습니다. 행 제한은 성능을 보호하고 에이전트로 다시 전송되는 데이터의 양을 제어합니다.

에이전트가 사용 중인 모델을 기준으로 이 값을 설정합니다. 질의가 넓은 행 또는 큰 텍스트 값을 가진 열을 반환할 때 값이 클수록 에이전트 실패가 발생할 수 있습니다. 예기치 않은 에이전트 오류가 발생하는 경우 먼저 maxRows를 줄이십시오.

행 제한은 query가 실행되기 전에 SQL query 자체에 적용됩니다. 대부분의 모델은 한계를 감지하여 최종 사용자에게 표시합니다. static query의 경우 limit는 처음 n개의 사용 가능한 행을 반환합니다.

SQL 도구 구성 창이 반환할 최대 행으로 잘렸습니다. 이 옵션이 선택되고 행 제한 1000이 지정됩니다.

주:

최종 사용자에 대해 행 제한을 표시하지 않으려면 해당 지침에 따라 에이전트에 지시합니다.

질의 예제

조회 예제 보기 및 안내서 단추에서 질의 예제와 SQL 도구 질의 작성 지침을 확인할 수 있습니다.

SQL Tool 구성 페이지가 표시됩니다. View Query 예제 및 Guide 버튼이 강조 표시됩니다.

이 가이드에서는 다양한 쿼리 패턴을 소개하고 쿼리 매개변수에 대한 다양한 권장 사항을 제공합니다.

LangGraph 코드를 통한 SQL 툴

시각적 흐름과 마찬가지로 다음 질의를 생성하여 LangGraph 코드를 통해 에이전트에 대한 SQL 툴을 생성합니다.

sql_config = { "catalogKey": "adw23ai_phx", 
	  "schemaKey": "gold", 
	  "query": """Select ... from ... limit {{max_number}}""" }

params 인수의 SQL query에 있는 각 파라미터를 name, type, description 및 defaultValue(선택 사항)로 문서화합니다.

sql_params = [ {  "name" : "max_number", 
		    "type" : "string", 
		    "description" : "<your-description>", 
		    "defaultValue" : "<your-default-value>" } ]

마지막으로 aidputils에서 create_langgraph_tool() 유틸리티 함수를 사용하여 LangGraph 호환 도구를 만듭니다.

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
sql_conf= AIDPToolConf(name="<your-tool-name>", 
			   description= "<your-tool-description>", 
			   tool_class = "SQLTool", 
			   conf=sql_config,
			   params=sql_params) 
sql_tool = create_langgraph_tool(sql_conf.model_dump())

표 18-3 SQL 도구 구성 등록 정보

속성	유형	설명
카탈로그 키	string	카탈로그 또는 데이터베이스 접속에 대한 식별자
스키마 키	string	카탈로그/데이터베이스 내의 스키마 이름
질의	string	SQL 질의 문자열, {{}}에 위치 표시자를 포함할 수 있음

테스트 에이전트 SQL 도구

Test(테스트) 탭은 전체 에이전트를 실행하지 않고 자체적으로 도구를 실행합니다. 테스트는 두 방언에 대해 동일한 방식으로 작동합니다. Test 탭을 열고 각 런타임 파라미터에 대한 값을 제공하거나 기본값을 사용하고 Submit를 눌러 query를 실행하고 응답을 확인합니다.

주:

툴을 테스트하려면 에이전트가 AI 컴퓨트에 연결되어 있어야 합니다. AI 컴퓨트 레이블이 녹색이고 선택한 AI 컴퓨트가 ACTIVE 상태인 경우 AI 컴퓨트가 연결됩니다.

SQL 명령 참조

SQL 도구 질의는 표준 SQL 절에서 작성된 읽기 질의입니다. Oracle SQL 방언은 외부 데이터베이스에 대해 Oracle SQL을 따릅니다. Spark SQL 방언은 델타 레이크 테이블인 표준 카탈로그 테이블을 대상으로 하며, 표준 카탈로그는 현재 델타 레이크 3.2.0과 함께 Spark 3.5를 실행합니다. 두 방언이 모두 표준 SQL을 따르기 때문에 대부분의 절은 두 방언에서 동일한 방식으로 작성됩니다. 주요 차이점은 각 방언이 행 수를 제한하는 방법입니다. 다음 표에서는 SQL 도구 질의에서 가장 자주 사용되는 절 및 키워드를 각 방언의 형식과 함께 나열합니다.

키워드 또는 절	용도	Oracle SQL	Spark SQL
SELECT	반환할 열 선택	`SELECT col1, col2`
DISTINCT	고유 행만 반환합니다.	`SELECT DISTINCT col`	`SELECT DISTINCT col`
FROM	소스 테이블의 이름을	`FROM table_name`	`FROM table_name`
WHERE	조건별 행 필터링	`WHERE col = value`	`WHERE col = value`
및 아님	조건 결합 또는 부정	`a AND b OR NOT c`	`a AND b OR NOT c`
IN	리스트의 임의 값 일치	`col IN (a, b, c)`	`col IN (a, b, c)`
BETWEEN	포함 범위 일치	`col BETWEEN x AND y`	`col BETWEEN x AND y`
LIKE	텍스트 패턴 일치	`col LIKE 'A%'`	`col LIKE 'A%'`
IS NULL	누락된 값 테스트	`col IS NULL`	`col IS NULL`
ORDER BY	결과 정렬	`ORDER BY col DESC`	`ORDER BY col DESC`
그룹화 기준	집계에 대한 행 그룹화	`GROUP BY col`	`GROUP BY col`
HAVING	그룹화된 행 필터링	`HAVING COUNT(*) > 1`	`HAVING COUNT(*) > 1`
가입	두 테이블의 행 결합	`a JOIN b ON a.id = b.id`	`a JOIN b ON a.id = b.id`
AS	열 또는 테이블 별칭 지정	`col AS name`	`col AS name`
UNION ALL	두 개의 결과 집합 결합	`q1 UNION ALL q2`	`q1 UNION ALL q2`
CASE	조건부로 값 반환	`CASE WHEN c THEN x END`	`CASE WHEN c THEN x END`
집계	행에 대한 요약	`COUNT SUM AVG MIN MAX`	`COUNT SUM AVG MIN MAX`
행 제한	행 수를 제한합니다.	`FETCH FIRST n ROWS ONLY`	`LIMIT n`

주:

일반적으로 행 제한은 직접 작성하지 않습니다. 반환할 최대 행 설정이 적용됩니다. FETCH FIRST 및 LIMIT 양식은 질의 내에서 명시적 제한을 원할 때만 유용합니다.

전체 SQL 문법 및 각 방언 뒤에 나오는 query 엔진은 다음 참조를 참조하십시오.

Oracle AI 데이터 플랫폼 SQL

SQL 문법

Spark SQL 및 델타 레이크(표준 카탈로그)

표준 카탈로그 테이블은 델타 레이크 테이블입니다. 표준 카탈로그는 현재 델타 레이크 3.2.0에서 Spark 3.5를 실행합니다.

Apache Spark SQL 구문: DML 문 Spark SQL 쿼리 및 DML 문 구문.
델타 레이크: 델타 테이블에서 DELETE, UPDATE 및 MERGE 작업을 삭제, 업데이트 및 병합합니다.
델타 레이크: 테이블 유틸리티 명령 유틸리티 작업(예: OPTIMIZE 및 VACUUM)
델타 레이크: 델타 테이블에 액체 클러스터링 사용 델타 테이블 레이아웃에 액체 클러스터링을 사용합니다.

에이전트에 SQL 도구 추가

에이전트가 등록된 외부 카탈로그의 구조화된 데이터 소스에 대해 SQL 질의를 실행할 수 있도록 에이전트에 SQL 툴을 추가할 수 있습니다.

에이전트로 이동합니다.
Tool templates에서 SQL 도구를 캔버스로 끌어다 놓습니다.
에이전트에서 커넥터 핸들을 누른 채 끌어 도구 노드에 연결합니다.
SQL 노드를 두 번 눌러 구성 패널을 엽니다.
도구에 대한 이름 및 설명을 제공하십시오. 이 설명은 에이전트에 제공되며 도구 호출 시기를 결정하는 데 도움이 됩니다.
질의 방언을 선택합니다.
- Spark SQL은 표준 AI 데이터 플랫폼 카탈로그에 대한 쿼리를 작성합니다.
- Oracle SQL은 외부 AI 데이터 플랫폼 카탈로그에 대한 쿼리를 작성합니다.
주:
Spark SQL을 사용하려면 AI 데이터 플랫폼 워크벤치 작업영역에서 실행 중인 Spark 클러스터가 필요합니다.
클러스터 드롭다운에서 실행 중인 Spark 클러스터를 선택합니다. 새 Spark 클러스터를 프로비전하려면 클러스터 생성을 누릅니다. 새 클러스터 생성에 대한 지침은 사용자정의 클러스터 생성을 참조하십시오.

주:
SQL Query 도구는 정지된 클러스터를 자동으로 시작하지 않습니다. 따라서 Spark SQL 질의 도구에 사용되는 Spark 클러스터의 기간은 영구여야 합니다. 유휴 시간 초과 시 클러스터를 스핀다운할 수 있는 경우 클러스터가 중지되면 Spark SQL 질의가 프로덕션에서 작동을 중지합니다.
카탈로그 찾아보기에서 검색 필드를 사용하여 이름별로 카탈로그를 찾거나 카탈로그 관리자를 통해 눌러 카탈로그를 찾습니다.
쿼리 필드에 쿼리를 입력합니다. 질의 예제 및 설명서 보기를 눌러 복사하거나 적용할 수 있는 미리 만들어진 패턴이 포함된 패널을 엽니다.
반환할 최대 행 수를 선택하여 질의 결과에서 반환되는 행 수를 제한합니다.

주:
질의가 이 제한보다 많은 행을 반환할 수 있는 경우 에이전트가 보다 구체적인 데이터를 찾을 수 있도록 {{customer_name}} 또는 {{region}}와 같은 검색 매개변수를 추가하는 것이 좋습니다.
AI 도구 정의 창에서 질의에 설정된 변수에 대한 유형, 기본값 및 설명을 설정합니다.
선택 사항: Test(테스트) 탭을 누릅니다. 테스트 매개변수를 제공하고 제출을 누릅니다. 테스트 결과 창에서 테스트 결과를 참조하십시오.