Google의 `Agents` 백서로 알아보는 AI Agent! (2): Extension과 Function 중심
지난 글에서 자세히 다루지 못했던 Extension과 Function에 대해 자세히 살펴보도록 하겠습니다.
Agent에 대해 전반적인 내용 설명은 지난 글을 참고해주세요!
Google의 AI 에이전트 백서에서는 Extension(확장)과 Function(함수 호출)을 에이전트가 외부 데이터를 활용하는 두 가지 주요 방법으로 설명합니다.
두 개념 모두 API와 연결되지만, 동작 방식과 사용 목적이 다릅니다.
1. Extensions (확장)
- 에이전트 내부에서 실행되며, API를 직접 호출할 수 있도록 연결해주는 역할
- 즉, 에이전트가 직접 API를 호출하고 응답을 처리하는 구조
Extension은 Agent와 외부 API를 연결
Agent 내에 여러 개의 API 연동을 위한 여러 개의 Extension이 존재할 수 있습니다
주요 특징
에이전트 내부에서 API 요청이 실행됨
API 호출을 자동으로 수행하여 실시간 정보를 가져옴
- API 사용법과 입력값을 학습하여, 적절한 API 호출을 수행함
만약 사용자의 프롬프트에서 추출할 수 있는 API 입력값의 내용이 불충분하다면 추가 질문을 통해 API 입력값을 정의할 수 있음
- 완전히 에이전트 내부에서 동작하며, 클라이언트 측 실행이 필요 없음
예시: 항공권 검색
예를 들어, 사용자가 “서울에서 뉴욕으로 가는 비행기 예약해줘.” 라고 하면:
- 에이전트가 Google Flights API를 호출할 필요가 있다고 판단
- Extension을 사용하여 API 호출 (
GET /flights?from=ICN&to=JFK) - API 응답을 받아 사용자가 이해할 수 있는 형태로 변환
- “대한항공, 아시아나항공 항공편이 있습니다. 어느 항공사를 원하시나요?” 라고 응답
즉, Extension은 API 호출을 직접 수행하고, 결과를 사용자의 요청에 맞게 가공하여 응답을 생성합니다.
2. Functions (함수)
- Function은 에이전트가 직접 API를 호출하는 것이 아니라, API를 호출할 수 있는 함수를 클라이언트(외부 시스템)로 넘겨줌으로써 실행이 이루어지는 방식
- 즉, API 호출을 위한 JSON 형식의 데이터를 반환하여 클라이언트 측(UI 또는 애플리케이션)이 실행할 수 있도록 하는 방식입니다.
- 이를 통해 API 실행의 보안, 인증, 데이터 흐름 등을 보다 유연하게 관리할 수 있습니다.
Fcuntion은 Agent에게 API 호출을 위한 명령(명세, Specification)을 제공
주요 특징
- 에이전트가 API를 직접 호출하지 않음
- API 호출은 클라이언트 측 애플리케이션에서 실행
- API 호출 전에 추가적인 데이터 변환, 검토, 보안 처리가 가능
- 비동기(Asynchronous) 작업이나 인증이 필요한 API 호출(인증으로 인해 Agent에서 직접 API접근 X)에 유리
예시: 항공권 검색
똑같은 “서울에서 뉴욕으로 가는 비행기 예약해줘.” 요청이 있을 때, Function 방식을 사용하면:
에이전트가 Google Flights API를 호출할 필요가 있다고 판단
하지만 Function은 직접 API를 호출하는 대신, 함수 호출 정보만 생성
1 2 3 4 5 6 7 8
{ "function_name": "get_flights", "arguments": { "departure": "ICN", "arrival": "JFK", "date": "2024-06-01" } }
클라이언트 측(예: 모바일 앱, 웹사이트)이 이 정보를 받아 실제 API를 호출
API 응답을 받아 클라이언트가 사용자에게 정보를 제공
즉, Function 방식은 API 호출을 직접 하지 않고, 필요한 정보만 전달하여 클라이언트가 API를 실행하도록 위임하는 방식입니다.
Funtion 호출 흐름
여행 Chatbot이 스키 여행지를 추천할 때, 사용자가 “스키 여행을 가고 싶은데 어디가 좋을까?”라고 입력 후 Function을 이용하여 API 호출을 클라이언트가 수행하도록 설정하는 플로우입니다. (이때 Google Place API를 사용합니다.)
- 사용자가 “스키 여행을 가고 싶은데 어디가 좋을까?”라고 입력
- 모델이 스키 여행지 리스트 생성
- 에이전트는 적절한 여행지를 추천하는
"display_cities" Function 호출을 생성 (JSON 형태로 변환)
1
2
3
4
5
6
7
8
9
{
"function_call": {
"name": "display_cities",
"arguments": {
"cities": ["Crested Butte", "Whistler", "Zermatt"],
"preferences": "skiing"
}
}
}
- 클라이언트 측 UI가 이 JSON을 받아 Google Places API에 실제 요청을 보냄
- API에서 응답을 받아 스키 리조트 이미지 및 상세 정보를 사용자에게 표시
3. 차이점 정리
Agent 주도방식(Extension)과 Client 주도방식(Function)의 차이
| Extension | Function | |
|---|---|---|
| 실행 위치 | 에이전트 내부에서 API 호출 및 실행 | 클라이언트(외부 시스템)에서 API 실행 |
| API 호출 방식 | 직접 API 호출 | API 호출을 위한 함수 정보만 제공 |
| 실행 흐름 | Agent에서 즉각적인 API 실행 및 결과 반환 | 클라이언트가 API를 실행해야 결과 확인 가능 |
| 보안 및 인증 | 에이전트 내부에서 처리 | 클라이언트가 인증 및 보안 검증 수행 가능 |
| 비동기 작업 | 지원하지 않음 (즉시 실행) | 지원 가능 (예: 대기 시간이 긴 작업) |
| 사용 사례 | 간단한 API 호출 (날씨, 검색, 지도 등) | API 호출 시 인증이 필요하거나, 사용자 확인이 필요한 경우 |
🔑 언제 Extension과 Function을 사용해야 할까?
| 사용 상황 | Extension 사용 | Function 사용 |
|---|---|---|
| API 호출이 간단하고 즉각적인 응답이 필요한 경우 | ✅ | ❌ |
| API 호출 전에 보안 검토, 승인 과정이 필요한 경우 | ❌ | ✅ |
| 외부 API 호출을 사용자에게 위임해야 하는 경우 | ❌ | ✅ |
| 검색, 날씨, 단순 정보 조회 같은 즉각적인 API 호출 | ✅ | ❌ |
| 데이터 변환, 추가 처리 후 API를 호출해야 하는 경우 | ❌ | ✅ |
👉 즉각적인 응답이 필요하다면 “Extension”, API 실행을 클라이언트에서 제어해야 한다면 “Function”을 사용!
4. 실제 코드 예제
4-1. Extension 방식 (에이전트 내부에서 API 호출)
1
2
3
4
5
6
7
8
9
10
11
12
from vertexai.preview.extensions import Extension
# Google Flights API 확장 불러오기
flight_extension = Extension.from_hub("google_flights")
# API 호출을 실행 (에이전트 내부에서 실행됨)
response = flight_extension.execute(
operation_id="get_flights",
operation_params={"departure": "ICN", "arrival": "JFK", "date": "2024-06-01"}
)
print(response)
✅ 에이전트가 직접 API를 호출하고 결과를 반환 ✅ 사용자가 응답을 바로 받을 수 있음
4-2. Function 방식 (클라이언트 측에서 API 호출)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
from vertexai.generative_models import GenerativeModel, FunctionDeclaration
# API 호출을 위한 함수 정의
def get_flights(departure: str, arrival: str, date: str):
return {"function_name": "get_flights", "arguments": {"departure": departure, "arrival": arrival, "date": date}}
# 함수 선언
get_flights_function = FunctionDeclaration.from_func(get_flights)
# 모델과 툴 구성
model = GenerativeModel("gemini-1.5-flash-001")
tool = Tool(function_declarations=[get_flights_function])
# 사용자 입력
message = "서울에서 뉴욕으로 가는 비행기 예약해줘."
res = model.generate_content(message, tools=[tool])
# 에이전트는 직접 API를 호출하지 않고, 함수 호출 정보만 제공
print(res.candidates[0].content.parts[0].function_call)
✅ 에이전트는 API를 실행하지 않고 함수 호출 정보만 반환 ✅ 클라이언트가 API 호출을 실행할 수 있도록 정보 제공
🌊 Deep Dive! Hybrid 방식(Extension + Function)
🔗 Extension과 Function을 함께 사용하는 방식 (Hybrid Approach)
Extension과 Function은 각각 에이전트가 외부 API와 상호작용하는 방식이지만, 특정한 시나리오에서는 이 둘을 함께 사용하여 더 강력하고 유연한 AI 에이전트를 구축할 수 있습니다.
🛠 Extension과 Function을 함께 사용하면?
- Extension을 사용하여 즉시 호출 가능한 API를 먼저 활용
- Function을 사용하여 비동기 실행이 필요한 API 호출을 클라이언트에서 수행
📌 예제: 여행 컨시어지(Chatbot)
여행 예약을 도와주는 AI 챗봇을 구축할 때, Extension과 Function을 함께 사용하는 방식을 살펴보겠습니다.
1️⃣ 사용자 요청 예제
“뉴욕에서 5일간 머물면서 관광할 계획인데, 호텔을 추천(=>Extension)해주고 비행기도 예약(=>Function)해줘.”
2️⃣ Extension을 활용한 즉시 API 호출
- 에이전트는 Google Places API를 Extension으로 호출하여 호텔 정보를 검색
- 즉시 API 호출 후 응답 반환 (실시간 호텔 추천)
1
2
3
4
5
6
7
{
"name": "get_hotels",
"arguments": {
"location": "New York",
"stay_duration": "5 days"
}
}
- API 응답:
1
2
3
4
5
6
{
"hotels": [
{ "name": "Hotel A", "rating": 4.5, "price": "$200 per night" },
{ "name": "Hotel B", "rating": 4.3, "price": "$180 per night" }
]
}
- 사용자에게 호텔 추천을 즉시 제공.
3️⃣ Function을 활용한 비동기 실행
- 비행기 예약 API는 사용자 승인이 필요하고, 보안 검증(결제, 여권 정보 입력 등)이 필요하기 때문에 클라이언트에서 실행하도록 Function 호출 생성.
1
2
3
4
5
6
7
8
9
10
11
{
"function_call": {
"name": "book_flight",
"arguments": {
"departure": "ICN",
"arrival": "JFK",
"date": "2024-06-01",
"passenger_name": "John Doe"
}
}
}
- 클라이언트(UI)에서 API를 호출하여 비행기 예약 진행.
📌 Hybrid Approach의 장점
- Extension으로 즉각적인 정보 제공 가능 (호텔 검색, 날씨 확인 등)
- Function으로 보안이 필요한 API 요청을 클라이언트에서 수행 (결제, 예약 등)
- 에이전트의 복잡성을 줄이면서도, 유연한 API 호출이 가능
그 외 사례
- 호텔 추천 + 비행기 예약 (즉시 추천 + 예약 요청 전달)
- 실시간 주가 조회 + 증권 거래 요청 (시세 확인 + 트랜잭션 요청)
- 쇼핑 검색 + 결제 진행 (상품 추천 + 결제 요청)
- 의료 정보 검색 + 원격 진료 예약 (병원 찾기 + 진료 예약 요청)
즉시 실행할 수 있는 API는 Extension으로 처리하고, 보안 또는 사용자 승인 필요 작업은 Function으로 처리하는 것이 가장 효과적인 접근 방식입니다!
출처