11.1 Thread, Message, ToolCall 구조의 이해

OpenAI의 Assistants API는 기존의 단순한 일회성 대화 방식에서 벗어나, 장기적인 컨텍스트 관리와 도구 조합 실행을 가능하게 하는 새로운 대화형 에이전트 플랫폼입니다. Assistants API를 사용하면 사용자는 단일 호출로 끝나는 정적 응답이 아닌, 지속적으로 상태를 이어가는 동적 상호작용, 복잡한 작업 처리, 코드 실행, 도큐먼트 검색, 사용자 정의 함수 호출 등의 다양한 기능을 활용할 수 있습니다.

이 장에서는 Assistants API의 핵심 구조인 Thread, Message, ToolCall을 중심으로 그 동작 원리를 예제 중심으로 상세히 해설합니다.

11.1.1 Assistants API의 주요 개념 요약

먼저 간단히 세 개념의 역할을 개요적으로 비교하면 다음과 같습니다.

개념
설명

Thread

하나의 대화 세션. Messages의 컨테이너.

Message

user/assistant가 Thread 내에 남긴 대화 항목.

ToolCall

Assistant가 도구(코드, 검색, 함수 등)를 사용하려 할 때의 호출 시도. (function_call, code_interpreter 등)

11.1.2 Thread란 무엇인가?

Thread는 특정 사용자와 Assistant 간의 하나의 대화 세션을 나타냅니다. 기존 Chat Completion API에서의 컨텍스트는 매 호출마다 메시지를 직접 유지해야 했지만, Assistants API는 서버 측에서 Thread에 메시지와 상태 정보를 저장하며, 언제든지 이어서 대화를 계속할 수 있는 구조를 제공합니다.

✅ Thread의 특징

  • 고유한 thread_id를 통해 식별됨.

  • 같은 Thread에 Message를 계속 추가함으로써 대화를 이어갈 수 있음.

  • Assistant는 Thread의 전체 컨텍스트를 바탕으로 응답을 생성.

🔧 예제: 새 Thread 생성

from openai import OpenAI

client = OpenAI()

# 새로운 Thread 생성
thread = client.beta.threads.create()
print(thread.id)  # ex: "thread_xyz123"

11.1.3 Message란 무엇인가?

Message는 하나의 대화 단위를 나타냅니다. 사용자의 질문이나 입력, Assistant의 응답 등이 각각 하나의 Message로 Thread 안에 저장됩니다.

✅ Message의 구성 요소

  • 역할 (role): "user" 또는 "assistant"

  • 내용 (content): 프롬프트 문자열 또는 응답 텍스트

  • 첨부 파일 (optional): 파일 ID 등

  • 생성 시간, 고유 ID 등 메타데이터

🔨 Message 추가 예제

# User가 Thread에 메시지를 추가
user_input = "파이썬에서 리스트를 역순으로 정렬하려면 어떻게 하나요?"

response = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content=user_input
)

이후 Assistant는 이 Thread 및 Message를 참조하여 적절한 응답을 생성합니다.

11.1.4 Run: Assistant가 Thread를 처리하는 실행 단위

Assistant가 주어진 Thread를 분석하고 Message에 응답하려면 'Run'을 생성해야 합니다. Run은 해당 Thread에서 Assistant가 도출한 응답 프로세스를 추적하는 단위입니다.

run = client.beta.threads.runs.create(
    thread_id=thread.id,
    assistant_id="asst_abc123"
)

이후 이 Run이 끝나면, Assistant의 응답은 자동으로 Message로 Thread에 추가됩니다.

⚠️ 'Run'이라는 개념은 대화 하나하나에 대해 수행되는 구조입니다. Thread는 대화방이고, Run은 Assistant가 질문에 답하는 실행 작업이라 이해하세요.

11.1.5 ToolCall: 도구 호출 구조

Assistants API에서는 AI가 외부 도구를 호출해 도움을 받을 수 있도록 설계되어 있습니다. 예컨대 복잡한 계산을 Code Interpreter로 수행하거나, 특정 DB를 조회하기 위해 Custom Function Call을 할 수 있습니다. 이런 도구 요청은 ToolCall로 표현됩니다.

✅ ToolCall이란?

ToolCall은 Assistant가 실행해야 하는 하나 이상의 도구 호출 요청입니다.

종류는 크게 다음과 같습니다:

  • function (사용자 정의 함수 호출)

  • code_interpreter (코드 실행 도구)

  • file_search (파일 내 검색 도구, 업로드한 PDF 등)

  • 기타 future tools (추후 확장 가능)

▶ function ToolCall 예시

Function 툴을 사전에 등록했다면, Assistant가 응답을 생성할 때 해당 함수를 호출하게 만들 수 있습니다.

예를 들어, 사용자 정의 함수 get_weather(location: str)을 도구로 등록했다고 가정합시다.

Assistant 프롬프트 중에 다음과 같이 발화할 수 있습니다:

{
  "tool_calls": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "arguments": "{ \"location\": \"Seoul\" }"
      }
    }
  ]
}

이때 OpenAI 서버는 실제 함수 실행을 개발자에게 위임하며, 이 호출 결과를 수신하면 Assistant의 응답이 계속 이어집니다.

11.1.6 ToolCall 처리 흐름

  1. Assistant가 메시지를 보고 도구 호출이 필요하다고 판단 → ToolCall 포함된 응답 생성

  2. 개발자가 ToolCall을 감지하고 대응하여 실제 함수나 코드 실행

  3. ToolCall 결과를 다시 Thread에 Message 형태로 추가

  4. 새로운 Run 수행 → 최종 사용자 전달용 응답 생성

📌 ToolCall 응답 전달

# ToolCall 응답을 Assistant에 전달
client.beta.threads.runs.submit_tool_outputs(
    thread_id=thread.id,
    run_id=run.id,
    tool_outputs=[
        {
            "tool_call_id": "call_001",
            "output": "현재 서울의 날씨는 맑고 25도입니다."
        }
    ]
)

11.1.7 전체 흐름 정리

다음은 Assistants API의 전체 응답 흐름을 도식화한 것입니다.

사용자 입력(Message)
       ↓
Thread에 메시지 추가
       ↓
Assistant 실행 요청(Run 생성)
       ↓
・단순 응답 → 결과 Message 저장
・도구 필요 → ToolCall 생성
       ↓
ToolCall 실행 → 결과 전달
       ↓
최종 Assistant 응답 생성 → Message 추가

11.1.8 Message/Run/ToolCall 상태 추적

  • Message는 시간순으로 Thread 안에서 계속 누적

  • Run은 실행 상태 (queued, in_progress, completed, requires_action 등)로 구분

  • ToolCall도 각 단계별 상태, ID, 인자 정보 보유

  • 상태 조회: .list() 또는 .retrieve() API 제공

messages = client.beta.threads.messages.list(thread_id=thread.id)
for m in messages.data:
    print(m.role, m.content)

11.1.9 핵심 요약

구성 요소
설명

Thread

전체 대화 세션. 상태 유지

Message

개별 발화. user / assistant 구분

Run

Assistant의 실행 단위. 메시지 → 응답 흐름 처리

ToolCall

기능 있는 응답을 위한 도구 요청. function, code 등

11.1.10 참고: 기존 Chat Completion API와의 차이점

기능
Chat Completions API
Assistants API

대화 상태 저장

❌ 매번 수동 전달

✅ Thread 내부 관리

Tool Call 처리

✅ 가능 (함수 호출 위주)

✅ 도구 체계화, 코드 실행 등 포함

파일 업로드/검색

❌ 복잡

✅ 기본 제공 기능

다단계 응답

❌

✅ ToolCall + 응답 흐름

에이전트 구성

❌ 자체 구현 필요

✅ Assistants에 설정

마무리

이 장에서는 Assistants API의 핵심 구조인 Thread, Message, ToolCall의 개념과 직관적인 사용 흐름을 상세히 설명했습니다. 다음 장에서는 이러한 기초 지식을 바탕으로, Functions, File Search, Code Interpreter 등 실제 기능을 Assistants 안에서 통합적으로 실행하는 예제를 다룹니다.

🔜 계속해서 11.2장 「코드 실행(Code Interpreter) 연동」으로 이동하여, ToolCall 중 'code_interpreter' 도구 활용법을 자세히 살펴보겠습니다.

Previous11.0 Assistants API 실전 사용법Next11.2 코드 실행(Code Interpreter) 연동

Last updated