Gemini 함수 호출에서 모델과 애플리케이션의 책임을 나누는 법

Gemini API로 업무 도구를 만들 때 가장 먼저 분리해야 할 것은 “모델의 제안”과 “애플리케이션의 실행”이다. 함수 호출에서 모델은 어떤 함수를 어떤 인자로 호출할지 구조화해 반환할 수 있다. 하지만 실제 함수 코드를 실행하거나 외부 API에 요청을 보내는 주체는 애플리케이션이다. 실행 뒤에는 그 결과를 다시 모델에 전달해 최종 응답을 만들게 하는 흐름으로 설계한다.

이 구분은 자동화의 통제 지점을 분명하게 만든다. 모델 출력만으로 외부 시스템이 바뀌는 구조로 생각하면, 검증·권한·오류 처리를 놓치기 쉽다. 반대로 애플리케이션을 실행 책임자로 두면, 호출 전 검사와 실행 후 결과 전달을 같은 흐름 안에서 관리할 수 있다.

핵심 역할 한눈에 보기

단계	모델의 역할	애플리케이션의 역할
함수 선택	호출할 함수명과 인자를 구조화해 반환	반환값을 읽고 처리 대상으로 삼음
실제 실행	함수를 직접 실행하지 않음	실제 함수 코드 실행 및 외부 API 요청
결과 반영	전달받은 실행 결과를 바탕으로 최종 응답 생성	실행 결과를 모델에 다시 전달
상호작용 기록	모델 출력 또는 함수 호출을 생성할 수 있음	호출과 결과를 다음 단계에 연결

Google AI for Developers의 함수 호출 문서는 모델이 함수명과 인자를 반환할 수 있다고 설명한다. 동시에 실제 함수 실행과 외부 API 요청은 애플리케이션의 책임이라고 명시한다. 따라서 함수 선언은 모델이 이해할 수 있는 선택지이고, 실행 권한 자체가 아니다.

업무 자동화 흐름을 설계하는 순서

1. 자동화할 작업을 함수 단위로 나눈다

먼저 업무 과정을 작은 실행 단위로 나눈다. 예를 들어 “요청 내용 정리”, “외부 시스템에 조회 요청”, “조회 결과를 사용자에게 설명”처럼 분리할 수 있다. 여기서 외부 시스템에 요청하는 부분은 애플리케이션이 실행할 함수로 둔다.

함수마다 이름과 받을 인자를 정한다. 모델은 이 정의를 바탕으로 함수명과 인자를 구조화해 반환한다. 애플리케이션은 반환된 값이 실제 실행에 필요한 형태인지 확인하는 위치에 놓인다. 모델이 인자를 제안하는 단계와 애플리케이션이 실행하는 단계는 하나로 합치지 않는다.

2. 모델의 함수 호출 출력을 받는다

사용자 요청을 모델에 전달하면 모델은 일반 텍스트 대신 함수 호출을 반환할 수 있다. 이때 애플리케이션은 함수명과 인자를 추출한다. 기존 Generate Content API의 함수 호출 예제도 모델 응답에서 함수명과 인자를 꺼낸 뒤 애플리케이션이 실제 함수를 호출하는 흐름을 설명한다.

최신 기능을 사용하려는 경우에는 해당 문서가 안내하는 대로 Interactions API를 우선 검토할 수 있다. 이 글에서 중요한 점은 API 형태가 달라도 실행 책임이 애플리케이션에 있다는 원칙이다.

3. 애플리케이션에서 실행 여부를 결정한다

함수 호출을 받았다고 즉시 외부 API 요청을 보내는 것은 설계상 필수 단계가 아니다. 호출 출력은 애플리케이션이 처리하는 입력이다. 따라서 실행 전에 함수명이 허용된 대상인지, 인자가 필요한 형식인지, 현재 작업이 실제 실행 대상인지 확인하는 절차를 둘 수 있다.

이 절차는 모델이 외부 시스템을 직접 제어하는 것이 아니라는 사실을 구현에 반영한다. 애플리케이션은 실행하지 않을 수도 있고, 실행 가능한 호출만 실제 함수에 넘길 수도 있다. 문서가 설명하는 책임 범위 안에서 애플리케이션이 외부 API 요청과 함수 코드 실행을 맡는다.

4. 실제 함수와 외부 API 요청을 실행한다

검사를 통과한 호출은 애플리케이션이 실제 함수 코드로 실행한다. 외부 서비스의 정보를 조회하거나 업무 시스템에 요청을 보내는 동작도 이 단계에서 수행한다. 모델은 함수명과 인자를 반환했지만, 외부 API 요청을 직접 수행하는 것은 아니다.

실행 과정에서 나온 값은 다음 단계의 입력으로 보관한다. 성공 결과만이 아니라 실행되지 않은 경우나 처리할 수 없는 경우도 애플리케이션이 구분해 다룰 수 있다. 핵심은 실행 결과가 모델의 최초 출력과 별개로, 애플리케이션이 만든 결과라는 점이다.

5. 함수 결과를 다시 모델에 전달한다

실행이 끝나면 애플리케이션은 함수 결과를 모델에 다시 전달한다. Gemini 함수 호출 문서는 이 결과 전달 뒤 모델이 최종 응답을 생성하게 하는 흐름을 설명한다. 따라서 사용자가 보는 최종 문장은 함수 호출 자체가 아니라, 실행 결과를 반영한 다음 모델 단계에서 만들어질 수 있다.

이 분리는 설명과 실행을 연결한다. 애플리케이션은 실행을 담당하고, 모델은 전달받은 결과를 바탕으로 사용자에게 응답한다. 결과를 전달하지 않으면, 모델이 실제 실행 결과를 반영해 최종 응답을 만들도록 하는 문서상의 흐름도 완성되지 않는다.

Interactions API로 실행 단계를 읽는 방법

Interactions API에서 Interaction은 모델 출력, function_call, function_result 같은 실행 단계를 기록한다. 이 구조는 함수 호출이 모델과 도구 실행 사이의 구조화된 상호작용으로 표현된다는 점을 보여 준다.

실무에서는 이 기록을 단계별로 읽는 방식이 유용하다. 먼저 모델 출력에서 함수 호출이 있는지 확인한다. 다음으로 애플리케이션이 그 호출을 처리한다. 그 뒤 함수 결과를 결과 단계로 연결한다. 마지막으로 결과를 바탕으로 생성된 응답을 확인한다. 이렇게 보면 어느 단계가 모델 출력인지, 어느 단계가 애플리케이션 실행인지 섞이지 않는다.

구현 체크리스트

[ ] 자동화할 외부 동작을 애플리케이션 함수로 분리했는가?
[ ] 모델이 반환한 함수명과 인자를 애플리케이션에서 추출하는가?
[ ] 실제 함수 코드 실행과 외부 API 요청을 애플리케이션이 맡는가?
[ ] 실행 결과를 모델에 다시 전달하는 흐름이 있는가?
[ ] 최종 응답이 실행 결과를 반영하도록 다음 모델 단계를 두었는가?
[ ] function_call과 function_result를 서로 다른 실행 단계로 구분하는가?
[ ] 최신 기능 검토 시 Interactions API 안내를 확인했는가?

제한 사항과 주의할 점

함수 호출은 모델이 실제 함수를 실행했다는 뜻이 아니다. 문서가 설명하는 모델 출력은 호출할 함수명과 인자의 구조화된 반환이다. 실제 코드 실행과 외부 API 요청은 애플리케이션이 담당한다. 그러므로 자동화의 성공 여부는 함수 호출 출력만으로 판단할 수 없다. 애플리케이션의 실행 결과와 그 결과를 모델에 전달하는 단계까지 확인해야 한다.

또한 Interactions API의 기록에 function_call과 function_result가 포함될 수 있다는 점은, 호출과 결과가 같은 단계가 아님을 뜻한다. 호출을 받는 단계, 실행하는 단계, 결과를 돌려주는 단계를 구분해 구현해야 한다. 제공된 문서 범위를 넘어 특정 외부 서비스의 권한 방식, 오류 형식, 재시도 정책을 일반화할 수는 없다. 그런 세부 사항은 연결하려는 서비스의 공식 문서에서 별도로 확인해야 한다.

개발·에이전트·인프라 성격의 자동화 작업을 위한 컴퓨팅 선택 항목으로는 Apple Mac mini를 둔다. 이 글의 구현 원칙은 제품 기능이나 성능을 전제하지 않으며, 함수 호출의 실행 책임을 애플리케이션에 두는 구조에 관한 것이다.

FAQ

Gemini가 함수 호출을 반환하면 외부 API도 호출된 것인가?

아니다. 제공된 함수 호출 문서는 모델이 함수명과 인자를 구조화해 반환하고, 실제 함수 코드 실행과 외부 API 요청은 애플리케이션의 책임이라고 설명한다.

함수 실행 뒤 왜 결과를 다시 모델에 보내야 하나?

문서는 애플리케이션이 실행 결과를 모델에 전달해 최종 응답을 생성하게 하는 흐름을 설명한다. 결과 전달은 실행 정보가 최종 응답 단계에 반영되게 하는 연결이다.

Interactions API에서 무엇을 구분해야 하나?

Interaction에 모델 출력, function_call, function_result 등의 실행 단계가 기록될 수 있다. 따라서 함수 호출과 함수 결과를 분리해 읽고, 그 사이의 실제 실행은 애플리케이션 책임으로 다룬다.

기존 Generate Content API 예제는 어떤 흐름을 보여 주나?

모델 응답에서 함수명과 인자를 추출한 다음 애플리케이션이 실제 함수를 호출하는 흐름을 보여 준다. 해당 문서는 최신 기능에는 Interactions API 사용을 권장한다고 안내한다.

구매 전 판매 페이지의 구성과 사용 대상을 다시 확인해.

공식 근거

이 게시물은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.