툴 및 통합

툴은 AI 모델이 할 수 있는 일을 확장합니다. 커스텀 로직을 위한 Python 기반 툴을 만들거나 MCP (Model Context Protocol) 및 OpenAPI를 통해 외부 툴 서버를 연결하세요.

툴이란?

툴은 모델이 대화 중에 호출할 수 있는 함수입니다:

• 커스텀 툴 — 직접 작성하는 Python 코드
• 외부 툴 — OpenAPI 서버 또는 MCP 서비스
• 사용 사례 — 데이터 가져오기, 계산 수행, 시스템과 상호작용

모델에 툴이 연결되면 더 정확하게 질문에 답하는 데 사용할 수 있습니다.

툴 보기

1. 워크스페이스 → 툴로 이동
2. 사용 가능한 모든 툴이 표시됩니다

각 툴은 다음을 표시합니다:

• 이름 — 툴 식별자
• 설명 — 툴의 역할
• 유형 — 커스텀, OpenAPI, 또는 MCP

커스텀 툴 만들기

1단계: "툴 만들기" 클릭

"+ 툴 만들기" 버튼을 클릭하세요.

2단계: 툴 정보 입력

입력:

• 툴 이름 — 고유 식별자 (영숫자, 소문자)
• 설명 — 툴의 역할 설명; LLM이 언제 호출할지 결정하는 데 사용됨

모델이 언제 사용할지 알 수 있도록 명확한 설명 작성:

• ✅ "주어진 티커 기호의 현재 주가를 가져옵니다"
• ❌ "금융 툴"

3단계: Python 코드 작성

툴은 Tools 클래스를 정의해야 합니다:

import anthropic

class Tools:
    def __init__(self):
        pass
    
    def get_stock_price(self, ticker: str) -> str:
        """Fetch current stock price for a given ticker"""
        # Your implementation
        return f"AAPL: $150.25"

요구 사항:

• Tools 클래스 정의
• 모델이 호출할 수 있는 메서드 구현
• 메서드에 독스트링 추가 (모델이 사용)
• 문자열 또는 JSON 반환

4단계: 툴 저장

변경 사항 저장을 클릭하세요. 툴이 즉시 사용 가능합니다:

• 모델에 연결
• 채팅 툴 메뉴에서 사용

툴 편집

1. 툴 카드에서 편집 클릭
2. Python 코드 수정
3. 변경 사항 저장 클릭

변경 사항이 툴을 사용하는 모든 채팅에 즉시 적용됩니다.

모델에 툴 추가

모델을 만들거나 편집할 때:

1. 툴 섹션에서 "+ 툴 추가" 클릭
2. 대화상자에서 툴 선택
3. 추가 클릭

선택된 툴이 모델 카드의 툴 목록에 표시됩니다.

MCP - 외부 툴 서버

MCP (Model Context Protocol)를 사용하면 외부 툴 서버를 연결할 수 있습니다.

MCP란?

MCP는 표준화된 툴 통합을 위한 프로토콜입니다:

• 표준화 — MCP 호환 서버와 호환됨
• 외부 — 툴이 자체 서버에서 실행됨
• 강력함 — 툴이 복잡한 시스템과 상호작용 가능

참고: MCP 지원은 실험적입니다. 프로덕션에는 OpenAPI가 더 안정적입니다.

MCP 툴 서버 추가

1. 워크스페이스 → MCP로 이동
2. "+ 추가" 클릭

입력:

OpenAPI 서버 연결

OpenAPI는 프로덕션에 권장됩니다. 제공:

• URL — API의 기본 URL
• 경로 — OpenAPI 스펙 경로 (예: /openapi.json)
• 인증 유형 — 없음, Bearer, 또는 커스텀
• API 키 — Bearer 인증 사용 시

추가되면 OpenAPI 엔드포인트가 툴 목록에 개별 툴로 표시됩니다.

인증 방법

모델에 툴 연결

모델을 만들거나 편집할 때 툴을 연결합니다:

1. 모델 만들기/편집 양식 열기
2. "+ 툴 추가" 클릭
3. 대화상자에 사용 가능한 모든 툴 표시 (커스텀 + MCP)
4. 연결할 툴 선택
5. 추가 클릭

사용자가 모델과 채팅할 때 모델이 연결된 툴을 호출하도록 선택할 수 있습니다.

채팅에서 툴 사용

모델의 툴 사용 방식

대화 중:

1. 모델에 메시지를 보냄
2. 모델이 툴이 필요한지 분석
3. 필요한 경우 모델이 파라미터와 함께 툴 호출
4. 툴이 결과 반환
5. 모델이 결과를 응답에 통합

예시

사용자: "뉴욕의 날씨가 어때요?"

모델: (날씨 툴이 필요하다고 판단) get_weather("New York") 호출

툴 반환: {"temp": 72, "condition": "Sunny"}

모델: "뉴욕은 현재 72°F이고 맑습니다."

문제 해결

툴이 만들어졌지만 모델 대화상자에 표시되지 않음

원인: Python 구문 오류 또는 Tools 클래스 누락.

해결 방법: 툴의 Python 코드를 확인하세요. Tools 클래스가 적절한 메서드로 정의되어 있는지 확인하세요.

모델이 툴을 호출하지 않음

원인: 툴 설명이 불명확하거나 모델이 언제 필요한지 인식하지 못함.

해결 방법: 툴을 사용해야 하는 시점을 설명하는 더 명확한 설명을 작성하세요.

MCP 서버 연결 실패

원인: 서버 다운, URL 오류, 또는 인증 자격 증명이 잘못됨.

해결 방법:

1. 서버 URL 직접 테스트
2. 인증 자격 증명 확인
3. 서버 로그에서 오류 확인

툴이 오류 반환

원인: 입력 파라미터가 유효하지 않거나 툴의 외부 서비스를 사용할 수 없음.

해결 방법: 입력을 검증하고 오류를 처리하도록 툴을 업데이트하세요.

다음 단계:

1. 커스텀 모델 만들기 — 모델에 툴 연결
2. Model Context Protocol 이해 — MCP에 대해 더 알아보기
3. 툴이 장착된 모델로 채팅 — 대화에서 툴 사용