AI Agent 도구 통합

AI Agent 도구 통합 가이드

AI Agent의 능력은 연결된 도구에 의해 결정됩니다. 효과적인 도구 설계와 통합 방법을 알아봅니다.

도구 설계 원칙

1. 명확한 설명

@tool
def calculate_loan_payment(
    principal: float,
    annual_rate: float,
    years: int
) -> str:
    """
    대출 월 상환금을 계산합니다.

    Args:
        principal: 대출 원금 (원)
        annual_rate: 연 이자율 (예: 5.5 = 5.5%)
        years: 상환 기간 (년)

    Returns:
        월 상환금과 총 이자를 포함한 계산 결과

    Example:
        calculate_loan_payment(100000000, 5.5, 30)
        -> "월 상환금: 567,790원, 총 이자: 104,404,400원"
    """
    monthly_rate = annual_rate / 100 / 12
    num_payments = years * 12

    monthly_payment = principal * (
        monthly_rate * (1 + monthly_rate)**num_payments
    ) / ((1 + monthly_rate)**num_payments - 1)

    total_paid = monthly_payment * num_payments
    total_interest = total_paid - principal

    return f"월 상환금: {monthly_payment:,.0f}원, 총 이자: {total_interest:,.0f}원"

2. 적절한 파라미터

• 필수 파라미터는 최소화
• 합리적인 기본값 제공
• 타입과 범위 명시

주요 도구 카테고리

1. 웹 검색 도구

from langchain_community.tools import DuckDuckGoSearchRun

search = DuckDuckGoSearchRun()

@tool
def web_search(query: str) -> str:
    """실시간 웹 검색을 수행합니다."""
    return search.run(query)

2. 데이터베이스 도구

@tool
def query_database(sql: str) -> str:
    """
    데이터베이스에 SQL 쿼리를 실행합니다.
    SELECT 쿼리만 허용됩니다.
    """
    if not sql.strip().upper().startswith("SELECT"):
        return "오류: SELECT 쿼리만 허용됩니다."

    try:
        result = db.execute(sql)
        return format_results(result)
    except Exception as e:
        return f"쿼리 오류: {e}"

3. 파일 시스템 도구

@tool
def read_file(path: str) -> str:
    """파일 내용을 읽습니다. 허용된 디렉토리만 접근 가능합니다."""
    allowed_dirs = ["/data/", "/uploads/"]
    if not any(path.startswith(d) for d in allowed_dirs):
        return "접근 거부: 허용되지 않은 경로입니다."

    with open(path, 'r') as f:
        return f.read()

@tool
def write_file(path: str, content: str) -> str:
    """파일에 내용을 씁니다."""
    with open(path, 'w') as f:
        f.write(content)
    return f"파일 저장 완료: {path}"

4. API 통합 도구

import requests

@tool
def get_stock_price(symbol: str) -> str:
    """주식 현재가를 조회합니다."""
    response = requests.get(
        f"https://api.stock.com/v1/price/{symbol}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    data = response.json()
    return f"{symbol}: {data['price']:,.0f}원 ({data['change']:+.2f}%)"

@tool
def send_slack_message(channel: str, message: str) -> str:
    """Slack 채널에 메시지를 전송합니다."""
    slack_client.chat_postMessage(
        channel=channel,
        text=message
    )
    return f"메시지 전송 완료: #{channel}"

도구 조합 전략

작업별 도구 세트

research_tools = [web_search, read_file, summarize]
coding_tools = [execute_code, read_file, write_file, run_tests]
communication_tools = [send_email, send_slack, schedule_meeting]

def get_tools_for_task(task_type: str):
    tool_sets = {
        "research": research_tools,
        "coding": coding_tools,
        "communication": communication_tools,
    }
    return tool_sets.get(task_type, [])

에러 처리

@tool
def safe_api_call(endpoint: str, data: dict) -> str:
    """안전하게 API를 호출합니다."""
    try:
        response = requests.post(
            endpoint,
            json=data,
            timeout=30
        )
        response.raise_for_status()
        return response.json()
    except requests.Timeout:
        return "오류: 요청 시간 초과"
    except requests.HTTPError as e:
        return f"HTTP 오류: {e.response.status_code}"
    except Exception as e:
        return f"알 수 없는 오류: {str(e)}"