도구와 액터

도구와 액터를 각각 만든 뒤 에이전트에 연결합니다. 하나의 도구나 액터를 여러 에이전트에 연결할 수 있습니다.

도구

도구는 에이전트가 작업 중에 불러 쓰는 기능 하나하나를 말합니다. 목록 페이지에서는 유형 필터 버튼과 개수 배지로 도구를 유형별로 찾습니다.

도구·액터 목록에서 여러 행을 선택하면 삭제를 순차 실행합니다. 삭제 권한이 없거나 확인 중인 행은 선택 대상에서 제외됩니다. 필터 결과 전체 선택과 부분 실패 규칙은 첫 화면의 관리 목록 공통 동작에서 확인합니다.

유형

유형	설명
Python	Python 스크립트로 작성하는 사용자 정의 도구
에이전트	다른 에이전트를 도구처럼 호출

에이전트 유형을 선택하면 다른 에이전트를 도구처럼 호출합니다. 파이프라인을 호출하는 워크플로우 유형은 새 도구 생성 화면에서 제공하지 않습니다.

이 방식은 도구 자산을 따로 만드는 절차입니다. AI 에이전트의 기능 구성 → 에이전트에서 직접 위임 대상을 고르는 방식은 다른 에이전트에 위임하기에서 확인합니다.

편집 필드

• 이름 / 별칭 / 설명: 기본 정보입니다. AI 자동 생성 버튼을 누르면 설명을 제안합니다.
• 유형: Python / 에이전트 중에서 고릅니다.
• 입력 스키마: 도구를 부를 때 넘겨야 할 파라미터를 JSON Schema로 정의합니다.
• 실행 로직:
  • Python: Python 스크립트. 커넥터 섹션에서 스크립트가 사용할 연결(커넥터)을 고를 수 있습니다.
  • 에이전트: 호출할 에이전트를 선택합니다.

사람 승인은 도구가 아니라 액터에 설정합니다

실행 전 사람의 승인이 필요한 단계는 도구가 아니라 액터의 확인 정책으로 지정합니다. 정책 값과 승인 화면은 확인 정책에서 확인합니다.

테스트 실행 (Python 도구)

Python 도구 편집 화면의 구현 탭에는 테스트 실행 섹션이 있습니다. 도구를 저장하거나 에이전트에 연결하기 전에 작성 중인 코드를 실행해 결과를 확인합니다.

• 입력값: 도구 함수에 넘길 JSON 객체를 입력합니다. 필수 파라미터가 있으면 기본 템플릿이 미리 채워집니다.
• 실행 결과: 성공/실패, 걸린 시간, 반환값(또는 오류)이 그대로 표시됩니다. 결과는 화면에만 남고 따로 기록으로 저장되지는 않습니다.

테스트 실행은 실제로 코드를 실행합니다

테스트 실행은 작성한 Python 코드를 실행하며 외부 서비스 호출도 수행합니다. 테스트용 입력과 연결 정보만 사용합니다. 이 기능은 Python 유형 도구에만 표시됩니다.

구성 탭

Python 도구의 구성 탭에서 실행 환경과 호출 지침을 설정합니다. 에이전트 유형 도구에는 실행 환경 항목 없이 호출 예시가 표시됩니다.

• 의존성: 쉼표로 구분해 Python 패키지를 입력합니다(예: requests>=2.31). 공백과 빈 항목은 저장할 때 제거됩니다.
• 브라우저 필요: 웹 브라우저를 탐색·조작할 실행 환경이 필요한 도구에 켭니다. 도구 연결이나 이 값을 바꾼 뒤 실행 중 에이전트에 반영하려면 다시 배포합니다.
• 도구 호출 예시: 선택 설명과 필수 인자 JSON 객체를 여러 개 저장합니다. 배열이나 문자열 같은 JSON 값은 사용할 수 없습니다.

호출 예시는 에이전트가 입력 형식을 고를 때 참고하는 지침으로 도구 정의에 저장됩니다. 테스트 실행의 입력값은 화면에만 남으므로 서로 다릅니다. 호출 예시는 Python·에이전트 유형에 모두 표시되고, 의존성과 브라우저 필요는 Python 도구에만 표시됩니다. 기본 제공 도구에서는 모두 읽기 전용입니다.

데코레이터 바인딩

Python 도구와 액터의 구성 → 데코레이터 바인딩에서 소스를 고치지 않고 실행 리소스를 연결합니다. 행마다 다음 값을 입력합니다.

• 데코레이터: use_connector, use_llm, use_rag처럼 use_로 시작하는 등록 이름
• 바인딩 이름: 실행 함수에서 사용할 올바른 Python 변수명
• 인자: 선택 JSON 객체. 예약 키 name은 넣지 않고 바인딩 이름 필드를 사용합니다.

같은 데코레이터와 바인딩 이름 조합은 중복할 수 없습니다. 소스 코드의 @use_* 선언과 같은 종류·이름이 겹치면 구성 행에 설정 우선이 표시되고 구성 값이 적용됩니다. 구성 행이 없으면 소스 선언을 사용합니다.

포털은 이름이 use_ 형식인지 검사합니다. 실제로 등록되지 않은 데코레이터는 저장되더라도 실행 리소스를 해석할 때 실패할 수 있습니다. 코드 편집기에서 소스에 데코레이터를 삽입하는 방법은 코드에서 확인합니다.

기본 제공 도구·액터의 데코레이터 바인딩은 읽기 전용입니다. 변경하려면 목록이나 편집 화면의 복사하여 만들기로 편집 가능한 사본을 만든 뒤 구성합니다.

기본 제공 도구와 복사하여 만들기

기본 제공 배지가 있는 도구는 읽기 전용입니다. 로직이나 연결된 커넥터를 변경하려면 편집 화면 헤더에서 복사하여 만들기를 누릅니다. 원본의 이름·컬렉션·설명·소스·파라미터·커넥터·태그가 채워진 편집 가능한 사본이 열립니다. 이 사본에는 기본 제공 도구의 편집 제한이 적용되지 않습니다.

기본 제공 자연어 자산 계획 기능은 다음 도구와 액터를 한 쌍으로 사용합니다.

• resource_plan_propose 도구는 자연어 요청을 자산 계획으로 검증하고 읽기 전용 미리보기를 만듭니다. 이 단계에서는 자산을 생성·변경·삭제하지 않습니다.
• resource_plan_apply 액터는 미리 본 계획과 계획 해시가 일치할 때 승인 카드를 표시합니다. 확인 정책은 confirm으로 고정되며 사용자가 승인한 뒤에만 계획을 적용합니다.

AI 에이전트에서 자연어 자산 작업을 제공하려면 두 항목을 모두 연결합니다. 한 계획에는 최대 24개 항목을 넣을 수 있으며 컬렉션·폴더·데이터셋·코드·파이프라인·대시보드·온톨로지 엔티티·온톨로지 관계·지식·프롬프트·시맨틱 테이블·값 사전·질의 템플릿을 생성·변경·삭제합니다. 데이터 연결, 시크릿, 에이전트·도구·액터, LLM 모델은 이 계획에 포함하지 않습니다. 승인과 항목별 적용 결과는 에이전트 배포에서 확인합니다.

기본 제공 웹 도구

도구	사용 시점	주요 범위
web_search	관련 페이지의 제목·URL·검색 요약을 찾을 때	결과 수 1~30개, 기본 10개. 본문은 반환하지 않으며 결과가 없으면 오류로 처리합니다.
web_fetch	URL 하나의 정적 HTML 본문을 읽을 때	PDF·이미지와 JavaScript 렌더링 페이지는 지원하지 않습니다. 본문 기본 상한은 20,000자이며 잘리면 truncated=true입니다.
use_browser	클릭·입력·스크롤이 필요하거나 정적 조회가 실패할 때	한 호출 안에서만 브라우저 상태를 유지합니다. 단계 기본 12회, 최대 30회입니다.

일반적으로 web_search로 후보를 찾고 결과 URL을 web_fetch로 읽습니다. extracted=false이거나 JavaScript로 렌더링되는 페이지라면 use_browser로 전환합니다. 브라우저 결과는 결론 answer, 추출 원문 extracts, 목표 달성 여부 completed를 구분합니다.

세 도구는 허용 도메인을 제한할 수 있으며 내부·루프백·클라우드 메타데이터 주소에는 접근하지 않습니다. use_browser를 연결한 에이전트는 브라우저 실행 환경을 포함하도록 배포해야 합니다. 인증 세션을 별도로 캡처하는 사용자 화면은 현재 제공하지 않습니다.

액터

액터는 에이전트가 호출하는 Python 함수형 실행 단위입니다. 액터별 확인 정책에서 실행 전에 사람의 승인을 받을지 정합니다.

편집 필드

• 이름 / 별칭 / 설명: 기본 정보입니다. AI 자동 생성 버튼을 누르면 설명을 제안합니다.
• 소스 코드: Python으로 def execute(**kwargs) -> Any 함수를 작성합니다.
• 입력 파라미터: 액터를 부를 때 받을 입력을 JSON Schema로 정의합니다.
• 커넥터: 스크립트가 사용할 연결(커넥터)을 고릅니다.
• 확인 정책: 확인 정책에서 실행 전 확인 방식을 선택합니다.

확인 정책

액터 편집 화면의 확인 정책 섹션에서, 이 액터를 실행하기 전에 사람의 승인을 거칠지 정합니다. 세 가지 중 하나를 고릅니다.

정책	기술 식별자	동작
자동	auto	확인 없이 실행
확인	confirm	실행 전에 사람의 승인을 요청하고 채팅에 승인 카드를 표시
거부	deny	실행 차단

확인으로 설정한 액터를 에이전트가 호출하면 대화 화면에 승인 요청 카드가 나타납니다. 사용자는 실행을 승인하거나 거부합니다. 승인 흐름은 에이전트 배포하기 — 사람 승인 카드에서 확인합니다. 액터 목록의 확인 정책별 필터 버튼으로 범위를 좁힙니다.

사용 위치

• 액터 선택기: 에이전트 빌더의 액터 호출 노드나 AI 에이전트 설정에서 액터를 검색·선택할 때 씁니다.
• 액터 호출 노드 설정 패널: 워크플로우 에이전트에서 액터 호출 노드를 선택하면 나타나는 패널로, 매핑과 실행 옵션(확인 정책 포함)을 편집합니다.

목록 화면 공통 기능

• 이름 검색과 유형 필터 버튼(도구: Python / 에이전트, 액터: 확인 정책별)
• 각 필터에는 해당 항목의 개수 배지가 붙습니다.
• 소유자 컬럼: 다른 자산 목록과 마찬가지로 각 도구·액터의 소유자를 표시합니다.
• 행의 작업 메뉴에서 편집 / 복제 / 삭제를 합니다.
  • 복제: 새 이름과 대상 컬렉션을 정해 편집 가능한 사본을 만듭니다. 기본 제공 도구와 액터도 복제합니다.
• 에이전트에서 참조 중인 도구·액터는 삭제할 수 없습니다. 삭제 창에는 해당 도구·액터를 참조하는 에이전트가 표시됩니다.
• 목록 헤더의 가져오기와 행의 내보내기로 정의 JSON을 옮깁니다. 파일 제한과 에이전트 번들은 가져오기·내보내기에서 확인합니다.
• 이전 실행 구성으로 되돌리려면 버전 기록을 열고 참조 중인 에이전트의 재배포 영향을 확인합니다.

다음 단계

• 에이전트 만들기
• 가져오기·내보내기
• 에이전트 배포