Python 도구 만들고 테스트하기

도구는 에이전트가 정보를 얻거나 계산할 때 호출하는 재사용 함수입니다. 이번 레슨에서는 입력 문자열을 정리해 반환하는 course_normalize_text Python 도구를 만들고, 저장하기 전에 실제 runner에서 실행해 봅니다.

도구 만들기 화면 열기

1. 왼쪽 사이드바에서 AI → 도구를 선택합니다.
2. 오른쪽 위의 생성을 선택합니다.
3. 도구 만들기 화면의 다음 영역을 확인합니다.

• 기본 정보
• 입력 파라미터
• 소스 코드
• 테스트 실행
• 설정
• 데코레이터 바인딩
• 의존성
• 도구 호출 예시

이번 실습에서는 기본 정보, 입력 파라미터, 소스 코드, 테스트 실행, 도구 호출 예시를 사용합니다.

기본 정보 입력하기

다음 값을 입력합니다.

도구 이름은 영문 소문자로 시작하고 소문자, 숫자, 밑줄만 사용합니다. 설명에는 구현 방식보다 에이전트가 언제 사용해야 하는지를 적는 것이 중요합니다.

입력 파라미터 추가하기

1. 입력 파라미터에서 파라미터 추가를 선택합니다.
2. 다음과 같이 입력합니다.

execute 함수 작성하기

소스 코드의 기본 내용을 다음 코드로 교체합니다.

def execute(text: str) -> dict:
    """Normalize one text value without changing external state."""
    normalized = text.strip().lower()
    return {
        "original": text,
        "normalized": normalized,
        "length": len(normalized),
    }

도구 runner가 호출하는 진입점은 execute입니다. 함수 이름을 도구 이름인 course_normalize_text로 작성하면 실행할 함수를 찾지 못하므로 그대로 execute를 사용하세요.

저장 전에 테스트 실행하기

1. 테스트 실행의 입력값에 다음 JSON을 입력합니다.

{
  "text": "  Hello D.Hub  "
}

2. 실행을 선택합니다.
3. 실행 상태가 성공인지 확인합니다.
4. 결과에 다음 값이 포함되는지 확인합니다.

{
  "original": "  Hello D.Hub  ",
  "normalized": "hello d.hub",
  "length": 11
}

테스트 실행은 현재 작성 중인 코드를 실제 격리 runner에서 실행합니다. 문법 오류, 잘못된 함수 이름, 파라미터 불일치를 저장 전에 발견할 수 있습니다.

도구 호출 예시 추가하기

1. 도구 호출 예시에서 예시 추가를 선택합니다.
2. 설명에 앞뒤 공백과 대문자가 있는 문자열 정리를 입력합니다.
3. 인자에 다음 JSON 객체를 입력합니다.

{
  "text": "  Hello D.Hub  "
}

도구 호출 예시는 LLM이 어떤 상황에서 어떤 인자를 만들어야 하는지 판단하는 데 도움을 줍니다.

저장하고 에이전트에 연결하기

1. 화면 아래의 저장을 선택합니다.
2. AI → 에이전트에서 에이전트 빌더 실습을 엽니다.
3. 기능 구성에서 도구를 선택합니다.
4. 선택된 항목만 보인다면 전체 보기를 선택합니다.
5. 텍스트 정리 도구를 선택합니다.
6. 상단의 저장을 선택합니다.

도구 선택 수가 1로 표시되면 연결된 것입니다. 도구를 만들기만 하고 에이전트에 연결하지 않으면 채팅에서 호출할 수 없습니다.

자가 점검

• course_normalize_text 도구를 같은 컬렉션에 만들었습니다.
• 필수 text 파라미터를 string으로 정의했습니다.
• 함수 이름이 execute입니다.
• 테스트 실행 결과의 normalized가 hello d.hub입니다.
• 도구 호출 예시를 추가했습니다.
• 에이전트의 기능 구성에서 도구 선택 수가 1입니다.

다음 레슨

실행 전 사람의 승인을 요구하는 액터를 만들고 확인 정책이 실제 승인 흐름을 어떻게 제어하는지 살펴봅니다.