AIMessage, ToolMessage, Tool Calling 완벽 이해: AIMessage → ToolMessage → AIMessage 흐름
AI 기반의 챗봇이나 자동화 시스템을 설계할 때, 단순히 모델이 답변을 생성하는 것이 아니라 외부 API, 데이터베이스, 코드 실행 등의 툴(Tool)을 호출해야 하는 경우가 많습니다.
이때 Tool Calling(툴 호출) 개념이 사용되며, 대표적으로 OpenAI의 Function Calling이나 LangChain의 Tool 기능이 있습니다.
오늘은 Tool Calling의 핵심 흐름인 AIMessage → ToolMessage → AIMessage 구조를 이해하고, tool_calls 필드가 왜 중요한지 살펴보겠습니다.
1. AIMessage → ToolMessage → AIMessage 흐름이란?
Tool Calling 과정에서 메시지는 다음과 같은 흐름을 따릅니다.
① AIMessage (툴 호출 요청)
사용자의 질문을 받은 LLM이 자체적으로 답변을 생성하지 않고, 외부 툴을 호출해야 한다고 판단하면 tool_calls 필드를 포함한 메시지를 생성합니다.
이때 중요한 점은 LLM이 직접 툴을 실행하는 것이 아니라, 툴을 호출하는 요청만 만든다는 것입니다.
🔹 예제 (AIMessage - Tool 호출 요청)
{
"content": null,
"tool_calls": [
{
"id": "123",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{ \"location\": \"Seoul\" }"
}
}
]
}✔ "get_weather"라는 툴을 호출해야 함을 나타냄.
✔ "location": "Seoul" 값을 툴에 전달하도록 요청함.
✔ LLM은 툴을 직접 실행하지 않고, 툴을 호출하는 요청만 생성.
즉, tool_calls이 포함된 AIMessage는 반드시 툴을 실행해야 하며, 툴이 실행되지 않으면 LLM은 후속 응답을 생성할 수 없습니다.
② ToolMessage (툴 실행 및 결과 반환)
AIMessage에서 툴을 호출했으므로, 실제 툴이 실행되고 결과를 반환해야 합니다.
이 역할을 하는 것이 ToolMessage이며, 툴의 실행 결과를 담고 있습니다.
🔹 예제 (ToolMessage - 툴 실행 결과)
{
"tool_call_id": "123",
"content": "{ \"temperature\": 15, \"condition\": \"Sunny\" }"
}✔ tool_call_id는 AIMessage에서 요청했던 것과 동일해야 함.
✔ "temperature": 15, "condition": "Sunny"라는 결과를 반환.
즉, 이 단계에서는 실제로 툴이 실행되며, API 호출, 데이터베이스 조회, 코드 실행 등의 작업을 수행하여 결과를 생성합니다.
③ AIMessage (최종 응답 생성)
툴이 반환한 결과를 바탕으로 LLM이 최종적으로 사용자에게 응답할 메시지를 생성합니다.
🔹 예제 (AIMessage - 최종 응답)
{
"content": "현재 서울의 온도는 15도이며, 날씨는 맑습니다."
}✔ LLM이 ToolMessage에서 받은 데이터를 바탕으로 자연어 응답을 생성.
✔ 툴을 통해 얻은 정보가 사용자에게 제공됨.
2. Tool Calling에서 tool_calls 여부의 중요성
✔ tool_calls이 없는 AIMessage의 의미
AIMessage에는 두 가지 경우가 있습니다.
1️⃣ LLM이 자체적으로 답변을 생성한 경우 (즉, Tool을 호출하지 않음)
{
"content": "서울의 날씨는 보통 봄에 따뜻하고 여름에는 덥습니다."
}tool_calls이 없고,content만 존재하는 경우.- LLM이 자체적인 지식을 기반으로 답변을 생성한 것.
- 툴을 호출하지 않음.
2️⃣ 이전 단계에서 Tool을 호출한 후, ToolMessage의 결과를 받아 LLM이 최종 응답을 생성한 경우
{
"content": "현재 서울의 온도는 15도이며, 날씨는 맑습니다."
}- 이전 단계에서 ToolMessage가 반환되었고, 이를 바탕으로 LLM이
content만 포함된 응답을 생성한 경우.
➡ 즉, tool_calls이 없는 AIMessage는 "이전 단계에서 Tool을 호출했을 수도 있고, 아닐 수도 있다."
➡ 반면, tool_calls이 포함된 AIMessage는 반드시 Tool을 호출해야 하고, ToolMessage가 없으면 후속 응답을 생성할 수 없다.
3. 전체 흐름 예제 (서울 날씨 조회)
✅ 정상적인 Tool Calling 흐름
1️⃣ 사용자 입력
"서울의 날씨 알려줘."
2️⃣ AIMessage (툴 호출 요청)
{
"tool_calls": [
{
"name": "get_weather",
"arguments": "{ \"location\": \"Seoul\" }"
}
]
}3️⃣ ToolMessage (툴 실행 결과 반환)
{
"tool_call_id": "123",
"content": "{ \"temperature\": 15, \"condition\": \"Sunny\" }"
}4️⃣ AIMessage (최종 응답 생성)
{
"content": "현재 서울의 온도는 15도이며, 날씨는 맑습니다."
}4. 마무리: Tool Calling의 핵심 정리
✅ AIMessage의 tool_calls 여부가 핵심
tool_calls이 존재하면 반드시 툴을 실행해야 하며, 툴 실행 결과가 없으면 후속 응답을 생성할 수 없음.tool_calls이 없으면 LLM이 자체적으로 답변을 생성하는 것으로 간주됨.
✅ AIMessage → ToolMessage → AIMessage의 필수 구조
- AIMessage: LLM이 툴 호출 요청을 생성.
- ToolMessage: 툴이 실행된 결과를 반환.
- AIMessage: 툴의 결과를 바탕으로 사용자 응답을 생성.
✅ Tool Calling의 목적
- LLM이 모든 정보를 알 수 없기 때문에, 툴을 통해 최신 데이터(API), 특정 지식(DB 조회), 계산(코드 실행) 등의 기능을 활용하는 것.
