콘텐츠로 이동

함수 호출 (Function Calling in AI Agents)

개요

함수 호출(도구 호출이라고도 함)은 현대의 LLM 기반 에이전트를 구동하는 핵심 기능 중 하나입니다. Claude 4.6, GPT-5.4, Gemini 2.5 Pro 같은 최신 모델들이 강화된 함수 호출 능력을 제공합니다. 함수 호출이 내부에서 어떻게 작동하는지 이해하는 것은 효과적인 AI 에이전트를 구축하고 문제가 발생할 때 이를 디버깅하는 데 필수적입니다.

함수 호출이란?

핵심 개념

함수 호출은 LLM이 외부 도구, API, 지식 기반과 상호 작용할 수 있게 하는 메커니즘입니다.

LLM이 훈련 데이터를 넘어서는 정보나 행동이 필요한 쿼리를 받으면, 외부 함수를 호출하여 그 정보를 검색하거나 그 행동을 수행할 수 있습니다.

간단한 예

사용자: "서울의 현재 날씨는 어떤가요?"

LLM의 인식: "실시간 날씨 데이터가 필요합니다.
             내 훈련 데이터에는 없으므로
             날씨 API를 호출해야 합니다."

LLM의 응답:
{
  "tool_name": "get_weather",
  "parameters": {
    "city": "서울",
    "country": "한국"
  }
}

시스템의 실행: 날씨 API 호출
  → OpenWeatherMap API 결과

LLM의 재개: "서울의 현재 날씨는 맑고, 기온은..."

이 능력은 기본 LLM을 텍스트 생성기에서 실제 세계와 상호 작용할 수 있는 강력한 에이전트로 변환합니다.

함수 호출이 AI 에이전트를 구동하는 방식

함수 호출 흐름도

┌─────────────────────────────────┐
│   1. 사용자 쿼리 수신           │
│   "한국 날씨 조회 + 일정 추가"   │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│   2. 컨텍스트 조립              │
│   - 시스템 메시지                │
│   - 도구 정의                   │
│   - 사용자 메시지               │
│   → LLM에 전송                 │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│   3. LLM이 도구 결정             │
│   "날씨 조회 필요"               │
│   "일정 추가 필요"               │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│   4. 도구 실행                   │
│   ├─ get_weather("서울")        │
│   └─ add_event(...)             │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│   5. 결과 수집 (관찰)            │
│   - 날씨: 맑음, 18°C            │
│   - 일정: 저장됨                 │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│   6. 응답 생성                   │
│   "서울은 현재 맑고...           │
│    일정이 추가되었습니다..."      │
└─────────────────────────────────┘

상세 단계 설명

1. 사용자 쿼리 - 사용자가 에이전트에 요청을 보냅니다 - 예: "내일 서울에서 회의가 있는데 날씨 확인하고 일정 추가해줄래?"

2. 컨텍스트 조립 - 시스템은 다음을 결합하여 LLM에 전달: 

{
  "system_prompt": "너는 날씨와 일정을 관리하는 에이전트다",
  "tools": [
    {
      "name": "get_weather",
      "description": "특정 도시의 날씨 조회",
      "parameters": {...}
    },
    {
      "name": "add_event",
      "description": "캘린더에 일정 추가",
      "parameters": {...}
    }
  ],
  "messages": [
    {"role": "user", "content": "내일 서울 날씨는? 회의 추가해줄래?"}
  ]
}

3. 도구 결정 - LLM이 컨텍스트를 분석합니다 - 필요한 도구들을 식별합니다 - 각 도구에 필요한 매개변수를 결정합니다

4. 도구 실행 - 개발자의 코드가 도구 호출을 받습니다 - 실제 함수를 실행합니다 - 결과를 수집합니다

5. 관찰 (Observation) - 도구의 실행 결과를 에이전트에 제공합니다 - 에이전트가 이 정보를 기반으로 다음 단계를 결정합니다

6. 응답 생성 - 도구 결과와 함께 LLM이 최종 응답을 생성합니다

핵심 통찰

LLM은 항상 전체 컨텍스트를 유지합니다: 

대화 흐름:
1. 사용자 메시지
2. 도구 호출 (LLM의 선택)
3. 도구 결과 (Observation)
4. LLM이 결과를 포함한 전체 대화 기록 유지
5. 최종 응답 생성

이 컨텍스트 인식이 에이전트가 다음 수행할 작업과 도구 결과를 최종 응답에 통합하는 방법에 대해 지능적인 결정을 내릴 수 있게 합니다.

도구 정의의 역할

도구 정의의 중요성

도구 정의는 함수 호출의 가장 중요한 구성 요소입니다. 이것이 LLM이 어떤 도구를 사용할 수 있는지, 그리고 언제 사용할지 알 수 있는 유일한 방법입니다.

도구 정의의 구조

도구 정의는 일반적으로 다음을 포함합니다:

필수 요소

{
  "name": "도구의 고유 식별자",
  "description": "도구가 무엇을 하는지, 언제 사용하는지 설명",
  "parameters": {
    "type": "object",
    "properties": {
      "매개변수1": {
        "type": "string",
        "description": "매개변수 설명"
      }
    },
    "required": ["필수_매개변수"]
  }
}

실제 예제: 한국 날씨 및 일정 도구

도구 1: 날씨 조회

{
  "name": "get_korea_weather",
  "description": "한국의 특정 도시 현재 날씨 조회. 기온, 습도, 강수 확률 등을 반환합니다.",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "도시 이름 (예: 서울, 부산, 대구, 인천)"
      },
      "include_forecast": {
        "type": "boolean",
        "description": "5일 예보도 포함할지 여부",
        "default": false
      }
    },
    "required": ["city"]
  }
}

도구 2: 일정 추가

{
  "name": "add_calendar_event",
  "description": "사용자의 캘린더에 새로운 일정을 추가합니다.",
  "parameters": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "일정 제목 (예: 회의, 약속)"
      },
      "date": {
        "type": "string",
        "description": "일정 날짜 (YYYY-MM-DD 형식)"
      },
      "time": {
        "type": "string",
        "description": "일정 시간 (HH:MM 형식, 24시간 체계)"
      },
      "duration_minutes": {
        "type": "integer",
        "description": "소요 시간 (분 단위)"
      },
      "location": {
        "type": "string",
        "description": "장소 (선택사항)"
      },
      "notes": {
        "type": "string",
        "description": "추가 메모 (선택사항)"
      }
    },
    "required": ["title", "date", "time"]
  }
}

좋은 도구 정의의 특징

✓ 명확한 이름: 도구의 목적이 분명
✓ 상세한 설명: 언제 사용하는지 명확
✓ 구체적인 예제: 사용 사례 포함
✓ 정확한 매개변수: 필수/선택 구분, 타입 명시
✓ 제약 조건: 입력값의 범위나 형식 명시
✓ 반환값 문서화: 결과가 어떤 형식인지 설명

에이전트 루프: 행동과 관찰

에이전트 루프의 개념

에이전트 루프를 이해하는 것은 AI 에이전트를 디버깅하고 최적화하기 위해 근본적입니다.

루프의 사이클

1. 행동 (Action)
   - 에이전트가 다음 수행할 행동 결정
   - 어떤 도구를 호출할지 선택
   ↓
2. 환경 응답 (Environment Response)
   - 외부 도구 또는 API가 결과 반환
   - 성공 또는 실패 응답
   ↓
3. 관찰 (Observation)
   - 에이전트가 결과 수신 및 처리
   - 결과 분석
   ↓
4. 결정 (Decision)
   - 에이전트가 다른 행동을 취할지 판단
   - 완료? → 최종 응답 생성
   - 계속? → 1번으로 돌아가기

실제 예: 한국 출장 준비 에이전트

사용자: "내일 부산 출장 가는데 준비해줄래?"

┌─────────────────────────────────┐
│ 1단계 - 행동                     │
│ 에이전트: "부산 날씨 확인 필요"    │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│ 2단계 - 환경 응답                │
│ get_korea_weather("부산")        │
│ 결과: 맑음, 18°C, 강수확률 10%   │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│ 3단계 - 관찰                     │
│ "부산 날씨가 좋네요.              │
│  가벼운 옷차림이 적당해 보입니다"  │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│ 4단계 - 결정                     │
│ "하지만 출장 일정도 확인하고,     │
│  교통편도 예약해야 해요"          │
│ 계속 → 다음 행동으로             │
└────────────┬────────────────────┘
             │
┌────────────▼────────────────────┐
│ 1단계 - 행동 (반복)              │
│ 에이전트: "출장 일정 조회 필요"   │
│ (다시 루프 시작)                 │
└─────────────────────────────────┘

루프 종료 조건

에이전트가 다음 중 하나를 판단할 때 루프 종료:

1. 작업 완료
   "모든 준비가 완료되었습니다"

2. 추가 정보 불가능
   "현재 시점에서 더 할 수 있는 것이 없습니다"

3. 사용자 결정 필요
   "여기서는 당신의 선택이 필요합니다"

4. 오류/실패
   "예약 실패. 다시 시도하시겠습니까?"

함수 호출 디버깅

일반적인 문제

AI 에이전트를 구축할 때, 에이전트가 예상대로 작동하지 않는 상황을 피할 수 없습니다:

  • 잘못된 도구 호출: 에이전트가 부적절한 도구 선택
  • 잘못된 인수: 도구에 올바르지 않은 매개변수 전달
  • 도구 호출 누락: 필요한 도구를 호출하지 않음
  • 무한 루프: 같은 도구를 반복 호출

디버깅 방법

1. 로깅 활성화

class DebugAgent:
    def call_tool(self, tool_name, parameters):
        """도구 호출 로깅"""
        print(f"[도구 호출] {tool_name}")
        print(f"[매개변수] {parameters}")

        # 실제 호출
        result = self.tools[tool_name](**parameters)

        print(f"[결과] {result}")
        return result

2. 단계별 추적

각 단계를 로깅:
✓ 입력 수신: 사용자 메시지 내용
✓ 도구 선택: 어떤 도구를 왜 선택했는가
✓ 매개변수: 도구에 전달된 정확한 값
✓ 도구 결과: 도구 실행의 실제 결과
✓ 토큰 사용: 각 단계의 토큰 소비량

3. 중간 단계 가시화

n8n과 같은 워크플로우 자동화 도구에서는 "중간 단계 반환"을 활성화하여 내부에서 정확히 무슨 일이 일어나고 있는지 볼 수 있습니다:

호출된 도구들의 순서:
1. get_korea_weather("서울") ✓
2. add_calendar_event("회의", "2025-02-21", "14:00") ✓
3. send_email("상사@company.com", "출장 준비 완료") ✓

각 도구로 전송된 인수:
- get_korea_weather: {"city": "서울"}
- add_calendar_event: {"title": "회의", "date": "2025-02-21", ...}
- send_email: {"to": "상사@company.com", ...}

수신된 관찰:
- 도구 1 결과: {"temp": 18, "condition": "맑음"}
- 도구 2 결과: {"status": "success", "event_id": "12345"}
- 도구 3 결과: {"status": "sent"}

토큰 사용:
- get_korea_weather: 150 토큰
- add_calendar_event: 200 토큰
- send_email: 180 토큰
- 총합: 530 토큰

디버깅 체크리스트

□ 도구 정의가 명확한가?
  └─ 설명이 충분히 상세한가?
  └─ 매개변수 예제가 있는가?

□ LLM이 올바른 도구를 선택하는가?
  └─ 로그에서 도구 호출 확인
  └─ 선택의 논리가 맞는가?

□ 매개변수 전달이 정확한가?
  └─ 필수 매개변수가 모두 있는가?
  └─ 데이터 타입이 맞는가?

□ 도구 실행이 성공하는가?
  └─ 외부 API가 정상 작동하는가?
  └─ 오류 메시지가 있는가?

□ 에이전트가 결과를 올바르게 처리하는가?
  └─ 결과를 다음 단계에 사용하는가?
  └─ 오류를 감지하고 대응하는가?

💡 실전 팁

함수 호출 최적화

  1. 명확한 도구 이름: get_weather 보다 get_korea_weather가 더 구체적

  2. 예제 포함: 도구 설명에 사용 사례 명시 

    "datetime"의 예: "2025-02-21 14:30"

  3. 제약 조건 명시: 

    "city: 서울, 부산, 대구 등 대도시만 가능"

  4. 오류 처리: 도구 실패 시 대안 마련 

    날씨 API 실패 → 캐시된 최근 날씨 사용

  5. 토큰 최적화: 불필요한 도구 호출 줄이기 

    한 번의 호출로 여러 정보 반환하도록 도구 설계

다양한 모델의 함수 호출

Claude 4.6 (Anthropic)

  • 지원: Tool Use API
  • 특징: 긴 컨텍스트 (1M 토큰)에서 안정적
  • 장점: 복잡한 다단계 도구 호출에 강함

GPT-5.4 (OpenAI)

  • 지원: Function Calling API
  • 특징: 최신 성능, 빠른 처리
  • 장점: 신뢰할 수 있는 매개변수 생성

Gemini 2.5 Pro (Google)

  • 지원: Function Calling
  • 특징: 멀티모달 (텍스트 + 이미지)
  • 장점: Google 서비스와의 통합

📝 핵심 정리

함수 호출의 역할

  • LLM을 실제 세계와 연결: 정보 수집 및 행동 실행 가능
  • 에이전트의 핵심 기능: 도구 없이는 에이전트 불가능
  • 자동화 가능: 복잡한 다단계 작업 자동 수행

함수 호출 흐름

사용자 입력 → 컨텍스트 조립 → LLM 의사결정 → 도구 실행
  → 결과 수집 → 응답 생성

도구 정의의 중요성

  • 명확성: LLM이 도구를 이해하는 기초
  • 정확성: 올바른 매개변수 전달 가능
  • 신뢰성: 예상치 못한 오용 방지

에이전트 루프

  • 반복적 실행: 도구 호출 → 관찰 → 결정
  • 적응성: 결과에 따라 다음 단계 결정
  • 완성도: 작업이 완료될 때까지 계속

디버깅

  • 로깅: 모든 단계 기록
  • 단계별 추적: 각 도구 호출 모니터링
  • 오류 분석: 잘못된 선택의 원인 파악

시험 포인트

  • 함수 호출의 기본 메커니즘과 단계
  • 효과적인 도구 정의의 작성
  • 에이전트 루프의 흐름과 제어
  • 일반적인 함수 호출 오류와 해결 방법
  • 도구 인수 검증과 오류 처리
  • 여러 도구의 순차 호출과 병렬 호출
  • 관찰 처리와 다음 행동 결정
  • 다양한 모델의 함수 호출 차이
  • 실무에서의 디버깅 기법