17 에이전트 만들기

이 섹션에서는 시각적 흐름 빌더 또는 코드를 통해 AI 에이전트를 생성하는 방법을 다룹니다.

항목:

• 다중 에이전트 시스템 및 상위자 패턴
• 시각적 흐름 캔버스 정보
• 코드를 통한 에이전트
• 에이전트 테스트

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

멀티 에이전트 시스템은 하나의 대규모 다목적 에이전트가 아닌 여러 협력 에이전트가 사용자 요청을 처리하는 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(모델) 탭에서 설정을 수정하여 에이전트 노드를 구성할 수 있습니다.

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

표 17-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 환경을 실행하기 위해 에이전트 시스템에 연결됩니다.

표 17-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.

표 17-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. 삭제를 누릅니다.