에이전트 도구 호출, 함수 콜링부터 생산급 오케스트레이션까지

핵심 결론: Agent가 도구를 호출하는 것은 「모델이 스스로 코드로 함수를 호출하는 것」이 아니라, 하나의 요청—결정—실행—반환—재생성으로 이어지는 다중 턴 폐쇄 루프다. 모델은 「어떤 도구를 쓸지, 어떤 파라미터를 채울지 결정」하는 역할만 맡고, 실제 실행은 애플리케이션 측에서 완료된다. 이 체인을 이해하는 것이 Agent 엔지니어링의 첫 수업이다.

목차

- 한 문장으로 본질 파악하기: 모델은 단지 「지휘관」

- 도구 호출 체인: 한 번의 완전한 4/5단계 폐쇄 루프

- 도구 정의(schema)를 잘 써야 모델이 올바르게 호출한다

- 파라미터 검증: 모델은 당신을 「속일」 수 있으므로 반드시 검증해야 한다

- 실행 가능한 완전한 예제: Python + OpenAI Function Calling

- 흔한 함정과 대조표: 증상 → 원인 → 해결법

- 도구 호출을 쓰지 말아야 할 때

- 요약: 모델은 「의사결정자」로, 애플리케이션은 「실행자」로

1. 한 문장으로 본질 파악하기: 모델은 단지 「지휘관」

많은 사람이 Agent의 도구 호출을 「대형 모델이 손발이 생겨 스스로 실행하는 것」이라고 생각한다. 아니다. 모델의 본질은 순수한 추론 엔진으로, 데이터베이스에 실제로 접근하거나 API를 호출할 권한도, 능력도 없다. 모델은 단 한 가지 일만 한다. 바로 당신이 제공한 도구 목록을 바탕으로 구조화된 「호출 지시」를 출력하는 것 — 어떤 도구를 쓸지, 파라미터에 무엇을 채울지.

이 지시를 실제로 실행하는 것은 당신(애플리케이션)이다. 이는 마치 AI가 프로젝트 매니저(generates a plan)이고, 당신이 실행 팀(executes the plan)인 것과 같다. 이 역할 분담을 이해해야 이후의 모든 단계가 엉키지 않는다.

비유하자면 🎭: 모델은 하나의 펜과 같아서 특정 도구를 호출하는 지시를 「써낼」 수만 있고, 당신은 「실행 키」와 같아서 오직 당신만이 이 지시를 실제 시스템 동작으로 번역할 수 있다. 모델은 "생각"을 담당하고, 애플리케이션은 "실행"을 담당한다.

2. 도구 호출 체인: 한 번의 완전한 4/5단계 폐쇄 루프

문서마다 도구 호출을 4단계 또는 5단계로 나누지만, 본질은 같은 일이다. 가장 흔한 4단계 폐쇄 루프를 예로 들어, 「날씨 조회」라는 예시로 이어서 설명해 보겠다.

① 요청(Request): 애플리케이션이 사용자의 질문, 컨텍스트와 함께 「사용 가능한 도구 목록」을 모델에 보낸다. 도구 목록은 미리 정의한 JSON schema로, 예를 들어 「get_weather(도시)」「search_docs(키워드)」 등이다.

② 결정(Decide): 모델이 분석한 뒤 결정을 내린다 — 직접 답할지, 도구 호출이 필요한지. 도구가 필요하다고 판단하면 tool name(도구 이름)과 arguments(파라미터)를 포함한 구조화 객체를 출력한다. 예를 들어:

{ "name" : "get_weather" , "arguments" : { "city" : "베이징" } }

③ 실행(Execute): 애플리케이션이 실행한다. 애플리케이션 계층이 도구 이름으로 해당 실행 함수를 찾아 파라미터를 채우고, 실제로 한 번 실행해 결과(예: 「25℃ 맑음」)를 얻는다.

④ 반환(Return): 애플리케이션이 도구 실행 결과를 tool 역할의 메시지로 모델에 반환한다.

⑤ 재생성(Finalize): 모델이 이 결과를 바탕으로 최종 자연어 답변을 생성하거나, 다음 라운드의 도구 호출을 계속发起한다(작업이 연속된 여러 단계를 필요로 할 때).

이는 하나의 순환이다: 모델이 「생각」→ 애플리케이션이 「실행」→ 결과를 「되먹임」→ 모델이 「다시 생각」. Agent가 복잡한 작업을 완수할 수 있는지는 이 순환이 안정적으로 돌아가느냐에 달려 있다. 화산엔진(Volcano Engine)의 docs는 이를 통일적으로 「다섯 단계」라고 부르고, 마이크로소프트는 「함수 정의」를 사전 단계로 간주하는데, 본질은 일치한다.

3. 도구 정의(schema)를 잘 써야 모델이 올바르게 호출한다

이것은 전체 도구 호출에서 가장 간과되기 쉽지만 효과에 가장 큰 영향을 미치는 부분이다. 모델이 「언제 이 도구를 써야 하는지, 파라미터에 무엇을 채울지」 판단하는 유일한 근거가 바로 당신이 작성한 도구 설명(description)이기 때문이다. 설명이 모호하면 모델은 제멋대로 추측하여, 호출하지 않거나 잘못된 파라미터를 전달한다.

규격에 맞는 tool schema는 최소한 네 가지 요소를 포함한다(Anthropic의 규격을 예로):

요소 설명 name 도구 이름, ^[a-zA-Z0-9_-]{1,64}$와 일치해야 함 description 한 문장으로 기능 + 언제 쓸지 + 언제 쓰지 말지 명확히 설명 input_schema JSON Schema, 각 파라미터의 타입, 필수/선택 정의 (선택)예시 실제 파라미터 한 세트 + 당신이 기대하는 반환값, 모델 정렬에 도움

description 작성의 황금률: 정확하게, 모호하지 않게. 동사로 시작하고, 「사용자가 X를 요청할 때 사용하고, 사용자가 단지 대화를 원할 때는 쓰지 않는다」를 명확히 쓴다. 예를 들어:

- ❌ 날씨 조회

- ✅ 사용자가 특정 지역의 날씨나 기온을 물을 때 호출하고, 단순 대화일 때는 호출하지 않음. 파라미터 city는 도시 이름, 예: "베이징". 온도, 날씨 상태를 반환.

실측 결과, description은 도구 호출 정확률에 영향을 미치는 가장 큰 단일 요인이다 — 그것은 모델이 「언제 호출할지, 파라미터를 어떻게 채울지」 판단하는 거의 유일한 컨텍스트다. 따라서 description을 다듬는 데 쏟는 노력의 보답이 prompt를 조정하는 것보다 훨씬 크다.

또한 도구 이름은 의미가 드러나야 한다: search_docs가 docs보다 좋은데, 모델이 그것으로 의도를 읽을 수 있기 때문이다. 파라미터는 schema에 타입, 필수 여부, 단위, 열거 값을 명확히 써야 한다. 모호한 schema(Vague schema)는 모델이 파라미터를 조작(invents invented arguments)하거나 도구를 잘못 선택하도록 유도한다.

4. 파라미터 검증: 모델은 당신을 「속일」 수 있으므로 반드시 검증해야 한다

이것은 신입이 가장 빠지기 쉬운 함정이다: 모델이 출력한 arguments를 그대로 받아 바로 실행하는 것. 절대 그렇게 해서는 안 된다. 모델이 출력한 파라미터는 텍스트 생성에 기반한 추측이지, 실제로 신뢰할 수 있는 데이터가 아니다. 모델은 다음과 같은 일을 할 수 있다:

- 문자열 리스트 ["P001","P002"]를 "P001,P002"로 출력(타입 오류)

- 숫자를 문자열 "25"로 출력하고 25가 아님

- 존재하지도 않는 도시 이름을 조작

- 필수 파라미터를 누락

따라서 실제 실행 전에 반드시 한 겹의 파라미터 검증을 해야 한다: JSON Schema로 파라미터 구조, 타입, 필수 항목을 검증하고; 고위험 작업(삭제, 전송, 송금)에는 2차 확인을 하고, 사용자 신원, 테넌트 범위가 관련되면 권한도 검증한다. 이 단계가 당신의 Agent를 「신뢰할 수 있는 조수」로 만들지 「사고를 치는 장난감」으로 만들지 결정한다.

한 가지 원칙: 모델 출력은 언제나 「후보 파라미터」이며, 당신의 검증과 정제를 거쳐야 「실행 가능한 파라미터」가 된다. 이것이 내가 앞서 AI07에서 보호 계층을 따로 작성한 이유이기도 하다 — 검증은 도구 호출 체인에서 빼놓을 수 없는 한 고리다.

5. 실행 가능한 전체 예제: Python + OpenAI Function Calling

아래는 복사해서 붙여넣으면 바로 실행되는 전체 코드입니다. OpenAI 호환 인터페이스로 「날씨 조회」 도구 호출의 전체 폐쇄 루프를 시연합니다. 실행 전에 pip install openai 를 설치하고 API key를 설정하세요.

import json from openai import OpenAI client = OpenAI(api_key= "당신의 API-KEY" ) # 1. 도구 정의(schema) —— 설명을 정확하게 쓸수록 모델이 더 정확하게 호출한다 tools = [ { "type" : "function" , "function" : { "name" : "get_weather" , "description" : "사용자가 특정 지역의 날씨나 기온을 물을 때 호출하며, 단순 대화만 할 때는 호출하지 않는다." "매개변수 city는 도시명, 예: '베이징', 온도와 날씨 상태를 반환한다." , "parameters" : { "type" : "object" , "properties" : { "city" : { "type" : "string" , "description" : "도시명, 예: '베이징'" } }, "required" : [ "city" ] } } } ] # 2. 실제 실행을 모사한 도구 함수 (모델은 스스로 실행하지 못하고, 애플리케이션이 실행한다) def get_weather ( city: str ) -> str : """실제 백엔드 조회로, 여기서는 가짜 데이터로 대체한다.""" return f" {city} 오늘 25℃, 맑음" # 3. 사용자가 질문하고, 애플리케이션이 도구 목록을 함께 모델에 보낸다 messages = [{ "role" : "user" , "content" : "베이징 오늘 날씨 어때?" }] response = client.chat.completions.create( model= "gpt-4o-mini" , messages=messages, tools=tools, tool_choice= "auto" , # auto=모델이 직접 호출 여부를 결정 ) # 4. 모델이 도구 호출을 결정하고 구조화된 지시를 출력한다 msg = response.choices[ 0 ].message if msg.tool_calls: call = msg.tool_calls[ 0 ] print ( "모델이 호출할 도구:" , call.function.name) # 5. 애플리케이션 측에서 매개변수를 받아 먼저 검증하고(여기서는 가장 단순한 검증을 시연), 그다음 실제 실행한다 args = json.loads(call.function.arguments) if "city" not in args or not isinstance (args[ "city" ], str ): raise ValueError( "매개변수 검증 실패: city 누락 또는 타입 오류" ) result = get_weather(args[ "city" ]) # 6. 도구 실행 # 7. 실행 결과를 tool 역할로 모델에 되돌려준다 messages.append(msg) # 모델의 선택도 컨텍스트에 들어간다 messages.append({ "role" : "tool" , "tool_call_id" : call. id , "content" : result, }) # 8. 모델이 결과를 바탕으로 최종 자연어 답변을 생성한다 final = client.chat.completions.create( model= "gpt-4o-mini" , messages=messages, tools=tools, ) print ( "최종 답변:" , final.choices[ 0 ].message.content) else : # 모델이 도구가 필요 없다고 판단하면 바로 답변한다 print ( "직접 답변:" , msg.content)

실행 로직 : 모델이 get_weather 지시를 출력 → 애플리케이션이 매개변수 검증 → get_weather("베이징") 실제 실행 → 25℃ 맑음 을 되돌려줌 → 모델이 「베이징 오늘 25℃, 맑음」을 생성. 이 전체 폐쇄 루프에서 모델은 실제로 함수를 호출하지 않고, 애플리케이션이 호출한다 .

6. 흔한 함정과 대조표: 증상 → 원인 → 해결법

도구 호출 오류는 대부분 추적 가능한 단서가 있다. 아래는 증상 → 원인 → 해결법 대조표로, 문제가 생기면 우선 여기에 대조해 점검하자:

증상 원인 해결법 모델이 도저히 도구를 호출하지 않음 description이 「언제 써야 하는지」를 명확히 말하지 않음 설명을 다시 써서 동사로 시작하고 트리거 상황을 명확히 서술 매개변수 타입 오류(리스트가 문자열로 바뀜) 모델이 텍스트를 기반으로 추측하고 검증하지 않음 JSON Schema 검증 + 타입 변환 매개변수 날조(허구의 도시명) schema에 enum/예시가 없어 모델이 지어냄 매개변수에 enum 값, 예시, 필수 제약 추가 도구명 선택 오류 도구명이 너무 광범위해 모델이 의도를 읽지 못함 search_docs처럼 의미 있는 이름 사용 HTTP 400 반환 tools JSON 구조가 규정에 맞지 않음 JSON Schema 구조를 엄격히 검증하고 typo/불필요한 필드 회피 모델이 호출을 반복하며 멈추지 않음 max_turns/종료 조건이 없음 최대 라운드 또는 명확한 정지 조건 설정 고위험 작업이 잘못 실행됨 2차 확인 없이 바로 실행 전송/삭제/이체 전에 사람 확인 추가 여러 번 호출한 결과가 뒤섞임 tool_call_id/컨텍스트를 안 붙임 매번 모델의 선택과 결과를 call_id로 짝지어 되돌려줌

7. 언제 도구 호출을 쓰지 않아야 하는가

모든 상황에 도구 호출이 필요한 것은 아니다. 도구 호출은 지연이 있고 비용이 들며 오류 위험이 있다. 모델이 직접 답할 수 있으면 굳이 도구를 붙이지 마라 .

- 써야 할 때 : 실시간 데이터, 외부 시스템, 업무 내부 정보, 실제 동작 실행이 필요할 때.

- 쓰지 말아야 할 때 : 순수 지식 문답, 의미 이해, 텍스트 생성처럼 모델이 잘하는 작업——직접 답하는 편이 더 빠르고, 더 안정적이고, 더 저렴하다.

판단 기준: 「이 질문을, 모델이 외부 데이터를 조회하지 않고도 정확히 답할 수 있는가?」를 자문하라 . 그럴 수 있다면 도구를 추가하지 마라. 도구 호출은 「모델 스스로는 답할 수 없고 반드시 외부 정보나 동작에 의존해야 하는」 상황에 남겨둘 때, Agent가 더 안정적이고 더 절약된다.

8. 요약: 모델을 「결정자」로, 애플리케이션을 「실행자」로

도구 호출의 본질은 모델과 애플리케이션 사이의 분업 협력이다:

- 모델: 의도를 이해하고, 도구를 선택하며, 파라미터를 생성한다(의사결정자)

- 애플리케이션: 파라미터를 검증하고, 실제 실행하며, 결과를 되돌려준다(실행자)

당신이 해야 할 일은: 도구 설명을 모델이 한눈에 이 도구를 써야 하는지 아닌지, 파라미터를 어떻게 채워야 하는지 알 수 있도록 다듬는 것, 실행 전에 파라미터 검증과 고위험 작업에 대한 2차 확인을 갖추는 것, 그리고 모델의 출력이 항상 후보 파라미터가 되게 하여 당신의 정제를 거친 뒤에야 반영되게 하는 것이다. 도구 호출 오류의 엔지니어링 방어선에 대해 더 깊이 알고 싶다면, AI07 방어 계층과 AI06 오호출 문제 진단을 다시 살펴보면 된다.

판단 마무리: 작업에 실시간 데이터, 외부 시스템 또는 실제 동작이 필요할 때는 도구 호출을 사용하고, 모델이 직접 정확히 답할 수 있을 때는 도구를 쓰지 말라—도구는 능력 확장이지 만능 열쇠가 아니다.

칼럼 소개: 이 칼럼 《AI Agent 도구》는 Agent 도구 호출의 실전 활용에 집중하며, 도구 호출 메커니즘, 파라미터 검증, 오호출 진단부터 방어 계층 구현까지 차례로 다루고, 각 글마다 바로 실행할 수 있는 코드 한 편을 곁들여 매주 한 편씩 업데이트한다. 순서대로 끝까지 읽고 싶다면 칼럼 페이지에서 구독하면 된다.