22 AI 에이전트

이 장에서는 작업 영역에서 에이전트를 생성, 테스트, 배치 및 모니터하는 방법에 대한 정보를 제공합니다.

에이전트는 엔드투엔드 에이전트 응용 프로그램입니다. 에이전트는 다양한 유형(트리거, 에이전트, 난간 또는 도구)의 노드로 표시되는 단계 그래프를 통해 정의됩니다. 에이전트는 노코드 시각적 흐름 빌더 및 LangGraph와 같은 타사 라이브러리를 통해 코드를 통해 정의할 수 있습니다.

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

• 사용자 정의 도구: 사용자 정의 코드 도구를 사용하면 에이전트 개발자가 자체 Python 코드로 AI 데이터 플랫폼을 확장할 수 있습니다. 도구 구현을 ZIP 파일로 패키지화하고 작업 영역에 업로드한 다음 구성합니다. 에이전트는 런타임 시 LLM에서 제공하는 매개변수를 사용하여 코드를 도구로 호출합니다.
• HTTP: HTTP 요청 도구를 사용하면 에이전트가 HTTPS REST API를 호출할 수 있습니다. 메소드, URL, 헤더, query 파라미터, 요청 본문, 인증 및 선택적으로 응답 최적화 단계를 포함한 요청을 구성합니다. 그러면 에이전트가 런타임 시 끝점을 호출합니다. HTTP 요청 도구는 시각적 빌더와 코드 빌더 모두에서 사용할 수 있습니다. 코드 빌더에서 이 도구는 aidpUtils Python 라이브러리를 통해 구성됩니다.
• 프롬프트: 프롬프트 도구를 사용하면 AI 개발자가 선택한 LLM에 실행할 수 있는 매개변수화된 프롬프트를 정의할 수 있습니다. 프롬프트 도구의 일반적인 사용 사례에는 전자메일 제도 태스크, 번역 태스크, 스타일 변환, Git 커밋 메시지 및 코드 설명이 포함됩니다.
• 원격 MCP 서버: 에이전트 개발자는 원격 MCP 서버 도구를 사용하여 에이전트를 원격 MCP(모델 컨텍스트 프로토콜) 서버에 연결할 수 있습니다.
• RAG: 에이전트는 RAG 도구를 사용하여 응답을 생성하기 전에 관련 외부 지식을 가져올 수 있습니다. AI 데이터 플랫폼 워크벤치에서 RAG 도구는 지식 기반(23ai Vector Search)을 쿼리하고 의미상 관련된 문서 청크를 검색합니다. 그런 다음 이러한 청크는 응답 생성을 위해 에이전트로 전달됩니다.
• SQL: 에이전트는 SQL 도구를 사용하여 Oracle Autonomous AI Lakehouse, Oracle Autonomous AI Transaction Processing, Oracle AI Database 등 외부 카탈로그를 통해 등록된 구조화된 데이터 소스에 대해 SQL 쿼리를 실행할 수 있습니다. 이 도구는 SQL query가 미리 정의되어 있고 파라메트화할 수 있는 시나리오를 위한 것입니다. 목표는 에이전트가 매개변수에 값을 할당하도록 하는 것입니다. 이 도구는 자연어 프롬프트를 기반으로 SQL query를 생성하는 NL2SQL 도구가 아닙니다.

  주:

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

주:

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

AI 데이터 플랫폼 워크벤치에서 에이전트를 생성하면 선택한 작업영역 폴더에 에이전트 아티팩트 파일(.aflow)이 생성됩니다. 이 파일은 수정할 수 없습니다.

다중 에이전트 시스템 및 상위자 패턴

멀티 에이전트 시스템은 하나의 대규모 다목적 에이전트가 아닌 여러 협력 에이전트가 사용자 요청을 처리하는 AI 응용 프로그램 설계입니다.

각 에이전트에는 고유한 역할, 지침, 모델 구성, 메모리 정책 및 허용된 도구가 있습니다. 플로우는 해당 에이전트 간에 요청이 이동하는 방법과 최종 응답이 생성되는 방법을 정의합니다.

이 설계는 워크플로우가 자연스럽게 전문가의 책임으로 분리되는 경우에 유용합니다. 예를 들어, 한 에이전트가 데이터를 검색하고, 다른 에이전트는 API를 호출하고, 다른 에이전트는 결과를 요약할 수 있고, 감독자는 사용할 전문가를 결정하고 결과를 단일 응답으로 결합할 수 있습니다.

주:

설계 원칙으로서, 요구 사항을 충족하는 가장 작은 에이전트 설계부터 시작하는 것이 가장 좋습니다. 우려 사항이 분리되면 여러 에이전트를 추가하여 신뢰성, 보안, 유지 관리 용이성 또는 가관측성이 비용과 복잡성을 증가시키는 것보다 더 향상됩니다.

다중 에이전트 시스템의 이점

다중 에이전트 시스템은 다음 작업에 가장 적합합니다.

• 전문화: 각 에이전트에게 하나의 붐비는 명령 블록 대신 집중적인 작업, 프롬프트, 도구 집합을 제공합니다.
• 경로 지정 및 분해: 감독자가 요청을 해석하고, 하위 태스크로 분할하고, 각 하위 태스크에 적합한 전문가를 선택할 수 있습니다.
• 도구 및 데이터 격리: 민감한 도구 또는 영향력이 큰 도구는 해당 도구의 사용을 담당하는 에이전트에게만 노출됩니다.
• 거버넌스 및 문제 해결: 핸드오프, 도구 소유권, 메모리 설정 및 장애 지점을 더 쉽게 검사할 수 있습니다.

다중 에이전트 또는 단일 에이전트 설계 선택 시기

도구가 더 많은 단일 에이전트가 종종 올바른 첫 번째 디자인입니다. 테스트하는 것이 더 간단하고, 실행하기가 더 저렴하며, 작업에 명확한 목표와 하나의 권한 모델이 있는 시기에 대해 추론하기가 더 쉽습니다. 워크플로우가 명시적 역할, 제한된 도구 액세스 또는 여러 전문가 출력을 조정할 수 있는 감독자의 이점을 활용하는 경우 다중 에이전트 디자인을 사용합니다.

설계 질문	다음 경우에 단일 에이전트 사용...	다중 에이전트 사용 시기...
태스크 구성	요청에는 하나의 주요 목표와 하나의 응답 세로대가 있습니다.	요청은 전문 분야 전반에서 분해, 라우팅, 검증 또는 합성되어야 합니다.
도구와 데이터	동일한 명령 세트 및 권한 모델이 모든 도구를 안전하게 관리할 수 있음	에이전트마다 다른 도구, 데이터 소스 또는 액세스 경계가 필요합니다.
지침	모든 비즈니스 규칙 및 도구 지침을 한 곳에서 제공하더라도 프롬프트는 명확합니다.	지침은 보다 작은 역할별 프롬프트로 유지 관리하기가 더 쉽습니다.
비용 및 대기 시간	사용자 메시지에서 답변할 가장 짧은 경로가 필요합니다.	안정성, 거버넌스 또는 유지보수 용이성은 추가적인 통합관리를 정당화합니다.
문제 해결	실패는 하나의 추적에서 디버깅하기 쉽습니다.	각 단계에 대한 명시적 핸드오프, 상태 격리 및 명확한 소유권이 필요합니다.

지원되는 패턴: 통합관리자/관리자

현재 캔버스 환경은 통합관리자/상위자 패턴을 지원합니다. 이 패턴에서 채팅 트리거는 사용자 메시지를 수신하고, 선택적 가드레일은 입력을 평가하며, 상위자 에이전트는 나머지 플로우에 대한 통합관리자 역할을 합니다.

감독자는 계획, 라우팅, 위임 및 최종 응답 합성에 중점을 두어야 합니다. 어떤 실행기 에이전트가 작업을 처리해야 하는지 결정하고, 해당 실행기에 범위 지정된 명령을 전송하고, 결과를 검토한 다음 다른 단계를 위임하거나 최종 응답을 반환합니다. 실행기 에이전트는 더 좁은 전문가여야 합니다. 즉, 지정된 작업을 수행하고, 첨부된 도구를 사용하고, 유용한 결과를 상위자에게 반환합니다.

시각적 흐름 캔버스 정보

노드 및 도구 템플리트를 왼쪽 팔레트에서 캔버스로 끌어온 다음 요청이 이동하는 순서대로 노드를 연결하여 에이전트를 어셈블합니다.

노드를 선택하면 화면 하단에 구성 패널이 열립니다.

캔버스 요소	용도
채팅 트리거	사용자 메시지에 대한 시작점입니다. 스크린샷에서 이 노드의 레이블은 Message이며 일반적으로 흐름 상단에 있습니다. 채팅 트리거 노드는 에이전트, 상위자 에이전트 또는 보호자 노드에 연결할 수 있습니다. 캔버스당 하나의 채팅 트리거만 허용됩니다.
가드레일	모델 작업 전후에 배치되는 선택적 정책 및 안전 계층입니다. 가드레일 정책에는 PII, 컨텐트 조정 및 프롬프트 주입 감지가 포함됩니다. 보호자 노드는 채팅 트리거와 에이전트 노드 간, 감독자와 실행자 에이전트 간 또는 에이전트와 도구 노드 간 트래픽을 필터링할 수 있습니다. 채팅 트리거와 에이전트 노드 사이에 단일 보호 한계선 노드를 사용하는 것이 좋습니다.
상위자 에이전트	통합관리자입니다. 사용자 요청을 수신하고, 각 작업을 처리할 실행기 에이전트 또는 도구를 결정하고, 최종 답변을 조정합니다. 하나의 캔버스에 하나의 상위자 에이전트만 허용됩니다.
에이전트	실행기 에이전트입니다. 각 실행자는 데이터 검색, API 조회, 요약 또는 문서 질문 답변과 같은 명확한 전문 지식을 보유하고 있어야 합니다. 단일 에이전트 시스템에 에이전트/실행기 에이전트를 사용합니다.
도구 템플리트	개별 실행기 또는 상위자 에이전트에 연결할 수 있는 재사용 가능한 기능입니다. 도구 템플리트에는 SQL, RAG, Prompt, HTTP, Remote MCP Server 및 Custom Tool이 포함됩니다.
개발/플레이그라운드	캔버스 위의 모드 선택기입니다. 개발은 에이전트 시스템을 편집하는 동안 사용됩니다. Playground는 테스트 세션을 시작하고 에이전트 동작을 검사하는 데 사용됩니다. 플레이그라운드에서 AI 컴퓨트가 에이전트에 연결되어야 합니다.
확대/축소 콘트롤	캔버스 확대/축소 선택기. 스크린샷에는 60% 및 90% 확대/축소 레벨이 표시됩니다.

에이전트 생성

관리 권한이 있는 작업영역에서 에이전트를 생성할 수 있습니다.

1. Home 페이지에서 작업 영역으로 이동합니다.
2. 왼쪽 탐색 창에서 에이전트 플로우를 누릅니다.
3. 에이전트 생성을 누르거나 오른쪽 상단에서 생성을 누릅니다.
   
   

   

   
   
4. 에이전트에 대한 이름 및 설명을 제공하십시오.
5. 에이전트 플로우 작성 모드의 경우 시각적 작성기를 선택합니다.
   
   

   

   
   
6. 선택 사항: AI 컴퓨트 드롭다운 메뉴에서 에이전트에 사용할 컴퓨트를 선택합니다.
7. 생성을 누릅니다. 팔레트에서 캔버스로 노드를 끌어서 에이전트 빌드를 시작합니다.

   주:

   첫 번째 에이전트 빌드를 간단하게 시작합니다. 하나의 채팅 트리거, 하나의 실행기 에이전트입니다. 가드 레일, 추가 도구 또는 다중 에이전트 시스템 설계와 같은 첫 번째 빌드를 성공적으로 실행한 후 복잡성을 추가합니다.

Visual Builder 캔버스에 채팅 트리거 및 에이전트 추가

Visual Builder로 에이전트를 생성한 후 첫번째 단계는 채팅 트리거 및 감독자 에이전트를 추가하는 것입니다.

트리거가 유저 메시지를 수신합니다. 감독자는 요청을 해석하고, 작업을 계획하고, 대리자를 실행자 에이전트나 도구로 만듭니다. 캔버스에서 노드를 끌어서 구성하고 나중에 연결할 수 있습니다.

1. 작업 영역에서 에이전트로 이동합니다.
2. 팔레트에서 채팅 트리거를 눌러 캔버스로 끌어옵니다. 노드가 캔버스에 메시지로 나타납니다.
3. 관리책임자 에이전트를 눌러 캔버스로 끌어옵니다.
   
   

   

   
   
4. [채팅 트리거] 노드에서 커넥터 핸들을 눌러 끌어 에이전트 노드에 연결합니다.

상위자 에이전트 배지에는 연결된 에이전트 및 도구 수가 표시됩니다. 새 빌드에서 상위자 에이전트에 에이전트 (0) 도구 (0)이 표시됩니다.

감독자 에이전트 구성

감독자 역할을 설명하는 지침과 함께 Visual Builder 캔버스에 추가된 감독자 에이전트를 구성해야 합니다.

다음 필드를 사용하여 감독자 에이전트를 구성합니다.

필드	구성
에이전트 이름	상위자 에이전트에 대한 구체적인 이름을 제공합니다. 추적 및 로그를 통해 시스템 동작을 디버깅할 때 유용한 설명형 이름이 사용됩니다.
에이전트 설명	에이전트 목적, 역할 및 일반 동작에 대한 설명을 제공합니다. 설명서용으로 유용합니다.
영역	상위자 에이전트에서 사용되는 OCI 생성형 AI 모델이 호스팅되는 지역을 선택합니다. 지역별 생성형 AI 모델을 참고하세요.
모델	상위자가 사용하는 OCI 생성형 AI 서비스 모델을 선택합니다. 드롭다운에는 선택한 영역에서 사용 가능한 모델이 나열됩니다.
에이전트 지침	감독자 역할, 라우팅 규칙, 위임 정책, 도구 사용 기대치 및 최종 응답 형식을 설명합니다.

1. 작업 영역의 에이전트로 이동합니다.
2. 캔버스에서 감독자 에이전트 노드를 누릅니다.
3. 상위자 에이전트에 대한 간단한 이름 및 설명을 제공합니다.
4. 상위자가 사용하는 OCI 생성형 AI 서비스 모델에 대한 영역 및 모델을 입력합니다.
5. 감독자 에이전트에 대한 에이전트 지침을 제공합니다.

제안된 상위자 지침

감독자 에이전트에 대한 지침 필드를 사용하여 감독자가 모든 태스크 자체를 수행하는 것이 아니라 통합관리를 담당하도록 해야 합니다.

지침을 구체적으로 유지하여 경로 지정 결정을 예측할 수 있도록 합니다. 관리책임자 지침 세트의 예는 다음을 참조하십시오.

You are the supervisor for a multi-agent system.

Responsibilities:
- Understand the user's request and break it into subtasks.
- Select the most appropriate executor agent or tool for each subtask.
- Do not perform specialist work yourself when an executor agent is available.
- Ask for clarification only when required information is missing.
- Combine executor outputs into a concise final answer.
- Mention important assumptions, limits, or failed tool calls in the final answer.

Routing rules:
- Use the SQL agent for structured data questions.
- Use the HTTP agent/tool for external API lookups.
- Use the RAG agent/tool for document or knowledge-base questions.
- Use the prompt tool for reusable prompt-only transformations.

상위자 에이전트 메모리 및 상태 격리 구성

상위자 에이전트의 [메모리] 탭은 상위자가 사용할 수 있는 대화 및 도구 출력 기록의 양과 실행자 에이전트와 공유되는 컨텍스트의 양을 제어합니다.

다음 필드를 사용하여 상위자 에이전트에 대한 메모리 및 격리 상태를 구성합니다.

필드	구성
에이전트 메모리 사용	사용자가 다중 회전 연속성을 필요로 하는 경우 사용으로 설정합니다. 격리된 한 번의 사용 작업에 대해 사용 안함으로 설정합니다. 상위자 에이전트에 대해 이 필드를 사용 안함으로 설정할 수 없습니다.
대화 내역 제한	지정된 제한에 도달한 후 LLM 컨텍스트 창을 자르려면 사용으로 설정합니다. 전체 내역을 표시하려면 사용 안함으로 설정합니다.
자르기 구성	대화 기록 제한이 사용으로 설정된 경우 이 필드를 사용하여 컨텍스트 창을 자르는 조건을 설정합니다. 옵션은 다음과 같습니다. 마지막 N개 메시지 보관 토큰 예산 모두
최대 메시지 한도 및 토큰 예산	자르기 구성에 대해 선택한 옵션에 따라 이러한 옵션 중 하나 또는 둘 다 표시됩니다. 기본값은 20개의 메시지와 5000개의 토큰입니다. 적절한 값으로 시작하고 필요에 따라 조정하는 것이 좋습니다.
실행기 에이전트에 대한 상태 격리	Stateless, Private 또는 Shared를 선택합니다. Stateless: 각 실행기 에이전트는 감독자가 지정한 작업만 봅니다. 호출 사이에 전달된 내역이 없습니다. 가장 강력한 격리 및 최소 에이전트 간 컨텍스트를 원할 경우 선택합니다. 비공개: 각 실행기 에이전트는 자신의 과거 상호 작용만 봅니다. 원래 사용자 대화의 다른 실행기 에이전트는 볼 수 없습니다. 실행기가 자체 작업에서 연속성을 필요로 하지만 컨텍스트를 다른 에이전트와 공유하지 않아야 하는 경우 이 옵션을 선택합니다. 공유: 실행기 에이전트는 에이전트 및 사용자 간에 전체 대화 내역을 볼 수 있습니다. 모든 에이전트는 하나의 공유 컨텍스트에서 작동합니다. 광범위한 컨텍스트 공유가 필요하고 개인 정보 보호 및 신속한 주입 위험을 검토한 경우 이 옵션을 선택합니다.

1. 작업 영역의 에이전트로 이동합니다.
2. 캔버스에서 감독자 에이전트 노드를 누릅니다.
3. 메모리 탭을 누릅니다.
4. 대화 기록 제한을 사용으로 설정할지 여부를 선택합니다. 사용으로 설정된 경우 잘라내기 구성을 선택하고 제한을 설정합니다.
5. 실행기 에이전트에 대한 상태 격리 옵션을 선택합니다.

모델 매개변수 탭

모델 매개변수 탭에서는 선택한 모델에 사용할 수 있는 모델별 매개변수를 구성할 수 있습니다.

모델 매개변수는 상위자 및 실행기 에이전트에 대해 별도로 구성할 수 있습니다. 사용할 수 있는 매개변수에는 온도, 상단 K, 상단 P 및 주파수 페널티가 포함됩니다.

주:

모델의 하위 세트만 구성 가능한 매개변수를 노출합니다. 또한 매개변수는 모델 패밀리에 따라 다릅니다.

에이전트에 가드레일 추가

캔버스에 하나 이상의 난간 노드를 추가하여 에이전트에 보호 계층을 추가할 수 있습니다.

기본적으로 선택한 모델 제공자가 해당 모델에 대해 미리 정의된 기능을 제공하는 것 이상으로 에이전트 시스템에 가드레일이 적용되지 않습니다. 가드레일을 채팅 트리거와 감독자 에이전트 사이에 배치할 수 있으므로 요청이 감독자 에이전트에 도달하기 전과 감독자 에이전트가 호출자에게 응답을 반환하기 전에 정책이 적용됩니다.

난간	옵션	사용 시기
개인 식별 정보(PII)	Input 및 Output 탭 개인, 주소, 전화 번호, 전자메일에 대한 체크박스	플로우가 모델 처리 전후에 민감한 개인 데이터를 차단하거나 숨겨야 하는 경우 사용합니다.
컨텐츠 조정 방지	블록, 정보 및 허용 옵션이 있는 입력 및 출력 행입니다.	흐름이 증오, 성적, 폭력, 독성, 특례 또는 괴롭힘 콘텐츠를 처리하는 방법을 정의하는 데 사용합니다.
프롬프트 주입 감지	블록 및 허용 옵션이 있는 입력 행입니다.	악의적인 지침이 시스템 또는 에이전트 지침을 대체할 가능성을 줄이려면 사용합니다.

난간 설정에 대한 자세한 내용은 가드레일을 참조하십시오.

1. 작업 영역의 에이전트로 이동합니다.
2. 팔레트에서 캔버스로 가드레일 노드를 끌어옵니다. Chat Trigger 노드와 Supervisor Agent 노드 사이에 배치합니다.
3. 연결을 가리키고 빨간색 X를 눌러 Chat Trigger와 Supervisor Agent 간의 연결을 삭제합니다.
   
   

   

   
   
4. Chat Trigger의 커넥터 핸들을 눌러 Guardrail 노드로 끌어옵니다. 그런 다음 커넥터 핸들을 눌러 Guardrail 노드에서 Supervisor Agent로 끌어옵니다.
5. Guardrail 노드를 눌러 Configuration 페이지를 엽니다.
6. 가드레일을 구성하여 입력 및 출력 검사에 대해 원하는 작업을 선택합니다.

에이전트에 실행기 에이전트 및 도구 추가

도구에 실행기 에이전트를 추가하여 상위자 에이전트에 대한 특수 작업을 수행할 수 있습니다.

아래 예에서 상위자 에이전트는 AGENT_1 및 AGENT_2에 위임합니다. AGENT_1은 SQL_1 및 HTTP_1 도구에 연결됩니다.

1. 작업 영역의 에이전트로 이동합니다.
2. 팔레트에서 캔버스로 에이전트 노드를 끌어옵니다. 에이전트 노드는 상위 에이전트 아래에 배치해야 합니다.
3. 팔레트에서 Tools를 캔버스로 끌어옵니다.
4. 상위자 에이전트에서 커넥터 핸들을 누른 채 끌어 에이전트 노드에 연결합니다.
5. 에이전트에서 커넥터 핸들을 누른 채 끌어 도구 노드에 연결합니다.

실행기 에이전트 구성

각 에이전트의 목적을 정의하는 데 도움이 되도록 Configuration(구성), Memory(메모리) 및 Model(모델) 탭에서 설정을 수정하여 에이전트 노드를 구성할 수 있습니다.

특정 기능과 목표를 고려하여 에이전트를 좁게 구성해야 하므로 감독자 에이전트가 안정적으로 작업을 라우팅할 수 있습니다.

표 22-1 에이전트 구성 탭

필드	구성
에이전트 이름	최적의 사용법은 SQL_AGENT, DOCUMENT_AGENT, API_AGENT 또는 SUMMARY_AGENT와 같은 전문 분야에 따라 각 실행기 에이전트의 이름을 지정하는 것입니다. 각 실행기 에이전트의 이름은 상위자 에이전트에 표시되므로 설명적인 이름을 사용합니다.
에이전트 설명	각 실행기 에이전트에 대한 자세한 설명을 제공합니다. 각 실행기 에이전트에 대한 설명은 상위자 에이전트에 표시됩니다.
영역	에이전트가 사용하는 OCI 생성형 AI 모델이 호스팅되는 지역을 선택합니다. 지역별 생성형 AI 모델을 참고하세요.
모델	에이전트가 사용하는 OCI 생성형 AI 서비스 모델을 선택합니다. 드롭다운 메뉴에는 선택한 영역에서 사용할 수 있는 모델이 나열됩니다. 실행기 작업에 맞는 모델을 선택합니다. 실행기 에이전트는 상위자 에이전트와 동일한 모델을 사용할 필요가 없습니다.
에이전트 지침	실행기가 수행해야 하는 작업, 사용할 수 있는 도구 및 반환해야 하는 출력 구조를 정확히 설명합니다.

실행기 에이전트 메모리 탭

상위자 에이전트에 접속된 실행기 에이전트의 경우 실행기 메모리는 상위자 노드에서 구성되고 모든 실행기 에이전트에 적용됩니다.

필드	구성
에이전트 메모리 사용	사용자가 다중 회전 연속성을 필요로 하는 경우 사용으로 설정합니다. 격리된 한 번의 사용 작업에 대해 사용 안함으로 설정합니다.
대화 내역 제한	지정된 제한에 도달한 후 LLM 컨텍스트 창을 자르려면 사용으로 설정합니다. 전체 내역을 표시하려면 사용 안함으로 설정합니다.
자르기 구성	대화 기록 제한이 사용으로 설정된 경우 이 필드를 사용하여 컨텍스트 창을 자르는 조건을 설정합니다. 옵션은 다음과 같습니다. 마지막 N개 메시지 보관 토큰 예산 모두
최대 메시지 한도 및 토큰 예산	자르기 구성에 대해 선택한 옵션에 따라 이러한 옵션 중 하나 또는 둘 다 표시됩니다. 기본값은 20개의 메시지와 5000개의 토큰입니다. 적절한 값으로 시작하고 필요에 따라 조정하는 것이 좋습니다.
실행기 에이전트에 대한 상태 격리	Stateless, Private 또는 Shared를 선택합니다. Stateless: 각 실행기 에이전트는 감독자가 지정한 작업만 봅니다. 호출 사이에 전달된 내역이 없습니다. 가장 강력한 격리 및 최소 에이전트 간 컨텍스트를 원할 경우 선택합니다. 비공개: 각 실행기 에이전트는 자신의 과거 상호 작용만 봅니다. 원래 사용자 대화의 다른 실행기 에이전트는 볼 수 없습니다. 실행기가 자체 작업에서 연속성을 필요로 하지만 컨텍스트를 다른 에이전트와 공유하지 않아야 하는 경우 이 옵션을 선택합니다. 공유: 실행기 에이전트는 에이전트 및 사용자 간에 전체 대화 내역을 볼 수 있습니다. 모든 에이전트는 하나의 공유 컨텍스트에서 작동합니다. 광범위한 컨텍스트 공유가 필요하고 개인 정보 보호 및 신속한 주입 위험을 검토한 경우 이 옵션을 선택합니다.

실행기 에이전트 모델 매개변수 탭

모델 매개변수 탭에서는 선택한 모델에 사용할 수 있는 모델별 매개변수를 구성할 수 있습니다.

주:

모델의 하위 세트만 구성 가능한 매개변수를 노출합니다. 매개변수는 모델 패밀리에 따라 달라집니다.

매개변수의 예로는 온도, 상단 K, 상단 P 및 주파수 페널티가 있습니다. 모델 매개변수는 상위자 및 실행기 에이전트에 대해 별도로 구성할 수 있습니다.

제안된 실행기 지침

You are the SQL executor agent.

Responsibilities:
- Translate the supervisor's task into safe SQL tool usage.
- Use only the SQL tools attached to this agent.
- Return a concise answer plus any important query assumptions.
- Do not invent data. If the tool cannot answer, say what is missing.
- Return structured output with: answer, evidence, assumptions, and follow_up_needed.

Visual Builder를 통한 에이전트 점검 목록

이 목록을 가이드로 사용하여 Visual Builder를 사용하여 구축된 에이전트에 필요한 모든 구성요소를 포함하고 구성했는지 확인하십시오.

빌드 체크리스트

• 에이전트에는 정확히 하나의 예상 시작점인 채팅 트리거/메시지가 있습니다.
• 가드레일은 의도한 위치에서 연결되며 필요한 경우 활성화됩니다. 트리거 메시지와 에이전트 사이에 보호 한계선을 삽입하는 것이 좋습니다.
• 상위자 에이전트에 선택된 영역, 선택된 모델 및 통합관리 지침이 있습니다. 실행기 에이전트와 동일합니다.
• 상위자 에이전트의 Memory(메모리) 탭에서 다중 에이전트 시스템의 메모리를 구성합니다. 프라이버시 및 연속성 요구사항에 맞는 실행기 상태 격리를 선택합니다.
• 각 실행기 에이전트는 명확한 전문성과 좁은 지침을 가지고 있습니다.
• 각 도구는 해당 도구를 사용해야 하는 에이전트에만 연결됩니다.
• 노드가 연결 해제되지 않았습니다.
• AI 컴퓨팅은 개별 도구를 테스트하고 Playground 환경을 실행하기 위해 에이전트 시스템에 연결됩니다.

표 22-2 일반적인 문제

문제	가능성 있는 원인	제안된 작업
상위자가 실행기를 호출하지 않습니다.	감독자 지침이 너무 모호하거나 접속된 실행자가 없습니다.	명시적 경로 지정 규칙을 추가하고 실행기 노드가 상위자에 연결되어 있는지 확인합니다.
집행자가 광범위한 답변 또는 주제 외 답변을 반환합니다.	실행기 지침이 너무 일반적입니다.	실행기 롤 범위를 좁히고 필요한 출력 구조를 정의합니다.
도구가 사용되지 않습니다.	도구가 연결 해제되었거나 잘못된 에이전트에 연결되었습니다.	도구 연결 및 에이전트 도구 수 배지를 확인합니다.
가드레일이 발사되지 않음	가드레일 섹션이 구성되었지만 사용으로 설정되지 않았습니다.	guadrails 노드를 열고 섹션 토글이 켜져 있는지 확인합니다.
상담원 간 컨텍스트 누수	상태 격리가 공유로 설정되거나 메모리가 의도한 것보다 광범위합니다.	더 엄격한 분리를 위해 Stateless 또는 Private 격리를 사용합니다.
후속 조치 질문의 컨텍스트 손실	메모리가 사용 안함으로 설정되었거나 잘림이 너무 공격적입니다.	메모리를 사용으로 설정하고 최대 메시지 제한을 조정합니다.

에이전트 플로우스루 코드

Oracle AI Data Platform Workbench에서 자체 LangGraph 코드 베이스를 AI 에이전트로 가져오거나, 에이전트 코딩 경험을 통해 플랫폼에서 새로운 LangGraph 에이전트를 직접 생성할 수 있습니다.

AI 데이터 플랫폼 워크벤치 유틸리티 Python 라이브러리 aidputils를 사용하여 기본 모델을 구성하고 시스템 도구를 에이전트로 가져올 수 있습니다. 보조 API 참조는 Aidp-utils API for Oracle AI Data Platform Workbench를 참조하십시오.

기존 코드 파일을 업로드하거나 인라인 편집기를 통해 에이전트에 직접 코드 파일을 생성하여 코드를 통해 에이전트를 생성합니다.

에이전트의 인라인 코드 편집기는 다음 코드 파일 유형을 지원합니다.

• Python(.py)
• JSON
• TXT
• CSV
• PSV
• 상세정보
• 폴더

File Selector drop-down list를 눌러 사용 가능한 코드 파일을 보고 탐색할 수 있습니다.

항목 및 종속성 파일

엔트리 파일은 코드로 정의된 에이전트에 대해 setup 및 invoke 메소드가 필요한 클래스를 가진 코드 파일입니다. Oracle AI Data Platform Workbench에서는 코드를 통해 에이전트에 대한 입력 파일을 설정해야 합니다.

종속성 파일은 에이전트가 코드로 정의한 타사 라이브러리를 포함하는 파일입니다. 종속성 파일은 일반적으로 필요한 타사 라이브러리 목록을 포함하는 requirements.txt 파일입니다.

주:

타사 라이브러리는 [재생] 단추를 눌러 편집기에서 코드를 테스트하거나 [테스트] 탭을 통해 에이전트를 테스트할 때 설치됩니다. 먼저 코드를 테스트하여 타사 라이브러리를 설치하는 것이 좋습니다. 라이브러리 설치 중 오류가 출력 셀에 표시됩니다.

에이전트 클래스

AgentBasic는 Stateful LangGraph 워크플로우를 사용하여 간단한 대화식 에이전트를 설정하고 호출하기 위한 템플리트 클래스입니다. 다음 두 가지 주요 방법을 사용하여 최소 에이전트 개발에 필요한 구조를 보여줍니다.

• setup(): 에이전트 워크플로우를 초기화하고 그래프를 정의합니다.
• invoke(user_query, **kwargs): 사용자 메시지에서 에이전트를 실행하고 응답을 반환합니다.

대형 시스템에 통합하기 전에 main() 함수를 사용하여 직접 실행하고 테스트할 수 있습니다.

정의

class AgentBasic:
    def __init__(self) -> None:
        self.graph = None
    def setup(self) -> None:
        self.graph = StateGraph(MessagesState)
        self.graph.add_node(mock_llm)
        self.graph.add_edge(START, "mock_llm")
        self.graph.add_edge("mock_llm", END)
        self.graph = self.graph.compile()
        system_prompt = "Be a helpful assistant."
    async def invoke(self, user_query: str, **kwargs):
        user_message = HumanMessage(content=user_query)
        messages = {"messages": [dict(user_message)]}
        try:
            return self.graph.invoke(messages)
        except Exception as e:
            import traceback
            logger.error(f"Exception while calling invoke {e}", exc_info=True)
            print("Stack trace:\n", traceback.format_exc()) 

테스트 호출

이 테스트 호출은 초기 기능 테스트에 적합합니다.

주:

독립형 테스트를 위한 기본 시작점을 포함합니다.

import asyncio

async def main():
test_agent = AgentBasic()
test_agent.setup()
result = await test_agent.invoke("Hi there")
print("Agent response:", result)
if __name__ == "__main__":
   asyncio.run(main())

작동 방식:

• 이 스크립트는 에이전트를 생성하고 설정하며 샘플 사용자 메시지를 보냅니다.
• 에이전트가 응답합니다({"messages": [{"role": "ai", "content": "hello world"}]} 이 예).

사용 안내서

setup 및 invoke 메소드를 사용하여 Agent 클래스를 생성합니다.

setup()	에이전트 워크플로우를 초기화합니다.	에이전트 설정()
호출()	사용자 메시지로 에이전트를 실행합니다.	await agent.invoke("당신의 질문")

• 비동기: invoke()는 비동기 메소드입니다. await와 함께 사용하거나 비동기 루프에서 실행합니다.
• 테스트: 포함된 main() Guard(if __name__ == "__main__":)를 사용하면 배포 전에 에이전트를 쉽게 테스트할 수 있습니다.

업로드로 코드를 통해 에이전트 빌드

LangGraph 코드 베이스를 업로드하여 기존 코드로 엔드투엔드 에이전트 애플리케이션을 구축할 수 있습니다.

Oracle AI Data Platform Workbench는 LangGraph 버전 1.0.1을 지원합니다.

주:

개별 파일 및 폴더를 최대 500개까지 업로드할 수 있으며, 각 파일의 최대 크기는 500MB일 수 있습니다. 업로드는 총 크기인 5GB로 제한됩니다.

1. 작업영역에서 에이전트로 이동합니다. 에이전트 이름을 누릅니다.
2. 업로드를 누릅니다.
   
   

   

   
   
3. 파일을 창에 끌어 놓거나 눌러서 파일을 찾아 선택합니다.
4. 업로드를 누릅니다.

새 코드를 생성하여 코드를 통해 에이전트 작성

코드 편집기를 통해 에이전트에서 직접 코드를 생성하여 기존 코드로 End-To-End 에이전트 응용 프로그램을 작성할 수 있습니다.

코드 편집기는 다음 파일 유형을 지원합니다.

• Python(.py)
• JSON
• TXT
• CSV
• PSV
• 상세정보
• 폴더

1. 작업영역에서 에이전트로 이동합니다. 에이전트 이름을 누릅니다.
2. 새 파일 추가를 누릅니다.
   
   

   

   
   
3. 코드 파일의 이름을 입력하십시오.
4. 드롭다운 목록에서 파일 유형을 선택합니다.
5. 생성을 누릅니다.

코드를 통해 에이전트에 대한 항목 파일 설정

코드를 통한 AI 에이전트에는 에이전트에 필요한 필수 클래스, 설정 및 호출 메소드가 있는 입력 파일이 필요합니다.

1. 작업영역에서 에이전트로 이동합니다. 에이전트 이름을 누릅니다.
2. 코드 편집기 탭의 왼쪽 탐색 창에서 항목 파일을 찾습니다. 파일이 존재하지 않을 경우 업로드를 눌러 업로드하거나 새 파일 추가를 눌러 생성할 수 있습니다.
3. 항목 파일을 마우스 오른쪽 단추로 누르고 항목 파일 설정을 누릅니다. 파일을 선택하고 코드 편집기 오른쪽 상단에 있는 항목 파일 설정 단추를 누를 수도 있습니다.
   
   

   

   
   

코드를 통해 에이전트에 대한 종속성 파일 설정

코드가 종속된 타사 라이브러리가 포함된 코드를 통해 에이전트가 이동하는 종속성 파일을 설정해야 합니다.

1. 작업영역에서 에이전트로 이동합니다. 에이전트 이름을 누릅니다.
2. 코드 편집기 탭의 왼쪽 탐색 창(일반적으로 requirements.txt)에서 종속성 파일을 찾습니다. 파일이 존재하지 않을 경우 업로드를 눌러 업로드하거나 새 파일 추가를 눌러 생성할 수 있습니다.
3. 종속성 파일을 마우스 오른쪽 단추로 누르고 종속성 설정을 누릅니다. 파일을 선택하고 코드 편집기 오른쪽 상단에 있는 종속성 파일 설정 단추를 누를 수도 있습니다.
   
   

   

   
   

테스트 에이전트 코드

Test 탭에서 에이전트에 사용되는 코드를 테스트하여 코드를 검증하고 디버그할 수 있습니다.

테스트하려면 에이전트에 AI 컴퓨트가 연결되어 있어야 합니다.

1. 작업영역에서 에이전트로 이동합니다. 에이전트 이름을 누릅니다.
2. 재생장 탭을 누릅니다.
   
   

   

   
   
3. 재생을 눌러 선택한 코드 파일을 테스트합니다.
   
   

   

   
   

Code Editor window의 하단에 있는 출력 셀은 코드에 있는 print 또는 logging 문의 출력을 표시합니다. 오류는 출력 셀에도 표시됩니다.

코딩 환경의 에이전트 기술

에이전트 기술을 사용하면 에이전트가 도메인 지식을 에이전트의 지침에 하드 코딩하지 않고도 작업별 지침, 참조 파일, 템플리트, 자산 및 선택적 실행 스크립트를 검색하고 사용할 수 있습니다.

스킬은 에이전트 코드 기반에 폴더로 저장됩니다. 각 스킬에는 스킬의 정의와 에이전트가 스킬을 사용하는 방법을 설명하는 필수 SKILL.md 파일이 있습니다. 기술에는 스키마, 예제, 프롬프트, 템플리트, 자산 또는 스크립트와 같은 지원 파일도 포함될 수 있습니다.

자세한 내용은 에이전트 기술 개요를 참조하십시오.

에이전트 기술은 다음과 같은 점진적 공개 모델을 지원합니다.

1. 에이전트가 스킬이 있음을 검색합니다.
2. 에이전트는 관련성이 있는 경우에만 기술을 활성화합니다.
3. 에이전트는 필요할 때만 스킬 폴더에서 추가 파일을 로드합니다.
4. 스킬이 허용하는 경우 에이전트는 명시적으로 선언된 스킬 진입점을 실행할 수 있습니다.

에이전트 기술 사용 시기

다음과 같이 재사용 가능한 에이전트 기능을 패키지화하려는 경우 기술을 사용해야 합니다.

• 도메인별 지침
• 코딩 또는 데이터 분석 워크플로우
• SQL 생성 지침
• 비즈니스 프로세스 플레이북
• 파일 템플리트
• 스키마 참조에 해당
• 안전한 계산, 변환 또는 조회를 위한 재사용 가능한 스크립트

기술은 에이전트가 전문적이고 재사용 가능한 지식에 액세스할 수 있어야 하지만 해당 지식을 모두 에이전트 프롬프트에 직접 배치하지 않으려는 경우에 유용합니다.

런타임 시 기술 작동 방식

런타임 시 호스트 응용 프로그램은 프로젝트 레벨 및 사용자 레벨 기술 폴더와 같이 사용 가능한 기술 디렉토리를 결정합니다. 플랫폼은 SKILL.md에서 각 스킬의 메타데이터를 로드하고 스킬 이름으로 키 지정된 카탈로그를 작성합니다.

그러면 에이전트는 기술 관련 툴을 사용할 수 있습니다.

도구	용도
activate_skill(name)	SKILL.md에서 스킬 지침을 로드합니다.
list_skill_files(name, path)	스킬 폴더 내에서 사용 가능한 파일을 나열합니다.
load_skill_file(name, path)	기술 폴더에서 지원 파일을 로드합니다.
run_skill_entrypoint(name, entrypoint, args_json, timeout_seconds)	스킬에서 허용하는 경우 명시적으로 선언된 Python 시작점을 실행합니다.

일부 환경에서는 사용 가능한 기술 요약을 시스템 프롬프트에 직접 포함할 수도 있습니다. 이 설정에서 에이전트는 프롬프트에서 사용 가능한 기술을 발견한 다음 전체 지침이 필요할 때 activate_skill를 사용할 수 있습니다.

기술 폴더 구조

스킬은 에이전트 스킬 스타일 폴더 레이아웃을 사용합니다.

<skills_dir>/
	some-skill/
		SKILL.md
		references/
		...
		scripts/
		...
		assets/
		...

SKILL.md만 필요합니다. 다른 폴더는 선택 사항입니다.

폴더 또는 파일	필수사항	용도
SKILL.md	예	주요 기술 메타데이터 및 지침입니다.
references/	아니요	지원 설명서, 스키마, 예제 또는 템플리트
scripts/	아니요	명시적으로 시작점으로 선언된 경우에만 실행할 수 있는 Python 스크립트입니다.
assets/	아니요	스킬에서 사용되는 정적 자산입니다.

작성 SKILL.md

각 기술에는 SKILL.md 상단의 YAML 프런트매터, 마크다운 지침이 포함되어야 합니다.

기본 예제

---
name: sql-helper
description: Helps the agent write safe SQL queries using project schemas.
license: internal
compatibility: "agent-platform"
metadata:
  owner: data-platform
  domain: analytics
allowed-tools: "analyzeQuery inspectSchema"
---

# SQL Helper

Use this skill when the user asks for SQL generation, query review, or schema-aware analysis.

Before writing SQL:
1. Inspect the relevant schema files in `references/`.
2. Prefer explicit column names.
3. Avoid destructive statements unless the user explicitly asks for them and the environment allows them.

표 22-3 지원되는 Frontmatter 필드

필드	필수사항	설명
name	예	카탈로그 및 도구에서 사용되는 고유 스킬 이름입니다.
description	예	검색 및 경로 지정에 사용되는 간단한 설명입니다.
라이센스	아니요	기술에 대한 라이센스 또는 사용 정책입니다.
호환성	아니요	지원되는 런타임 또는 플랫폼에 대한 호환성 참고 사항입니다.
메타데이터	아니요	문자열-문자열 메타데이터 맵입니다.
허용 도구	아니요	이 스킬이 허용하는 공백으로 구분된 툴 목록입니다.
시작점	아니요	스킬에 의해 선언된 실행 가능 시작점 목록입니다.

지원 파일 추가

지원 파일을 사용하면 기술이 기본 지침 외부에서 세부 콘텐츠를 유지할 수 있습니다. 이렇게 하면 SKILL.md가 집중되고 에이전트가 더 풍부한 컨텍스트에 액세스할 수 있습니다. 예:

skills/
	sql-helper/
		SKILL.md
		references/
			warehouse_schema.md
			query_style_guide.md
			examples.md

에이전트는 다음을 사용하여 이러한 파일을 검사할 수 있습니다.

list_skill_files("sql-helper", "references")
load_skill_file("sql-helper", "references/warehouse_schema.md")

다음과 같은 컨텐트에 지원 파일 사용:

• 데이터베이스 스키마
• API 예
• 프롬프트 템플리트
• 스타일 가이드
• 도메인 용어집
• 단계별 플레이북
• 테스트 사례 또는 예제

실행 가능 기술 생성

스킬은 선택적으로 run_skill_entrypoint를 통해 재사용 가능한 실행 동작을 노출할 수 있습니다. 이는 계산, 변환, 검증 또는 구조화된 데이터 인출과 같은 제어된 작업에 사용됩니다.

실행 가능 기술은 다음 두 가지 요구 사항을 충족해야 합니다.

1. 기술에는 허용되는 도구에 run_skill_entrypoint가 포함되어야 합니다.
2. 스크립트는 SKILL.md의 시작점 섹션에서 명시적으로 선언해야 합니다.

실행 가능 기술 예

skills/
	statistics-helper/
		SKILL.md
		scripts/
			summarize_numbers.py

사이트맵

---
name: statistics-helper
description: Computes basic summary statistics for numeric data.
allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
entrypoints:
  - name: summarize_numbers
    script: scripts/summarize_numbers.py
    func: run
    description: Returns count, min, max, mean, and median for a list of numbers.
---

# Statistics Helper

Use this skill when the user asks for basic descriptive statistics.
scripts/summarize_numbers.py:
from statistics import mean, median

def run(*, values: list[float]) -> dict:
    if not values:
        raise ValueError("values must not be empty")

    return {
        "count": len(values),
        "min": min(values),
        "max": max(values),
        "mean": mean(values),
        "median": median(values),
    }
Example invocation:
run_skill_entrypoint(
  name="statistics-helper",
  entrypoint="summarize_numbers",
  args_json="{\"values\": [10, 20, 30, 40]}",
  timeout_seconds=10
)
The runner returns structured output that includes exit_code, stdout, stderr, and a best-effort parsed result when the script prints or returns JSON.

실행 가능 항목 지점에 대한 규칙

실행 파일 진입점은 의도적으로 제한됩니다. 플랫폼은 다음과 같은 Python 파일만 실행합니다.

• 스킬의 스크립트/ 디렉토리 아래에 위치
• 스킬의 진입점에서 사전 선언됨
• 스킬의 allowed-tools 설정에서 허용됩니다.

플랫폼은 범용 임의의 스크립트 실행을 제공하지 않습니다. SKILL.md에 선언되지 않은 스크립트는 실행할 수 없습니다.

스크립트 실행자는 시간 초과를 사용하고, 기본값은 10초이며, 격리된 모드 동작으로 Python을 실행하고, 경로 제한을 적용합니다. 그러나 하위 프로세스 기반 실행은 전체 운영 체제 샌드박스가 아닙니다. 운용 환경에서는 컨테이너, 제한된 파일 시스템 또는 네트워크 컨트롤과 같은 높은 격리를 고려해야 합니다.

allowed-tools를 사용한 도구 사용 권한

allowed-tools는 기술 수준 권한 게이트 역할을 합니다. 설명서 전용 스킬의 경우 파일 읽기 도구만 허용할 수 있습니다.

allowed-tools: "load_skill_file list_skill_files"

선언된 스크립트를 실행할 수 있는 기술에는 run_skill_entrypoint를 포함합니다.

allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint" 

기술이 실제로 실행 가능한 동작을 필요로 하지 않는 한 run_skill_entrypoint를 추가하지 마십시오.

에이전트가 스킬을 발견하고 사용하도록 하는 방법

기술을 통해 에이전트를 보완하려면 aidpUtils 라이브러리의 다음 객체를 사용하여 기술 카탈로그, 기술 미들웨어를 인스턴스화하고 기술을 도구로 변환해야 합니다.

도구	용도
discover_skill_catalog	기본 기술 검색 위치 결정(프로젝트 + 사용자) 검색된 디렉토리에서 SkillCatalog 작성
SkillMiddleware	사용 가능한 기술 요약 및 경로 지정 규칙을 시스템 프롬프트에 추가합니다. 작업 공간 기반 미들웨어 구성을 위한 공장 도우미를 제공합니다.
make_skill_tools	이 메소드는 activate_skill, list_skill_files, load_skill_file 및 run_skill_entrypoint의 기술 검색 도구를 반환합니다. 이러한 도구는 에이전트가 다양한 기술을 활성화하고 실행하는 데 사용할 수 있습니다.

다음은 입력 파일에 포함될 내용의 예입니다.

from aidputils.agents.skills.discovery import discover_skill_catalog
from aidputils.agents.skills.middleware import SkillMiddleware
from aidputils.agents.skills.tools.factories import make_skill_tools
...
class SchoolGradeAgentWithEmbededSkills:
	...
	def init(self) -> None: 
		...
		self.catalog = discover_skill_catalog(skill_folder_whitelist=None)
		self.skill_middleware = SkillMiddleware(self.catalog)
		self.tools = make_skill_tools(self.catalog)

이 로거 명령문을 코드에 추가하여 기술 카탈로그를 디버깅할 수 있습니다. 스킬 카탈로그에서 발견된 모든 스킬이 인쇄됩니다.

for info in self.catalog.list():
	logger.info("skill_id=%s name=%s desc=%s root=%s skill_file=%s", info.skill_id, info.name, info.description, info.root_dir, info.skill_file)

스킬 우선순위

이 플랫폼은 프로젝트 레벨 및 사용자 레벨 디렉토리와 같은 여러 위치에서 기술을 로드할 수 있습니다. 카탈로그는 해당 위치를 이름이 지정된 단일 기술 목록으로 집계합니다.

동일한 이름의 스킬이 여러 점포에 포함된 경우 우선순위는 사용할 스킬을 결정합니다. 나중에 저장소가 이전 저장소를 대체하므로 호스트 응용 프로그램이 사용자 레벨 기술, 프로젝트 레벨 기술 또는 작업 영역 레벨 기술이 우선하는지 여부를 제어할 수 있습니다.

기술 작성 모범 사례

SKILL.md 집중 유지

활성화 후 즉시 에이전트에 필요한 핵심 지침에 SKILL.md를 사용합니다. 참조/에 긴 스키마, 예제 및 참조 자료를 넣습니다.

명확한 설명 작성

설명 필드는 검색에 사용됩니다. 에이전트가 스킬을 활성화할 시기를 알 수 있을 만큼 구체적으로 지정합니다.

좋음:

description: Helps generate BigQuery SQL using the finance warehouse schema.

덜 유용함:

description: Helps with data.

명시적 시작점 이름 사용

시작점 이름은 작업을 명확하게 설명해야 합니다.

entrypoints: 
   - name: validate_query 
   - name: summarize_numbers 
   - name: transform_csv

다음과 같은 모호한 이름은 피하십시오.

entrypoints: 
   - name: run 
   - name: do_it 

구조화된 결과 반환

실행 스크립트에서는 가능하면 JSON 직렬화 가능한 결과를 반환해야 합니다. 이렇게 하면 에이전트가 보다 쉽게 검사하고 사용할 수 있습니다.

불필요한 실행 방지

가능한 경우 지침 및 참조 파일을 선호합니다. 실제로 코드가 필요한 작업에 대해서만 실행 가능 시작점을 사용합니다.

새 기술 추가

스킬 디렉토리 내에 새 폴더를 생성하고 필요한 파일 및 폴더를 추가하여 새 에이전트 스킬을 추가할 수 있습니다.

1. skills 디렉토리(.agents/skills/<skill-name>/) 아래에 폴더를 생성합니다.
2. 필요한 frontmatter가 있는 SKILL.md 파일을 추가합니다.

   ---
   name: <skill-name>
   description: <what this skill helps the agent do>
   ---
   

3. Markdown의 기술 지침을 프론트 매터 아래에 작성하십시오.
4. 다음 아래에 선택적 지원 파일을 추가합니다.

   references/
   assets/
   scripts/
   

5. 기술이 실행 가능한 경우 run_skill_entrypoint를 allowed-tools에 추가하고, SKILL.md에서 entrypoints를 선언하고, Python 구현을 scripts/ 아래에 배치합니다.

기존 스킬에 새 실행 가능 기능 추가

기존 스킬에 새 실행가능 공정을 추가하여 SKILL.md의 기능을 확장할 수 있습니다.

1. 1. 스킬의 scripts/ 디렉토리 아래에 Python 파일을 추가합니다.

   .agents/skills/<skill-name>/scripts/my_operation.py 

2. 2. run(...) 함수를 구현합니다.

   def run(*, input_text: str) -> dict:
       return {
           "length": len(input_text),
           "uppercase": input_text.upper(),
       }
   

3. 3. 일치하는 시작점을 SKILL.md에 추가합니다.

   allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
   entrypoints:
     - name: my_operation
       script: scripts/my_operation.py
       func: run
       description: Processes input text and returns structured output.
   

4. 4. JSON 객체를 인수로 사용하여 시작점을 테스트합니다.

   {
     "input_text": "hello"
   }
   

에이전트 기술 문제 해결

에이전트 기술 구현에 문제가 있는 경우 이 목록에서 문제 해결에 대한 도움말을 확인하십시오.

에이전트에 내 스킬이 표시되지 않습니다.

다음 사항을 확인하십시오.

• 스킬 폴더는 구성된 스킬 디렉토리 아래에 있습니다.
• 폴더에는 SKILL.md가 포함되어 있습니다.
• SKILL.md에 적합한 YAML 프런트매터가 있습니다.
• 프런트매터에는 이름과 설명이 모두 포함됩니다.

에이전트가 잘못된 스킬을 활성화합니다.

스킬 디렉토리에서 중복 스킬 이름을 확인하십시오. 두 스킬의 이름이 동일한 경우 카탈로그 우선순위는 사용할 스킬을 결정합니다.

지원 파일을 로드할 수 없습니다.

다음 사항을 확인하십시오.

• 파일이 스킬 폴더 안에 있습니다.
• 경로에는 ../와 같은 순회가 포함되지 않습니다.
• 파일이 숨겨지지 않았습니다.
• __pycache__ 또는 .pyc와 같은 파일은 제외되지 않습니다.

시작점이 실행되지 않습니다.

다음 사항을 확인하십시오.

• run_skill_entrypoint가 allowed-tools에 포함되어 있습니다.
• 시작점은 SKILL.md에서 선언됩니다.
• 스크립트 경로는 scripts/ 아래에 있습니다.
• 스크립트는 .py 파일입니다.
• func의 함수 이름이 스크립트에 있습니다.
• 인수는 적합한 JSON 객체입니다.

시작점 시간 초과

작업이 더 오래 걸릴 것으로 예상되는 경우에만 timeout_seconds를 늘립니다. 장기 실행 또는 자원 집약적인 작업의 경우 작업을 전용 서비스 또는 보다 격리된 실행 환경으로 이동하는 것이 좋습니다.

예: 에이전트 기술 완료

이 예에서는 구현 후 전체 에이전트 기술이 어떻게 표시되는지 보여줍니다.

폴더 구성

skills/
	customer-support-reply/
		SKILL.md
		references/
			tone_guide.md
			refund_policy.md
			escalation_rules.md

사이트맵

---
name: customer-support-reply
description: Helps draft customer support replies using the company tone guide and policy references.
allowed-tools: "load_skill_file list_skill_files"
metadata:
  owner: support-operations
  domain: customer-support
---

# Customer Support Reply

Use this skill when the user asks for help drafting, reviewing, or improving a customer support response.

Workflow:

1. Identify the customer’s issue.
2. Load the relevant policy file from `references/` if needed.
3. Draft a clear, empathetic response.
4. Avoid making commitments that are not supported by policy.
5. Recommend escalation when the request matches the escalation rules.
This skill does not run code. It gives the agent structured instructions and optional policy files that can be loaded only when relevant.

에이전트 테스트

에이전트를 테스트하여 출력을 미리 보고 디버그할 수 있습니다. 또한 테스트 세션을 생성 및 관리하여 에이전트에 대한 다양한 테스트 시나리오를 탐색할 수 있습니다.

에이전트를 테스트하는 첫번째 단계는 에이전트를 AI 컴퓨트에 연결하는 것입니다. 에이전트를 연결하면 에이전트의 복사본이 AI 컴퓨트에 푸시됩니다. 에이전트가 AI 컴퓨트에 연결되어 있는 한, [테스트] 단추를 누를 때마다 에이전트에 대한 모든 변경사항이 연결된 컴퓨트로 전파됩니다.

테스트 버튼을 클릭하면 테스트 놀이터로 이동합니다.

테스트 플레이그라운드에는 다음과 같은 구성 요소가 있습니다.

• 세션을 시작하고 에이전트와 채팅을 시작하거나 기존 세션을 재개할 수 있는 채팅 창
• 에이전트의 그래프 기반 표현
• 세션 중 생성된 추적 및 범위 트리를 보여주는 패널입니다.
• 추적 및 범위 속성, 입력/출력을 표시하는 추적 및 범위 탐색기 패널입니다. Details(세부정보) 탭에는 ID, 시작 및 종료 시간, 실행 시간이 포함되며 Events(이벤트) 탭에는 실행 중 오류가 강조 표시됩니다.

Playground를 사용하면 각 에이전트를 개별적으로 상호 작용하고 테스트할 수 있습니다. 기본적으로 상위자 에이전트가 선택되지만 각 실행자 에이전트와 채팅하고 개별적으로 테스트하도록 선택할 수 있습니다. 이렇게 하면 실행기 에이전트에 대한 요청을 실행하는 감독자 에이전트의 동작을 시뮬레이션할 수 있습니다. 이렇게 하려면 채팅 창의 드롭다운 메뉴에서 테스트할 에이전트를 선택합니다.

추적 및 범위는 첫 번째 메시지를 작성하는 즉시 중앙 패널에 표시됩니다. 각 작업은 다른 사용자 메시지에 해당합니다. 왼쪽 캐럿을 눌러 추적을 확장하고 범위를 검사할 수 있습니다.

놀이터에서 에이전트 테스트

테스트 플레이그라운드에서 시각적 빌더 및 LangGraph 기반 에이전트를 테스트하여 에이전트를 검증하고 디버그할 수 있습니다.

테스트하려면 에이전트에 AI 컴퓨트가 연결되어 있어야 합니다. 에이전트에 대한 AI 클러스터 생성에 따라 새 AI 컴퓨트 클러스터를 추가하거나, 에이전트에 기존 AI 클러스터 연결에 따라 기존 AI 컴퓨트 클러스터를 연결할 수 있습니다.

1. 작업영역에서 에이전트로 이동합니다. 에이전트 이름을 누릅니다.
2. 캔버스 상단에서 플레이그라운드를 누릅니다. 에이전트를 연결된 컴퓨트로 푸시하는 데 몇 초 정도 걸릴 수 있습니다.
   
   

   

   
   

에이전트가 테스트 놀이터에 표시됩니다.

에이전트 테스트 세션 생성

테스트 세션을 생성하여 에이전트와 새 대화를 시작할 수 있습니다.

에이전트가 연결된 컴퓨트에서 호스트되는 테스트 플레이그라운드 대상에서 생성된 모든 세션입니다. 세션이 생성되면 나중에 재개할 수 있습니다.

1. 작업영역에서 에이전트로 이동합니다. 에이전트 이름을 누릅니다.
2. 캔버스 맨 위에서 플레이그라운드를 누릅니다.
3. 세션 선택기에서 세션 생성을 누릅니다.
   
   

   

   
   
4. 채팅 상자에 쿼리를 입력하여 에이전트와 대화 상자를 시작합니다.
   
   

   

   
   

에이전트 테스트 세션 재개

이전에 생성한 에이전트 테스트 세션을 재개할 수 있습니다.

주:

생성한 세션만 재개할 수 있습니다.

1. 작업영역에서 에이전트로 이동합니다. 에이전트 이름을 누릅니다.
2. 캔버스 맨 위에서 플레이그라운드를 누릅니다.
3. 세션 드롭다운에서 이전 세션을 선택합니다.
   
   

   

   
   
4. 채팅 상자에 쿼리를 입력하여 에이전트와 대화 상자를 재개합니다.

에이전트 테스트 세션 삭제

연결된 AI 컴퓨트에서 호스트된 에이전트에 대한 테스트 세션 및 배포된 에이전트에서 생성된 세션을 삭제할 수 있습니다.

1. 작업 영역에서 에이전트로 이동합니다.
2. 세션 탭을 누릅니다.
   
   

   

   
   
3. 삭제할 세션 옆에 있는 작업을 누른 다음 삭제를 누릅니다.
   
   

   

   
   
4. 삭제를 누릅니다.

에이전트 도구 정보

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

에이전트는 하나 이상의 도구와 연결할 수 있는 단일 에이전트로 구성된 구성을 지원합니다. Oracle AI Data Platform Workbench는 시각적 흐름 또는 코드를 통해 사용하도록 구성할 수 있는 세 가지 도구 템플릿을 제공합니다.

• 사용자정의 코드: AI 개발자는 사용자정의 코드 도구를 사용하여 Python을 사용하여 도구를 구현할 수 있습니다. 개발자는 도구를 ZIP에 패키지화하여 작업영역에 업로드하고 에이전트에서 노드로 구성합니다. 사용자정의 코드 도구는 내장된 도구가 필요한 통합을 제공하지 않는 경우에 사용됩니다.
• HTTP 요청: HTTP 요청 도구는 개발자가 에이전트에서 지원되는 REST API 호출을 사용하여 AI 데이터 플랫폼 워크벤치 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 AI Database 등 외부 카탈로그를 통해 등록된 구조화된 데이터 소스에 대해 SQL 쿼리를 실행할 수 있습니다. 이 도구는 SQL query가 미리 정의되어 있고 파라메트화할 수 있는 시나리오를 위한 것입니다. 목표는 에이전트가 매개변수에 값을 할당하도록 하는 것입니다. 이 도구는 자연어 프롬프트를 기반으로 SQL query를 생성하는 NL2SQL 도구가 아닙니다.

  주:

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

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

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

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

주:

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

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

AIDPToolConf() 클래스의 인스턴스를 통해 LangGraph 코딩 에이전트에 RAG, SQL 및 Prompt 툴을 추가합니다.

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

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

• 이름: 사용자와 LLM이 도구의 목적을 이해하는 데 도움이 되는 설명형 이름입니다.
• 설명: 사용자와 LLM이 도구의 기능을 이해할 수 있도록 충분한 정보를 제공하는 철저한 요약입니다.
• tool_class: 지원되는 도구 유형(PromptTool, SQLTool 또는 RAGTool)입니다.
• 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 탭에서는 패키지의 각 도구 클래스에 대한 정적 설정을 구성합니다. 도구 클래스 드롭다운을 사용하면 패키지에서 검색된 도구 간에 전환할 수 있습니다.

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

• 도구 클래스: 구성할 도구 클래스를 선택합니다. 드롭다운은 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을 눌러 툴을 호출하고 응답을 봅니다.

주:

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

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

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

주:

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

1. 에이전트로 이동합니다.
2. Tool Templates에서 Custom 도구를 캔버스로 끌어 놓습니다.
3. 패키지 탭에서 사용자 정의 코드가 포함된 ZIP 파일을 눌러 선택하거나 화면에 끌어 놓습니다. 업로드가 완료될 때까지 기다립니다.
   
   

   

   
   
4. 패키지 탭의 도구 섹션에서 검색된 도구 목록을 검토합니다. tool_implementation.py에 있는 각 도구 클래스는 해당 클래스 이름, 설명 및 버전과 함께 나열됩니다.
   
   

   

   
   
5. 사용으로 설정할 도구를 선택합니다. 사용 안함으로 설정된 도구는 에이전트에 노출되지 않습니다.
6. 선택 사항: 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에 연결하는 방법은 다음과 같습니다.

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

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

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

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

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

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

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

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 도구 노드의 테스트 탭을 통해 수행할 수 있습니다.

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

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

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

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

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

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

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

주:

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

1. 에이전트로 이동합니다.
2. 흐름 탭의 도구 템플리트에서 사용자정의 MCP 서버를 눌러 캔버스로 끌어옵니다.
3. MCP 서버에 대한 서버 URL을 제공합니다.
4. MCP 서버의 표시 이름을 제공합니다. 시각적 빌더 캔버스에 표시되는 노드의 이름입니다.
5. 선택 사항: MCP 서버에 대한 설명을 제공합니다. 설명 필드가 에이전트에 제공되지 않았습니다.
6. 인증 드롭다운 메뉴에서 인증 방법을 선택합니다.
   • 인증 없음: 원격 MCP 서버가 공개적으로 사용 가능하며 인증이 필요하지 않은 경우 이 옵션을 사용합니다.
   • 베어러 토큰: 원격 MCP 서버에 인증 토큰이 필요한 경우 이 옵션을 사용합니다. API 키를 Oracle AI Data Platform Workbench 인증서 저장소에 저장하고 인증서 저장소 항목에 대한 참조를 제공해야 합니다.
7. 연결을 누릅니다. 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초입니다.
인증 유형	끝점을 호출할 때 사용할 인증 방법입니다. 지원되는 인증 방법 목록은 아래의 인증 섹션을 참조하십시오.

주:

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

헤더

헤더는 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)

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

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

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

에이전트 플로우에 HTTP 요청 툴 추가

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

주:

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

1. 에이전트로 이동합니다.
2. Tool 템플리트에서 HTTP Request 툴을 캔버스로 끌어다 놓습니다.
   
   

   

   
   
3. 매개변수 탭에서 HTTP 메소드를 제공합니다. 지원되는 방식은 GET, POST, PUT, PATCH 및 DELETE입니다.
4. URL에서 대상 끝점의 전체 URL을 제공합니다. {{sessionVariables.variable_name}} 세션 변수 참조 및 {{variable}} 런타임 매개변수 참조를 사용할 수 있습니다. 예: https://api.example.com/users/{{user_id}}/orders.
5. 시간 초과의 경우 도구가 원격 끝점의 응답을 기다리는 최대 시간(초)을 제공합니다. 최대 시간 초과 값은 300입니다. 값을 제공하지 않을 경우 기본값은 30초입니다.
6. 인증 드롭다운 메뉴에서 적합한 인증 유형을 선택합니다.
7. HTTP 요청의 헤더를 제공합니다. 추가 헤더를 추가하려면 새 항목 추가를 누릅니다.
   
   

   

   
   
8. HTTP 요청에 대한 질의 매개변수를 제공합니다. 새로 추가를 눌러 다른 매개변수를 추가합니다.
   
   

   

   
   
9. 선택 사항: 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 도구 정의 패널을 자동으로 채웁니다. 해당하는 경우 각 매개변수에 대한 설명과 매개변수 유형 및 기본값을 에이전트에 제공합니다.

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)

표 22-4 프롬프트 도구 구성 등록 정보

속성	유형	설명
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에 실행하는 매개변수화된 프롬프트를 정의할 수 있습니다.

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

RAG 도구

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

주:

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

Visual Flow를 통한 RAG 도구

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

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

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

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

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

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())

표 22-5 RAG 도구 구성 등록 정보

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

테스트 에이전트 RAG 도구

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

에이전트에 RAG 도구 추가

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

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

SQL 도구

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

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

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}}')

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

주:

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

JSON으로 구성 편집

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

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

행 한도

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

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

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

주:

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

질의 예제

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

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

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())

표 22-6 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 문법
  • 카탈로그 SQL 문법
  • 스키마 SQL 문법
  • 볼륨 SQL 문법
  • 테이블 SQL 문법
  • DML 질의

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

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

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

에이전트에 SQL 도구 추가

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

1. 에이전트로 이동합니다.
2. Tool templates에서 SQL 도구를 캔버스로 끌어다 놓습니다.
3. 에이전트에서 커넥터 핸들을 누른 채 끌어 도구 노드에 연결합니다.
   
   

   

   
   
4. SQL 노드를 두 번 눌러 구성 패널을 엽니다.
5. 도구에 대한 이름 및 설명을 제공하십시오. 이 설명은 에이전트에 제공되며 도구 호출 시기를 결정하는 데 도움이 됩니다.
6. 질의 방언을 선택합니다.
   • Spark SQL은 표준 AI 데이터 플랫폼 카탈로그에 대한 쿼리를 작성합니다.
   • Oracle SQL은 외부 AI 데이터 플랫폼 카탈로그에 대한 쿼리를 작성합니다.

   주:

   Spark SQL을 사용하려면 AI 데이터 플랫폼 워크벤치 작업영역에서 실행 중인 Spark 클러스터가 필요합니다.
   
   

   

   
   
7. 클러스터 드롭다운에서 실행 중인 Spark 클러스터를 선택합니다. 새 Spark 클러스터를 프로비전하려면 클러스터 생성을 누릅니다. 새 클러스터 생성에 대한 지침은 사용자정의 클러스터 생성을 참조하십시오.

   주:

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

   
   

   

   
   
8. 카탈로그 찾아보기에서 검색 필드를 사용하여 이름별로 카탈로그를 찾거나 카탈로그 관리자를 통해 눌러 카탈로그를 찾습니다.
   
   

   

   
   
9. 쿼리 필드에 쿼리를 입력합니다. 질의 예제 및 설명서 보기를 눌러 복사하거나 적용할 수 있는 미리 만들어진 패턴이 포함된 패널을 엽니다.
   
   

   

   
   
10. 반환할 최대 행 수를 선택하여 질의 결과에서 반환되는 행 수를 제한합니다.

    주:

    질의가 이 제한보다 많은 행을 반환할 수 있는 경우 에이전트가 보다 구체적인 데이터를 찾을 수 있도록 {{customer_name}} 또는 {{region}}와 같은 검색 매개변수를 추가하는 것이 좋습니다.
11. AI 도구 정의 창에서 질의에 설정된 변수에 대한 유형, 기본값 및 설명을 설정합니다.
    
    

    

    
    
12. 선택 사항: Test(테스트) 탭을 누릅니다. 테스트 매개변수를 제공하고 제출을 누릅니다. 테스트 결과 창에서 테스트 결과를 참조하십시오.

에이전트 메모리

에이전트 메모리는 에이전트가 회전, 작업 또는 세션 간에 정보를 보존하고 재사용할 수 있게 해주는 AI 에이전트 시스템의 일부입니다.

임시이며 현재 프롬프트로 제한되는 모델의 컨텍스트 창과 달리 메모리는 팩트, 기본 설정, 이전 결정, 도구 출력, 중간 계획 또는 환경에 대한 관찰을 지속할 수 있습니다.

AI 데이터 플랫폼의 에이전트 메모리

AI 데이터 플랫폼은 세션 기간으로 제한되는 단기 메모리를 제공합니다. 에이전트의 Memory(메모리) 탭에서 메모리에 보관할 수 있는 항목을 구성할 수 있습니다.

단일 에이전트 메모리 구성

단일 에이전트 시스템의 메모리 구성은 에이전트 노드의 [메모리] 탭에서 찾을 수 있습니다.

메모리 구성	설명
에이전트 메모리 사용	이 설정은 에이전트 메모리를 사용으로 설정합니다. 사용 안함으로 설정된 경우 에이전트는 기본적으로 Stateless 시스템입니다. 각 회전은 독립적으로 처리되며 후속 질문을 할 수 없습니다. 메모리를 사용으로 설정하는 것이 좋습니다.
대화 내역 제한	이 선택이 사용 안함으로 설정되면 이전 회전은 모델이 컨텍스트가 부족하고 오류가 반환될 때까지 메모리를 채웁니다. 짧은 세션이 예상되는 경우 이 설정을 사용 안함으로 설정하는 것이 좋습니다. 그러나 대부분의 사용 사례에서는 대화 내역을 제한하는 것이 좋습니다.
자르기 구성	대화 내역을 제한하도록 선택한 경우 다음을 수행하여 내역을 잘라내도록 결정할 수 있습니다. 마지막 N개 메시지만 유지(사용자 + 에이전트) 전체 토큰 예산 설정(선입선출) 또는 둘 다, 어느 쪽이 먼저 나오든 에이전트 메모리의 자르기를 트리거합니다.
최대 메시지 제한	마지막 N개의 메시지를 유지하도록 선택한 경우 N의 값을 설정할 수 있습니다.
토큰 예산	또는 전체 토큰 예산을 설정할 수 있습니다. 가장 최근의 토큰을 메모리에 보관하기 위해 첫 번째 토큰이 제거됩니다.

다중 에이전트 시스템 메모리 구성(감독자 패턴)

다중 에이전트 시스템의 메모리는 상위자 에이전트의 Memory(메모리) 탭에서 구성됩니다.

다중 에이전트 시스템의 메모리는 강제 적용되며 사용 안함으로 설정할 수 없으며 상위자 에이전트 노드에 표시된 메모리 자르기 옵션은 상위자 에이전트 메모리에만 적용됩니다. 각 실행기 에이전트 메모리 자르기 정책은 전체 시스템에 대해 선택된 상태 격리 정책에 따라 실행기 노드 메모리 탭에서 구성할 수 있습니다.

또한 다중 에이전트 시스템 메모리 구성을 통해 실행기 에이전트의 메모리 공유 정책을 선택할 수 있습니다. Stateless, Private 및 Shared의 세 가지 옵션이 있습니다. 정책은 모든 실행기 에이전트에 적용됩니다.

실행기 에이전트에 대한 상태 격리	설명
Stateless	각 실행기 에이전트는 감독자가 할당한 작업만 표시합니다. 호출 사이에 전달된 내역이 없습니다. 실행기 에이전트가 감독자 에이전트에 후속 조치를 요청할 수 없습니다. Stateless가 선택된 경우 각 실행기 에이전트의 메모리가 사용 안함으로 설정됩니다.
프라이빗	각 실행기 에이전트는 자신의 과거 상호 작용만 봅니다. 다른 실행기 에이전트나 감독자 에이전트와의 원래 사용자 대화는 볼 수 없습니다.
공유	실행기 에이전트는 에이전트 및 사용자 간의 전체 대화 내역을 볼 수 있습니다. 모든 에이전트는 하나의 공유 컨텍스트에서 작동합니다. 공유가 선택된 경우 각 에이전트 노드 메모리 탭에서 각 실행기 에이전트에 대해 별도로 메모리 자르기 정책을 구성할 수 있습니다.

세션 변수

사용자 정의 에이전트 정의 세션 변수를 사용하여 사용자 세션 중에 에이전트에 추가 컨텍스트 데이터 포인트를 제공할 수 있습니다.

세션 변수란?

사용자 정의 에이전트 정의 세션 변수는 사용자 세션 중 에이전트에 추가 컨텍스트 데이터 포인트를 제공합니다. 이 변수는 도구에서 매개변수 값 설정, 에이전트에 전체 지침 제공, 에이전트가 포함된 호출자 및/또는 응용 프로그램에 대한 컨텍스트 정보 제공 등 다양한 용도로 사용할 수 있습니다.

다음은 고객 지원 에이전트를 구축하는 간단한 시나리오입니다. 고객 지원 에이전트는 소매 웹사이트 내에 통합되어 있습니다. 사용자가 소매 웹 사이트에 로그인하면 해당 사용자에 대한 정보가 클라이언트 응용 프로그램(userID, 사용자 이름, 지리적 위치, 사용된 장치, 장바구니 ID 등)에 의해 캡처되고 다운스트림 지원 에이전트가 해당 정보를 사용할 수 있습니다. AIDP의 에이전트 지침 필드에서 이러한 세션 매개변수를 사용할 수 있는 방법에 대한 예를 살펴보겠습니다.

You are a customer support agent for the retail website belts-and-buckles.com, specializing in the sales of belts and buckles. Your objective is to answer questions that customers have about their current and past orders, answer questions about items they put in their shopping cart, and answer general questions about belts-and-buckles.com.  
A few guidelines before your start:  
    You are interacting with user {{sessionVariable.userName}}. Always start with a welcome message: Hello {{sessionVariable.preferredSalutation}} {{sessionVariable.userName}}! What’s the weather like today in {{sessionVariable.currentUserGeo}}?  

위의 예제에서는 세 개의 세션 변수가 사용됩니다.

• 사용자 이름
• 선호 인사말
• 현재 사용자 지오

에이전트는 소매 웹 사이트와 상호 작용하는 사용자에 대한 사전 지식이 없으며 사용자 위치가 무엇인지 알지 못하거나 사용자의 쇼핑 카트에 있는 내용에 대한 컨텍스트가 없습니다. 원칙적으로 클라이언트 응용 프로그램은 이러한 값의 전부 또는 일부를 알고 이러한 값을 요청으로 에이전트에 전달할 수 있습니다. 다음은 세션 매개 변수를 포함하여 에이전트에 대한 요청이 어떻게 나타날 수 있는지에 대한 예입니다.

주:

이 예에서는 이 요청의 모양을 보여줍니다. 구현 결정을 대표하지 않습니다.

"input": [  
{ "role": "user", 
         "content": [  
{ "type": "input_text”,  
	  "text": "What material is the belt Mr Outcast made of?", 
	  “variables”: [“userName”: “Paul”, “preferredSalutation”: “Hon”, “cartID”: NULL, “currentUserGeo”: “Cancun, MX”]  
} 
  ]  
} 
] 

대리인은 "안녕하세요, 폴 씨, 오늘 칸쿤의 날씨는 어떻습니까, Mx?"라고 대답합니다.

이러한 세션 파라미터의 또 다른 용도는 도구에서 파라미터 값을 설정하는 것입니다. 예를 들어, SQL 질의는 세션 매개변수 {{sessionParam.CartID}} 을(를) 사용하여 쇼핑 카트의 콘텐츠를 검색할 수 있습니다.

Select productID, productName, productDescription, 
productPrice from cartTable where cartID == 
{{sessionVariable.cartID}}  

세션 변수는 에이전트를 생성할 때 에이전트 개발자가 정의하며, 세션이 생성되거나 재개될 때 클라이언트 응용 프로그램에서 이러한 속성 값을 설정합니다.

새 세션 변수를 생성할 때 다음 설정을 구성할 수 있습니다.

설정	설명
필수 변수	에이전트의 각 호출 호출에 대해 이 세션 변수를 필수로 설정하려면 사용으로 설정합니다. 비활성화하면 각 호출 호출에 대해 세션 변수가 선택 사항으로 설정됩니다.
로그 변수	로그 및 추적에서 세션 변수의 값을 캡처하려면 사용으로 설정합니다. 사용 안함으로 설정하면 변수가 로그에 표시되지 않습니다. 중요한 데이터가 있는 변수의 경우 이 설정을 사용 안함으로 설정하는 것이 좋습니다.
이름	세션 변수의 이름입니다. 설명이 포함된 이름을 사용하면 사용자와 다른 사용자가 변수의 용도를 쉽게 확인할 수 있습니다.
기본값	정의된 경우 호출 호출에 다른 값이 정의되지 않은 경우 세션 변수에 기본값이 할당됩니다. 비워 둘 경우 호출 호출의 일부로 값을 지정해야 합니다.
설명	세션 변수 설명입니다. 본인 및 다른 사용자가 세션 변수의 기능을 이해할 수 있도록 유용한 설명을 제공하십시오.

예제: 도구 구성에서 세션 변수 사용

SQL 도구 구성에서 세션 변수를 SQL query 자체의 일부로 사용할 수 있습니다.

이 예제에서 세션 변수 geo는 SQL 질의 결과를 필터링하는 데 사용됩니다.

동일한 query 내에서 세션 변수와 도구 파라미터를 사용할 수 있습니다. 아래 예제에서 titleID 매개변수는 에이전트에 의해 설정되고 세션 변수 geo는 호출 응용 프로그램에 의해 제공됩니다.

시스템 생성 세션 변수

세션 변수는 원격 MCP 서버가 에이전트에 연결되어 있고 MCP 서버에 Bearer 토큰과 같은 인증이 필요할 때 자동으로 생성됩니다.

세션 변수는 Bearer 토큰의 값을 보유합니다. 이 시스템 생성 세션 변수의 이름은 변경할 수 없으며 필수 변수입니다. MCP 노드가 캔버스에서 제거되면 시스템 변수가 삭제됩니다.

플레이그라운드에서 시스템 생성 세션 변수에 대한 값을 제공합니다. 이 경우 MCP 서버를 사용하려면 Bearer 토큰을 제공해야 합니다. MCP 노드 구성 중 사용한 것과 동일한(또는 다른) 토큰을 선택할 수 있습니다.

에이전트를 배치하는 경우에도 마찬가지입니다. 권한 부여 토큰을 제공해야 합니다. 자세한 내용은 재생장에서 세션 변수에 값 지정을 참조하십시오.

예: 배치된 끝점을 호출할 때 세션 변수에 값 지정

이 예제에는 두 개의 세션 변수가 있습니다. userLocation 및 UserName 클라이언트 응용 프로그램이 body의 metadata 필드를 통해 세션 변수 값을 전달합니다. Python 및 OCI CLI를 통해 값을 할당하는 방법을 보여줍니다.

Python 요청 라이브러리를 사용하는 경우 페이로드는 다음과 같습니다.

body = { 

            "isStreamEnabled" : False, 

            "trace" : False, 
            "input" :[{ 
                "role":"User", 
                "content":[{ 
                    "type" : "INPUT_TEXT", 
                    "text" : “Hello how can you help me?”                  
                }] 
            }], 

            "metadata": { 
            "sessionvariables.userLocation": "Canada",  
            "sessionvariables.UserName": "George" 
        } 
        } 

response = requests.post( 
url = <insert-chat-url>,  
params = None,  
auth = <insert-oci-signer>, 
json = body, 
headers={“x-session-id": <insert-a-session-key>,} 
)  

또는 OCI CLI를 사용하는 경우 페이로드는 다음과 같습니다.

oci raw-request \ 
  --http-method POST \ 
  --auth security_token \ 
  --request-body '{ 
    "isStreamEnabled": false, 
    "input": [ 
      { 
        "role": "user", 
        "content": [ 
          { 
            "type": "INPUT_TEXT", 
            "text": "Hello how can you help me?" 
          } 
        ] 
      } 
    ], 
    "metadata": { 
      "sessionvariables.userName": "George", 
      "sessionvariables.userLocation": "Canada"}" 
    } 
  }' \ 
  --request-headers '{ 
    "x-session-id": "george-session-may11" 
  }' \ 
  --target-uri "<insert-your-agent-flow-uri>" 

에이전트 변수 탭에서 세션 변수 생성

새 세션 변수를 생성하고 Variables 탭에서 에이전트에 추가할 수 있습니다.

1. 세션 변수를 추가할 에이전트로 이동합니다.
2. 변수 탭을 누릅니다.
   
   

   

   
   
3. 세션 변수 추가를 누릅니다.
   
   

   

   
   
4. 세션 변수가 필수 변수인 경우 선택합니다.
5. 세션 변수 값을 로그 및 추적에 기록할지 여부를 선택합니다. 중요한 데이터에 대해서는 이 설정을 사용 안함으로 유지합니다.
6. 세션 변수에 대해 의미 있는 이름과 설명을 제공합니다.
7. 세션 변수에 대한 기본값을 제공합니다. 호출 호출의 일부로 다른 값이 할당되지 않은 경우 기본값은 세션 변수에 할당됩니다.
8. 생성을 누릅니다.

에이전트 플로우 지침의 세션 변수 참조

SQL 및 프롬프트 도구 질의를 비롯하여 에이전트 지침 및 도구 구성에서 세션 변수를 참조할 수 있습니다.

1. 에이전트 플로우로 이동합니다.
2. 플레이그라운드에서 SQL 또는 Prompt 도구 노드를 누릅니다.
   
   

   

   
   
3. 질의 필드에서 {{sessionvariables 입력을 시작합니다.
4. 기존 세션 변수 리스트에서 세션 변수를 선택합니다.

세션 변수를 사용하여 에이전트 및 도구 보기

에이전트 흐름의 [변수] 탭에서 특정 세션 변수를 사용하여 에이전트 및 도구 목록을 볼 수 있습니다.

1. 관련 에이전트 및 도구를 보려는 세션 변수를 사용하여 에이전트 흐름으로 이동합니다.
2. 변수 탭을 클릭합니다.
3. 세션 변수에 대해 사용 위치: 옆에 있는 드롭다운 메뉴를 누릅니다. 세션 변수를 사용하는 에이전트 및 도구 목록이 표시됩니다.

플레이그라운드에서 세션 변수에 값 할당

[재생] 탭에서 언제든지 세션 변수에 값을 지정할 수 있습니다.

1. 에이전트 플로우로 이동합니다.
2. 플레이그라운드 상단에서 세션 매개변수를 누릅니다. 에이전트 플로우의 모든 세션 변수 목록이 표시됩니다.
   
   

   

   
   
3. 세션 변수를 수정합니다. 플레이그라운드 세션을 재개한 후 마지막으로 할당된 세션 변수 값이 사용됩니다.
   
   

   

   
   

가드레일

가드레일은 AI 에이전트의 동작을 안내하고 제어하기 위한 안전 메커니즘입니다.

Oracle AI Data Platform Workbench에서 가드레일은 에이전트 흐름별 유독하고 악의적인 콘텐츠 생성 또는 사용을 방지하도록 구성됩니다. Guardrails는 또한 에이전트 흐름에 의한 개인 식별 정보 (PII)의 누출을 방지합니다. AI 데이터 플랫폼 워크벤치에서 사용할 수 있는 특정 보호 장치는 콘텐츠 조정, 프롬프트 삽입 및 PII에 적용됩니다.

주:

Oracle AI Data Platform Workbench에서 제공하는 가드레일은 영어로만 제공됩니다.

AI 데이터 플랫폼 워크벤치에서 제공되는 가드레일은 OCI 생성형 AI 서비스 팀이 구현합니다. OCI Generative AI용 가이드레일을 참고하세요. 가드레일 구성에 따라 AI 데이터 플랫폼 워크벤치 서비스는 OCI 테넌시 내에서 가드레일 API 적용을 호출합니다.

비주얼 플로우 캔버스의 난간

기본적으로 모델 공급자의 기본 안전 제어를 넘어서는 보호대는 시스템에 적용되지 않습니다. 난간을 추가하려면 난간 노드를 에이전트 시각적 흐름 빌더로 끌어서 에이전트에 연결해야 합니다.

보호자 노드는 채팅 트리거와 에이전트 노드 간, 감독자와 실행자 에이전트 간 또는 에이전트와 도구 노드 간 트래픽을 필터링할 수 있습니다. 대부분의 시나리오에서는 채팅 트리거와 에이전트 노드 사이에 단일 보호 한계선 노드를 사용하는 것이 좋습니다. 이렇게 하면 에이전트가 생성한 수신 사용자 및 메시지의 메시지가 보호대를 통해 필터링됩니다.

난간 노드는 다음 사이에만 삽입할 수 있습니다.

• 채팅 트리거 노드 및 에이전트(감독자 또는 실행자)

어떤 가드레일을 사용할 수 있습니까?

아래 다이어그램은 일반 사용자와 에이전트 간의 간단한 상호 작용을 보여줍니다. 이 시나리오에서는 모든 가드레일이 적용됩니다(콘텐츠 조정 - CM, 프롬프트 주입 방지 - PI 및 PII 감지 - PII). PI는 사용자 질의에만 적용됩니다.

최종 사용자가 발행한 두 번째 메시지 이후 PI 시도가 감지되었고 PI 감지(블록)에서 에이전트 개발자가 선택한 조치에 따라 사용자 메시지가 차단되었습니다.

콘텐츠 조정

콘텐츠 조정은 대부분의 생성형 AI에서 가드레일을 일반적으로 구현하는 작업입니다. 선택하지 않은 LLM은 유해한 콘텐츠를 생성하고, 폭력적이고, 인종차별적이며, 성적으로 명시적인 콘텐츠를 홍보할 수 있습니다. 에이전트 개발자에게 에이전트와의 사용자 상호 작용이 모니터링되고 스캔되는 방식에 대한 완전한 가시성과 제어력을 제공하여 잠재적으로 유해한 콘텐츠를 파악하는 것이 중요합니다. 콘텐츠 조정은 증오, 성적, 폭력적, 독성, 특례적 또는 괴롭힘 기반 콘텐츠가 에이전트 흐름에 의해 고려되거나 생성되는 것을 방지합니다. 당사의 가드레일 모델은 이러한 6가지 범주 및 해당 범주 중 하나에 속하는 플래그 콘텐츠에 따라 콘텐츠를 분류합니다.

사용자 입력 질의 또는 모델 응답에 대해 작업을 수행하도록 선택할 수 있습니다.

• 블록: 에이전트가 사용자 입력을 처리하고 응답을 생성하지 못하도록 합니다. 사용자가 에이전트 플로우에서 오류 응답을 수신합니다.
• 정보: 에이전트 플로우가 사용자 입력을 처리하고 응답을 생성할 수 있도록 허용합니다. 에이전트는 가드레일 기준을 충족하는 콘텐츠가 포함된 입력 또는 응답 중 하나임을 사용자에게 통지합니다.
• 허용: 에이전트 플로우에서 잠재적으로 유해한 콘텐츠의 처리 및/또는 생성을 허용합니다.

에이전트 플로우를 생성할 때 콘텐츠 조정에 대해 블록 작업이 선택됩니다. Oracle은 블록을 콘텐츠 조정에 대한 보호 한계선 선택으로 유지할 것을 권장합니다.

프롬프트 주입

AI 에이전트에 대한 프롬프트 사출 가드레일은 사용자 입력에 포함된 악의적이거나 의도하지 않은 지침을 감지, 방지 및 완화하는 보호 메커니즘입니다. 프롬프트 삽입 공격은 모델에 이전 규칙을 무시하거나, 암호를 추출하거나, 권한이 부여되지 않은 작업을 실행하도록 지시하는 숨겨진 텍스트를 삽입하여 에이전트의 원래 지침, 정책 또는 목표를 대체하거나 훼손하려고 시도합니다.

콘텐츠 조정에 대해 수행할 수 있는 동일한 작업(블록, 정보 또는 허용)을 선택할 수 있습니다. 프롬프트 주입 가드레일은 유저 입력 query에만 적용됩니다.

• 블록: 에이전트가 사용자 입력을 처리하지 못하도록 합니다. 사용자가 에이전트 플로우에서 오류 응답을 수신합니다.
• 정보: 에이전트 플로우가 사용자 입력을 처리할 수 있도록 허용합니다. 에이전트는 가드레일 기준을 충족하는 콘텐츠가 입력에 포함되어 있음을 사용자에게 통지합니다.
• 허용: 에이전트 플로우에서 잠재적으로 유해한 콘텐츠 처리를 허용합니다.

에이전트 플로우를 생성할 때 블록 작업이 프롬프트 삽입으로 선택됩니다. Oracle은 블록을 프롬프트 삽입을 위한 보호 한계선 선택으로 유지할 것을 권장합니다.

개인 식별 정보(PII)

PII 보호 장치는 사용자 입력 쿼리 또는 에이전트 응답에서 PII를 자동으로 감지, 차단 또는 마스킹합니다. 이 보호 장치는 에이전트가 개인 정보 보호 규정이나 조직 정책을 위반하는 방식으로 민감한 사용자 정보를 노출하지 못하도록 방지합니다.

PII 보호 레일은 다음 네 가지 엔티티 유형을 지원합니다.

• 전자메일
• Telephone number
• 물리적 주소
• 개인 이름

이러한 네 개의 엔티티 각각에 대해 에이전트가 입력 사용자 질의 또는 에이전트 응답에 대해 수행할 다음 작업 중 하나를 적용하도록 선택합니다.

• 블록: 에이전트가 사용자 입력을 처리하고 응답을 생성하지 못하도록 합니다. 사용자가 에이전트 플로우에서 오류 응답을 수신합니다.
• 정보: 에이전트 플로우가 사용자 입력을 처리하고 응답을 생성할 수 있도록 허용합니다. 에이전트는 입력 또는 응답에 PII가 포함되어 있음을 사용자에게 알립니다.
• 마스크: 에이전트 플로우가 입력을 처리하고 마스킹된 응답을 생성하도록 허용합니다. 사용되는 모든 PII는 노출을 방지하기 위해 개정됩니다.
• 허용: 에이전트 플로우에서 PII 데이터의 처리 및/또는 생성을 허용합니다.

새 에이전트 플로우에서는 기본적으로 사용자 입력과 응답 모두에서 PII가 허용됩니다. Oracle은 보안 요구사항에 따라 PII에 대한 보호 한계선을 신중하게 선택할 것을 권장합니다.

노드에서 특정 보호 한계선 사용

시각적 캔버스에 난간 노드를 추가할 때 사용으로 설정할 난간과 각각의 구성 방법을 선택할 수 있습니다.

1. 작업영역에서 에이전트 플로우로 이동합니다.
2. 팔레트에서 캔버스로 가드레일 노드를 끌어옵니다.
3. 노드에 대해 의미 있는 이름과 설명을 제공합니다.
   
   

   

   
   
4. 가드레일을 토글하여 사용으로 설정하고 구성을 시작합니다. 토글을 다시 누르면 난간 및 해당 구성이 사용 안함으로 설정됩니다.
   
   

   

   
   
5. 각 범주에 대해 필요한 난간 구성을 선택합니다.
   
   

   

   
   

에이전트에 대한 AI 클러스터 생성

에이전트 인터페이스에서 직접 새 AI 클러스터를 만들고 즉시 연결할 수 있습니다.

자세한 내용은 AI 컴퓨트를 참조하십시오.

1. Home 페이지에서 에이전트로 이동합니다.
2. 컴퓨트를 누른 다음 새 AI 컴퓨트 생성을 누릅니다.
3. AI 컴퓨트 클러스터에 대한 이름 및 설명을 제공하십시오.
4. AI 컴퓨트 클러스터에 대한 OCPU 수 및 메모리 크기를 선택합니다.
5. 생성을 누릅니다.

에이전트에 기존 AI 클러스터 연결

이전에 생성한 AI 클러스터를 적어도 USE 권한이 있는 에이전트에 연결할 수 있습니다.

1. Home 페이지에서 에이전트로 이동합니다.
2. 컴퓨트를 누른 다음 AI 컴퓨트에 연결을 누릅니다.
3. 목록에서 사용할 클러스터를 누릅니다.
   에이전트가 성공적으로 연결되면 AIcompute: (ClusterName) running이 표시됩니다. 이 작업은 최대 몇 분 정도 걸릴 수 있습니다.

AI 컴퓨트에서 에이전트 분리

AI 컴퓨트에서 에이전트를 분리할 수 있습니다. AI 컴퓨트를 분리하면 연결된 컴퓨트에서 실행되는 에이전트 코드가 제거되고 테스트가 금지됩니다.

주:

AI 컴퓨트에서 에이전트를 분리해도 에이전트는 삭제되지 않습니다. 동일하거나 다른 AI 컴퓨트에 에이전트를 연결하여 에이전트 구축 및 테스트를 재개할 수 있습니다.

1. Home 페이지에서 에이전트로 이동합니다.
2. 컴퓨트를 누른 다음 AI 컴퓨트에서 분리를 누릅니다.
   
   

   

   
   

A2A 에이전트 배치

Agent2Agent(A2A) 프로토콜은 서로 다른 프레임워크로 구축된 에이전트, 서로 다른 공급업체에서 호스팅하거나 불투명한 원격 시스템으로 실행되는 에이전트를 포함하여 독립적인 AI 에이전트 간의 통신을 위한 개방형 표준입니다.

이 회사의 목적은 이러한 에이전트가 서로의 기능을 검색하고, 지원되는 입/출력 형식을 협상하고, 작업을 위임 또는 협업하고, 내부 메모리, 도구 또는 구현 세부 정보를 노출하지 않고도 정보를 안전하게 교환할 수 있도록 공유 상호 작용 모델을 제공하는 것입니다. 자세한 내용은 Agent2Agent (A2A) Protocol을 참조하십시오.

A2A는 에이전트 상호 운용성을 해결하기 위한 것입니다. 즉, 모든 에이전트 통합이 사용자 정의되는 대신 클라이언트 또는 다른 에이전트가 공통 개념 및 작업 세트를 사용하여 A2A 호환 원격 에이전트와 상호 작용할 수 있습니다. 사양은 메시지, 작업, 부품, 아티팩트, 스트리밍 업데이트 및 푸시 알림을 중심으로 하며 동기 회신, 장기 실행 비동기 작업, 스트리밍 및 엔터프라이즈 스타일의 인증/보안 패턴을 지원합니다.

Oracle AI Data Platform에서는 배포된 모든 에이전트에 A2A 클라이언트 애플리케이션에서 호출할 수 있는 /A2A 호출 경로가 제공됩니다.

에이전트 카드란 무엇입니까?

에이전트 카드는 A2A 서버에서 게시한 JSON 메타데이터 문서입니다. AIDP에서 A2A 서버는 에이전트 배치를 호스팅하는 AI 컴퓨트입니다.

이 카드는 에이전트의 ID, 서비스 끝점, 지원되는 프로토콜/전송, 기능, 기술, 지원되는 입/출력 모드 및 인증 요구 사항에 대해 설명합니다. 클라이언트는 이 카드를 사용하여 에이전트가 적합한지 여부 및 에이전트의 호출 방법을 파악합니다. 제대로 문서화된 에이전트 카드는 A2A 프로토콜의 요구 사항입니다.

AI 데이터 플랫폼 워크벤치의 에이전트 카드는 초안 상태입니다. 즉, 에이전트가 배치되지 않았거나 게시됨입니다. 즉, 카드가 에이전트와 함께 배치되었습니다.

에이전트 카드 작업

에이전트를 개발하는 동안 에이전트의 작업 메뉴에서 카드를 사용할 수 있습니다.

다음 두 에이전트 카드에 액세스할 수 있습니다.

• 초안 카드는 개발 중인 에이전트의 현재 상태를 반영합니다.
• 게시된 카드는 에이전트가 배포될 때 찍은 카드의 스냅샷에 해당합니다. 게시된 카드는 배치된 에이전트의 상태를 반영합니다.

에이전트 카드 필드

AI Data Platform Workbench는 현재 A2A 프로토콜 에이전트 카드 필드의 하위 세트를 지원합니다(여기서는 A2A 프로토콜 - 에이전트 카드).

필드	필수사항	설명
name	예	에이전트에 대한 사람이 읽을 수 있는 이름입니다. 예: "레시피 에이전트"
description	예	에이전트에 대한 사람이 읽을 수 있는 설명으로, 사용자와 다른 에이전트가 해당 목적을 이해할 수 있도록 지원합니다. 예: "사용자에게 조리법 및 요리를 제공하는 데 도움이 되는 에이전트입니다."
Agent Version	예	에이전트의 버전입니다. 예: "1.0.0"
Documentation URL	아니요	에이전트에 대한 추가 설명서를 제공하는 URL입니다.
Provider - Organization	아니요	에이전트의 서비스 제공자입니다.
Provider - URL	아니요	서비스 제공자의 URL입니다.
Capabilities	예	에이전트에서 지원하는 A2A 기능 세트입니다. streaming만 구성할 수 있음(True/False)
Skills	예	기술은 에이전트의 능력을 나타냅니다. 그것은 대체로 설명적인 개념이지만 에이전트가 성공할 가능성이 더 큰 일련의 행동을 나타냅니다. 기술은 AgentSkill의 배열을 나타냅니다.

각 AgentSkill은 에이전트의 기능을 문서화하는 여러 필드로 구성됩니다. 에이전트 카드에서 에이전트 기술 정의는 시간이 가장 많이 걸리는 작업이며 반복 프로세스입니다. 배포 전에 초안 에이전트 카드에서 기술(나머지 에이전트 카드와 함께)을 편집할 수 있습니다.

주:

inputModes, outputModes 및 securityRequirements는 AI 데이터 플랫폼 워크벤치에서 제공되며 수정할 수 없습니다.

필드	필수사항	설명
Skill ID	예	에이전트 스킬에 대한 고유 식별자입니다.
Skill Name	예	스킬에 대한 사람이 읽을 수 있는 이름입니다.
Description	예	기술에 대한 자세한 설명입니다.
Tags	예	스킬의 기능을 설명하는 키워드 세트입니다.
Examples	아니요	이 스킬이 처리할 수 있는 프롬프트 또는 시나리오의 예입니다.

에이전트 배치 끝점 A2A 경로

/a2a 경로는 /chat 외에도 배포된 에이전트의 URL에 표시됩니다.

예를 들어, 에이전트는 다음 경로를 외부 클라이언트에 노출합니다.

• https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/chat
• https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a

두 경로(/chat, /a2a) 모두 별도의 클라이언트에서 사용할 수 있습니다.

A2A의 세션 변수

세션 변수의 값은 메시지 metadata 필드에서 A2A 에이전트로 전달할 수 있습니다. 아래 JSON 코드 조각은 세 개의 세션 변수(userName, geoLocation 및 os)가 있는 a2a 에이전트에 발행된 사용자 메시지의 페이로드를 보여줍니다.

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "contextId": "session_12345",
    "taskId": "task_67890",
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "What is the current status of my order?",
        }
      ],
      "metadata": {
        "sessionvariables.userName": "George",
        "sessionvariables.geoLocation": “Dallas, TX”,
        "sessionvariables.os": "mobile_ios"
      }
    }
  },
  "id": "rpc-99821"
}

예: OCI CLI를 사용하여 A2A 에이전트 호출(비스트리밍)

oci raw-request \
  --http-method POST \
  --auth security_token \
  --request-body '{
    "id": "<your-request-id>",
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "configuration": {
        "acceptedOutputModes": [
          "text/plain",
          "text"
        ]
      },
      "message": {
        "contextId": "<your-context-id>",
        "kind": "message",
        "messageId": "<your-message-id>",
        "parts": [
          {
            "kind": "text",
            "text": "What is the capital of India?"
          }
        ],
        "role": "user"
      }
    }
  }' \
  --request-headers '{
    "x-session-id": "<your-session-id>",
    "dh-user-principal": "<your-user-principal>"
  }' \
  --target-uri " <your-a2a-agent-endpoint-url>"

예: OCI CLI를 사용하여 A2A 에이전트 호출(스트리밍)

oci raw-request \
  --http-method POST \
  --auth security_token \
  --request-body '{
    "id": "<your-request-id>",
    "jsonrpc": "2.0",
    "method": "message/stream",
    "params": {
      "configuration": {
        "acceptedOutputModes": [
          "text/plain",
          "text"
        ]
      },
      "message": {
        "contextId": "<your-context-id>",
        "kind": "message",
        "messageId": " <your-message-id>",
        "parts": [
          {
            "kind": "text",
            "text": "What is the capital of India?"
          }
        ],
        "role": "user"
      }
    }
  }' \
  --request-headers '{
    "x-session-id": "<your-session-id>",
    "dh-user-principal": "<user-principal>"
  }' \
  --target-uri "<your-a2a-agent-endpoint-url>"

예: A2A 클라이언트 SDK

import asyncio
import json
import logging
import typing
from collections.abc import Iterator
import uuid
import httpx
import oci
from a2a.client import A2AClient, ClientFactory
from a2a.types import (
    AgentCard,
    Message,
    Part,
    Role,
    TextPart,
    SendMessageRequest,
    MessageSendParams,
    MessageSendConfiguration,
    Task, SendMessageSuccessResponse, SendStreamingMessageRequest,
)

class OCIAuth(httpx.Auth):
    """httpx auth implementation using OCI signer via requests auth adapter."""

    def __init__(self, signer: oci.signer.AbstractBaseSigner):
        self._requests_auth = _OCIRequestsAuth(signer)

    def auth_flow(self, request: httpx.Request) -> Iterator[httpx.Request]:
        req = RequestsRequest(
            method=request.method,
            url=str(request.url),
            headers=dict(request.headers),
            data=request.content,
        )
        prepared: RequestsPreparedRequest = req.prepare()
        prepared = self._requests_auth(prepared)
        request.headers.update(dict(prepared.headers))
        yield request



def getOCIAuth():
    conf = oci.config.from_file(profile_name="DEFAULT")
    token_file = conf['security_token_file']
    token = None
    with open(token_file, 'r') as f:
        token = f.read()
    private_key = oci.signer.load_private_key_from_file(conf['key_file'])
    signer = oci.auth.signers.SecurityTokenSigner(token, private_key)
    auth = OCIAuth(signer=signer)
    return auth


async def _call_agent_with_a2a(agent_url: str, query: str, context_id: str,auth:OCIAuth) -> str:
    """Call an agent using the A2A protocol."""
    try:
        # Initialize OCI signer
        #headers = {"dh-user-principal": "dh-user"}
        headers = {"Accept": "*/*",
                   "dh-user-principal": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}

        async with httpx.AsyncClient(timeout=60.0, auth=auth,headers=headers) as hc:
            agent_card = await _get_agent_card(agent_url,auth)
            print(f"Agent card is {agent_card}")

            client =  A2AClient(httpx_client=hc, agent_card=agent_card)
            # Create message
            message = Message(
                message_id=str(uuid.uuid4()),
                context_id=context_id,
                role=Role.user,
                parts=[Part(root=TextPart(text=query))],
                metadata={"sessionvariables.cred.mcp.weatherReportMCP.bearer": "valid-123"}
            )
            request = SendMessageRequest(
                id=str(uuid.uuid4()),  # Add the required id field
                params=MessageSendParams(
                    message=message,
                    configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
                ),
            )
            #json_string = json.dumps(message, indent=4)
            print(f"Send request : {request}")

            response = await client.send_message(request)

            logging.info("Received response from A2A server: %s", response.root.result)
            # Extract response
            result = response.root.result
            # Handle different response types


            if isinstance(result, Task):
                # Task response
                if result.artifacts:
                    # Extract text from artifacts
                    texts = []
                    for artifact in result.artifacts:
                        for part in artifact.parts:
                            if hasattr(part, "root") and hasattr(part.root, "text"):
                                texts.append(part.root.text)
                    return "\n".join(texts) if texts else "Task completed with no text response"
                elif result.status and result.status.message:
                    logging.info(f"Received Task status {result.status.state} from A2A server and status message is {result.status.message}", result.status.message)
                    if  result.status.state== "failed":
                        print("Failure observed in Task invocation")
                        for m_part in result.status.message.parts:
                           print(f"Error message  { m_part.root.text}")

                    return get_message_text(result.status.message)
                else:
                    return f"Task {result.id} status: {result.status.state if result.status else 'unknown'}"

            elif isinstance(result, Message):
                return get_message_text(result)
            else:
                logging.warning(f"Unexpected response type: {type(result)}")
                return "Received response but unable to extract text"
    except Exception as ex:
        logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
        return f"Error communicating with agent: {str(ex)}"


async def _call_agent_with_a2a_with_stream(agent_url: str, query: str, context_id: str, auth: OCIAuth) -> str:
    """Call an agent using the A2A protocol with streaming (SSE) and return the final artifact text."""
    try:
        async with httpx.AsyncClient(timeout=60.0, auth=auth) as hc:
            agent_card = await _get_agent_card(agent_url)
            if not agent_card:
                return "No Agent Card Found"
            print(f"Agent card is {agent_card}")

            client = A2AClient(httpx_client=hc, agent_card=agent_card)
            message = Message(
                message_id=str(uuid.uuid4()),
                context_id=context_id,
                role=Role.user,
                parts=[Part(root=TextPart(text=query))],
            )
            request = SendStreamingMessageRequest(
                id=str(uuid.uuid4()),
                params=MessageSendParams(
                    message=message,
                    configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
                ),
            )
            print("Invoking Remote Agent request (beautified JSON):")
            print(json.dumps(request.model_dump(), indent=2, ensure_ascii=False))
            # Expected event types:
            # - TaskStatusUpdateEvent (working/in-progress)
            # - TaskArtifactUpdateEvent (contains Artifact.parts[].root.text) -> final output
            final_artifact_text_parts: list[str] = []

            async for event in client.send_message_streaming(request):
                # Print each SSE event as-is (SDK object)
                print(f"[A2A stream event] {event}")

                try:
                    result = getattr(event.root, "result", None)
                    if not result:
                        continue

                    # TaskArtifactUpdateEvent and TaskStatusUpdateEvent are SDK types; to avoid tight coupling,
                    # extract by attribute presence.
                    artifact = getattr(result, "artifact", None)
                    if artifact and getattr(artifact, "parts", None):
                        for part in artifact.parts:
                            root = getattr(part, "root", None)
                            txt = getattr(root, "text", None)
                            if txt:
                                final_artifact_text_parts.append(txt)
                except Exception:
                    # Keep streaming even if an event can't be parsed
                    continue

            return "\n".join([t for t in final_artifact_text_parts if t]).strip() or "Stream completed (no artifact text)."
    except Exception as ex:
        logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
        return f"Error communicating with agent: {str(ex)}"

초안 에이전트 카드 편집

아직 배포되지 않은 에이전트의 에이전트 카드를 편집할 수 있습니다.

1. 에이전트로 이동합니다.
2. 작업을 누른 다음 에이전트 카드 보기 및 에이전트 카드 초안을 누릅니다.
   
   

   

   
   
3. 편집을 누릅니다.
   
   

   

   
   
4. 오른쪽 상단에서 양식 또는 JSON을 눌러 뷰를 전환할 수 있습니다. JSON 뷰는 더 완전하지만 읽기 전용입니다. 양식 보기의 필드만 편집할 수 있습니다.
   
   

   

   
   
5. 필요에 따라 필드를 수정합니다.
6. 스킬 추가를 눌러 A2A 클라이언트에 표시할 스킬을 추가합니다.
   
   

   

   
   
7. 저장을 누릅니다.

게시된 에이전트 카드 편집

에이전트를 배치 해제하거나 재배치하지 않고 게시된 에이전트 카드를 수정할 수 있습니다.

게시된 카드는 배포 시 초안 카드의 스냅샷에 해당합니다.

주:

게시된 카드에 대한 변경 사항은 즉시 A2A 클라이언트가 액세스할 수 있는 agent-card.json 파일에 반영됩니다.

1. 에이전트로 이동합니다.
2. 작업을 누른 다음 에이전트 카드 보기 및 게시된 에이전트 카드를 누릅니다.
   
   

   

   
   
3. 오른쪽 상단에서 양식 또는 JSON을 눌러 뷰를 전환할 수 있습니다. JSON 뷰는 더 완전하지만 읽기 전용입니다. 양식 보기의 필드만 편집할 수 있습니다.
4. 편집을 누릅니다.
   
   

   

   
   
5. 필요에 따라 필드를 수정합니다.
6. 스킬 추가를 눌러 A2A 클라이언트에 표시할 스킬을 추가합니다.
   
   

   

   
   
7. 변경사항 게시를 누릅니다.

게시된 에이전트 카드는 공개적으로 사용할 수 없습니다. agent-card.json의 내용을 검사하려면 사용자를 인증하고 올바른 권한(READ)이 있어야 합니다. 다른 에이전트는 표준 경로에서 HTTP GET 요청을 통해 에이전트 기능 및 메타데이터를 검색할 수 있습니다.

https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a/agent-card.json

에이전트 배치

에이전트를 배치하면 에이전트가 호스트된 응용 프로그램으로 전환됩니다.

플레이그라운드 또는 다른 AI 컴퓨트에 연결된 동일한 AI 컴퓨트에 에이전트를 배포할 수 있습니다. 에이전트에 대한 최신 변경사항을 연결된 AI 컴퓨트에 배포할 때 배포된 에이전트는 배포 시 에이전트의 스냅샷을 나타냅니다. 배치된 에이전트를 최신 버전으로 업데이트하려면 에이전트를 재배치해야 합니다.

각 에이전트에는 고유한 에이전트 키에 따라 달라지는 안정적인 배포 URL이 있습니다. 에이전트를 여러 번 재배치하면 에이전트가 배치 URL 뒤에 덮어씁니다.

에이전트 배치에는 다음과 같은 제한 사항이 있습니다.

• 에이전트는 지정된 시간에 하나의 AI 컴퓨트 클러스터에만 배치할 수 있습니다.
• 동일한 에이전트를 동일한 AI 컴퓨트 클러스터에 여러 번 배치하면 이전에 배치된 에이전트의 반복이 겹쳐쓰여집니다.

에이전트를 배치한 후에는 채팅 URI를 검색하여 에이전트의 세부정보 탭에서 프로그래밍 방식으로 질의를 실행하고 에이전트에서 응답을 검색할 수 있습니다.

끝점 URL이 안정적이며 각 에이전트에 연결됩니다. URL에는 각 에이전트에 지정된 고유한 agentID가 포함됩니다. 즉, 에이전트의 배치를 해제하고 다시 배치하는 경우 URL은 동일하게 유지됩니다. 단점은 끝점을 호출하는 클라이언트 코드를 수정할 필요가 없다는 것입니다. 단점은 운용 중인 에이전트를 겹쳐쓸 수 있다는 것입니다.

URL의 구조는 다음과 같습니다.

https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/{protocol}

설명:

• oci-region는 AI 데이터 플랫폼 인스턴스 리전에 해당합니다.
• agentId은 에이전트와 연관된 고유 ID입니다.
• protocol는 통신 프로토콜입니다. chat는 OpenAI Responses API 형식을 따르고 a2a는 에이전트-에이전트 통신 프로토콜을 따릅니다. 각 에이전트 끝점에 대해 두 프로토콜을 모두 사용할 수 있습니다. 자세한 내용은 A2A 에이전트 배치를 참조하십시오.

주:

Details(세부정보) 탭에는 두 개의 AI 컴퓨트가 나열됩니다. Attached to AI Compute(AI 컴퓨트에 연결됨)는 플레이그라운드에서 에이전트를 테스트하는 데 사용됩니다. AI 컴퓨트에 배포됨은 배포된 에이전트를 호스팅합니다.

에이전트를 배치하면 끝점 URL 필드가 채워집니다. 운용 애플리케이션에서 이 끝점 URL을 호출할 수 있습니다.

에이전트 배치

생성한 에이전트를 배치하여 다른 사용자가 AI 데이터 플랫폼 인스턴스에서 보고 사용할 수 있도록 합니다.

1. 홈 페이지에서 배치할 에이전트가 포함된 폴더로 이동합니다.
2. 에이전트 옆에 있는 작업을 누르고 배치를 누릅니다. 에이전트 이름을 누르고 오른쪽 상단에서 배치를 누를 수도 있습니다.
   
   

   

   
   
3. 배치된 에이전트에 연결할 AI 컴퓨트를 선택합니다.
4. 승인 유형에 대해 AIDP 워크벤치를 선택합니다.
5. 세션 데이터 보존 정책을 선택합니다.
   • 보유 기간의 경우 세션 데이터가 보존되는 기간(일)을 제공합니다.
   • 세션 크기 제한의 경우 세션이 도달할 수 있는 최대 크기를 제공합니다.
   • 스레드 수 제한에 대해 보존되는 최대 세션 스레드 수를 제공합니다.
6. 배치를 누릅니다.

OAuth2로 에이전트 배치

OAuth2 인증을 사용하여 외부 ID 제공자에 연결하도록 생성 및 구성된 에이전트를 배치할 수 있습니다.

1. 홈 페이지에서 배치할 에이전트가 포함된 폴더로 이동합니다.
2. 에이전트 옆에 있는 작업을 누르고 배치를 누릅니다. 에이전트 이름을 누르고 오른쪽 상단에서 배치를 누를 수도 있습니다.
   
   

   

   
   
3. 배치된 에이전트에 연결할 AI 컴퓨트를 선택합니다.
4. 권한 부여 유형에 대해 OAuth2를 선택합니다.
5. 대상자 청구를 제공합니다. AI 데이터 플랫폼 워크벤치는 이 필드를 자동으로 채우지만 ID 제공자의 대상자 클레임으로 대체할 수 있습니다.
6. JWKS를 검색할 발행자 클레임 및 URI를 제공합니다. 이 정보는 ID 제공자에서 파생됩니다.
7. 세션 데이터 보존 정책을 선택합니다.
8. 배치를 누릅니다.

배치된 에이전트 호출

운용 응용 프로그램에서 에이전트의 끝점 URL을 호출할 수 있습니다.

에이전트 엔드포인트를 호출하는 데 사용되는 프로그래밍 인터페이스에 관계없이 OCI를 통해 인증되고 관련 권한이 있어야 합니다. 에이전트 플로우 끝점의 경우 호출자는 에이전트 끝점에 대해 최소한 USE 권한을 가져야 합니다.

끝점 URI는 에이전트 UI의 세부정보 탭에 문서화되어 있습니다. 해당 끝점 URI를 코드에 복사하여 에이전트를 호출할 수 있습니다.

끝점 URI를 호출하는 메소드

다양한 도구, SDK 및 CLI를 통해 에이전트 끝점 URI를 호출할 수 있습니다.

다음 메소드를 사용하여 Oracle AI Data Platform Workbench 에이전트에서 끝점 URI를 호출할 수 있습니다.

OCI CLI로 호출

제공된 예제는 OCI CLI를 사용하고 보안 토큰을 사용하여 인증하는 방법을 보여줍니다. <your-agent-flow-endpoint-uri>를 에이전트 끝점 URI로 바꾸고 <security_token>를 OCI 보안 토큰으로 바꿉니다.

oci raw-request
--http-method POST
--target-uri <your-agent-flow-endpoint-uri>
--request-body '{"query":"Tell me about the Ryder Cup in 1985"}'
--auth <security_token>

Python 요청 라이브러리로 호출

OCI Python SDK를 사용하여 OCI로 인증할 서명자를 생성할 수 있습니다. Python 요청 라이브러리는 에이전트 끝점 URI에 요청을 게시하고 응답을 반환하는 데 사용할 수 있습니다. 다음 예제는 OCI 구성 및 전용 키 파일을 통해 사용자 주체를 사용하는 방법을 보여줍니다.

import oci import requests import json import uuid from contextlib import closing from requests import Request, Response
class AuthHelper: """ AuthHelper allows creating an OCI signer with either API key or security_token (which are short term sessions) """ def init(self, oci_profile: str, use_security_token:bool = True): config = oci.config.from_file(file_location="/Volumes/jr/default/misc/config",profile_name=oci_profile) if use_security_token: with open(config["security_token_file"], 'r') as f: token = f.read() private_key = oci.signer.load_private_key_from_file(config["key_file"])
 self.signer = oci.auth.signers.SecurityTokenSigner(token, private_key) else: self.signer = oci.signer.Signer( tenancy=config["tenancy"], user=config["user"], fingerprint=config["fingerprint"], private_key_file_location=config["key_file"], #pass_phrase=config.get("pass_phrase"), #private_key_content=config.get("key_content") )
@property
def Signer(self):
    return self.signer
 
class MyRawJsonRpcClient: """ Simple class using requests lib to post JSON to chat endpoint using OCI signing """ def init(self, chat_url:str, oci_profile: str, sessionKey:str, use_security_token:bool = True): self.authhelper = AuthHelper(oci_profile=oci_profile, use_security_token=use_security_token) self.authsigner = self.authhelper.Signer self.chat_url = chat_url self.sessionKey = sessionKey
def send(self, input:str) -> Response:
    body = {
        "isStreamEnabled" : False,
        "sessionKey" : self.sessionKey,
        "trace" : False,
        "input" :[{
            "role":"User",
            "content":[{
                "type" : "INPUT_TEXT",
                "text" : input                   
            }]
        }]
    }

    response:Request = requests.post(
        url =self.chat_url,
        params = None,
        auth = self.authsigner,
        json=body,
        headers={}
    )
    return response

MyRawJsonRPCClient 클래스를 인스턴스화하고 OCI 프로파일 값(OCI 구성 파일에 있음), 에이전트 끝점 URI(chat_url) 및 sessionKey를 제공하여 에이전트 끝점 URI를 호출할 수 있습니다. 임의의 sessionKey을 제공할 수 있습니다. sessionKey은 에이전트와 사용자 세션의 고유 식별자입니다. 동일한 sessionKey를 계속 재사용하는 경우 사용자 메시지와 에이전트 응답이 동일한 보존에 추가됩니다.

client = MyRawJsonRpcClient(chat_url="<your-agent-flow-endpoint-uri>",
   oci_profile = "DEFAULT",
   sessionKey= “<your-session-key>”,
   use_security_token = False )

사용자 메시지를 제공하고 클라이언트를 사용하여 에이전트 끝점 URI로 메시지를 보낼 수도 있습니다.

user_input = f"Hello, tell me a good dad joke."
r = client.send(input = user_input)
response_json = r.json()

APEX 사용

AI Data Platform Workbench 샘플 Github 저장소에서 사용 가능한 코드 샘플을 사용할 수 있습니다. 이 샘플은 APEX 애플리케이션에서 에이전트 배치 끝점을 호출하는 프로세스를 안내합니다.

Streamlit을 통해

AI Data Platform Workbench 샘플 Github 저장소에서 사용 가능한 코드 샘플을 사용할 수 있습니다. 샘플은 Streamlit 애플리케이션에서 에이전트 배치 끝점을 호출하는 프로세스를 안내합니다.

모범 사례 - 비동기 및 비동기 응답

비동기 응답을 가정하는 클라이언트 코드를 작성하는 것이 좋습니다. 예:

import httpx 
 
async def fetch_data(): 
    async with httpx.AsyncClient() as client: 
        response = await client.get(URL) 
        return response.json()

에이전트 배치 해제

MANAGE 권한이 있는 에이전트를 사용할 수 없도록 배치 해제하도록 선택할 수 있습니다.

1. 홈 페이지에서 배치를 해제할 에이전트가 포함된 폴더로 이동합니다.
2. 에이전트 옆에 있는 작업을 누르고 배치 해제를 누릅니다.
   
   

   

   
   
3. 배치 해제를 누릅니다.

에이전트 모니터

에이전트의 세션 및 측정 단위와 관련된 세부 정보를 모니터링하여 사용 방법, 사용 리소스 등에 대한 정보를 확인할 수 있습니다.

사용 세부정보를 추적하기 위한 탭이 에이전트에 여러 개 있고, 세션 탭, 측정항목 탭 및 작업 탭이 있습니다. 에이전트 캔버스 상단에서 찾을 수 있습니다.

추적 및 범위

추적은 에이전트 요청의 플로우를 캡처하고 표시하여 에이전트에 대한 관찰 가능성을 제공합니다. 범위는 추적을 구성하는 객체입니다. 각 범위는 사용자의 채팅 프롬프트, 에이전트 호출 및 워크플로 태스크와 같은 흐름의 다른 단계입니다.

현재 세션이나 테스트 실행 또는 이전 세션에 대한 Trace를 확인할 수 있습니다. 현재 세션 추적을 보려면 Flow 탭으로 이동하여 Playground를 누릅니다. 페이지 하단의 Details 창에는 왼쪽 창에 현재 세션의 Trace가 표시됩니다. 추적에서 객체를 눌러 확장하거나 더 자세한 정보를 볼 수 있습니다. 오른쪽 창에서 정보, 세부정보 또는 이벤트 탭을 눌러 선택한 범위 객체에 대해 자세히 알아볼 수 있습니다.

세션 이름을 눌러 세션 탭에서 이전 세션에 대한 추적을 확인할 수 있습니다.

세션

세션 탭에서는 이 에이전트에 대한 세션 내역을 볼 수 있습니다. 각 세션이 성공 또는 실패했는지 여부, URI 원본, 세션이 시작되었을 때, 세션 기간 및 세션에 사용된 토큰을 확인할 수 있습니다. 세션 ID를 눌러 해당 세션에 대한 세부 정보를 확인하고 해당 특정 세션에 대한 Trace를 확인할 수 있습니다.

검색 표시줄을 사용하여 세션 ID 또는 URI 원점별로 필터링하고, 날짜 필터를 사용하여 특정 날짜 범위만 표시하고, 세션 상태 드롭다운 메뉴를 사용하여 세션 성공 또는 실패 여부를 필터링하여 표시된 세션을 필터링할 수 있습니다.

측정 단위

측정항목 탭에는 모든 에이전트 세션에 대한 사용량 데이터 요약이 표시됩니다. 일자 범위 드롭다운은 표시된 카드에 요약되어 표시할 기간을 필터링합니다. URI 선택은 세부정보를 확인할 URI 선택 소스를 필터링합니다. 표시할 카드와 그래프를 시각적 사용 표현으로 포함할지 여부를 수정할 수 있습니다.

작업

작업 탭에는 에이전트 배치 상태에 대한 요약이 표시됩니다. 작업 열은 배치 작업 유형(배치 또는 배치 해제)을 지정하고 상태 열은 작업 결과(성공, 오류, 경고, 실패)를 지정합니다. 작업을 시작한 사람과 시기 및 작업 결과와 연계된 상태 메시지를 확인할 수 있습니다.

에이전트 세션 보기

에이전트의 세션 기록을 보고 결과를 필터링하여 추세를 확인하고 문제 해결을 지원할 수 있습니다.

1. Home 페이지에서 에이전트로 이동합니다.
2. 세션 탭을 누릅니다.
3. 필터를 사용하여 표시된 세션을 변경합니다.

에이전트 측정항목 보기

토큰 사용량, 세션 기간, 대기 시간 등과 같은 에이전트에 대한 요약된 세부정보를 볼 수 있습니다.

1. Home 페이지에서 에이전트로 이동합니다.
2. 측정항목 탭을 누릅니다.
3. 일자 범위 드롭다운에서 다른 옵션을 선택하여 타임라인 간에 측정항목이 어떻게 다른지 확인합니다.
4. 특정 URI 소스에 대해 필터링하려면 URI 선택 드롭다운에서 다른 옵션을 선택합니다.

에이전트 이동

소유하거나 관리 권한이 있는 에이전트를 이동할 수 있습니다.

1. 홈 페이지에서 이동할 에이전트가 포함된 폴더로 이동합니다.
2. 수정할 에이전트 옆에 있는 작업을 누르고 이동을 누릅니다.
3. 에이전트의 새 작업 영역 위치를 선택합니다. 이동을 누릅니다.

상담원 복사

소유한 에이전트를 복사하거나 사용 가능한 작업영역을 다른 위치에 대해 관리 권한을 가질 수 있습니다.

에이전트를 동일하거나 다른 폴더에 복사할 수 있습니다. 에이전트 플로우는 액세스 권한이 있는 여러 작업 영역의 폴더로 복사할 수 있습니다. 에이전트 구성과 도구 및 난간 설정이 복사됩니다. AI 컴퓨트 클러스터 연결은 복사되지 않으며, 개발을 재개하려면 새 AI 컴퓨트 클러스터에 에이전트를 연결해야 합니다.

1. 홈 페이지에서 이동할 에이전트가 포함된 폴더로 이동합니다.
2. 수정할 에이전트 옆에 있는 작업을 누르고 작업 영역으로 복사를 누릅니다.
3. 필요한 경우 복사된 에이전트에 대한 새 이름과 설명을 제공합니다.
4. 찾아보기를 누르고 작업 영역에서 에이전트를 복사할 새 위치를 선택합니다. 선택을 누릅니다.
5. 복사를 누릅니다.

에이전트 파일 다운로드

에이전트 파일 및 해당 에이전트에 대한 정의가 포함된 해당 난간 파일을 다운로드할 수 있습니다.

에이전트 파일은 파일 확장자가 AFLOW인 JSON 파일이며 에이전트에 대한 정의를 포함합니다. 가드레일 파일의 레이블은 _guardrails.JSON이며 에이전트에 대한 가드레일 정의를 포함합니다.

1. 작업 영역의 에이전트 폴더로 이동합니다.
2. 다운로드할 에이전트의 이름을 누릅니다.
   
   

   

   
   
3. 에이전트의 AFLOW 파일 옆에 있는 작업을 누른 다음 다운로드를 누릅니다. 파일이 로컬 시스템으로 다운로드됩니다.
4. _guardrails.JSON 파일 옆에 있는 작업을 누른 다음 다운로드를 누릅니다. 파일이 로컬 시스템으로 다운로드됩니다.