Function Calling Migration：구 API에서 새 SDK로의 실전 가이드

이주의 진정한 출발점: 단순히 종착지를 바꾸는 것 이상의 의미

모델 버전 업그레이드 공지에서 "XX API가 폐기되었습니다. 새로운 SDK로 마이그레이션해 주세요"라는 안내를 보면, 첫 반응은 요청 URL과 매개변수 이름을 교체하는 것입니다. 하지만 Function Calling에서는 이 아이디어가 바로 마이그레이션 실패의 가장 큰 원인입니다.

함수 호출 마이그레이션의 핵심은 API 주소 변경이 아니라, 도구 호출 메커니즘의 패러다임 전환입니다. 구형 OpenAI용 Chat Completions API에서는 함수가 functions 매개변수로 정의되며, 모델은 function_call 객체를 반환합니다; 새로운 Responses API 또는 Assistants API에서는 도구 정의, 호출 컨텍스트, 상태 관리가 tools 매개변수와 tool_choice, 병렬 함수 호출, 그리고 더 엄격한 출력 형식 제약으로 통합되었습니다.

실제 사례: 개발팀이 이전 API에서 20개의 함수 정의를 새 API로 직접 복사했는데, 모델이 자주 "유효하지 않은 도구 호출" 오류를 반환한다는 것을 발견했습니다. 조사 결과, 새 API는 각 도구에 대해 description 필드에 매개변수 의존성을 명시적으로 지정해야 한다는 사실이 밝혀졌습니다(예: "이 함수를 호출하기 전에 사용자 ID를 반드시 얻으세요"). 이는 이전 API가 이를 강제하지 않았습니다.

가장 흔한 실패: 암묵적 맥락 상실(Implicit Context Loss)

이주에서 가장 숨겨진 함정은 맥락 상태 상실입니다. 이전 API에서는 개발자들이 함수 호출의 중간 결과를 메시지 배열에 다시 삽입하여 모델이 자연스럽게 이력을 감지할 수 있도록 하는 데 익숙했습니다. 하지만 새로운 API의 에이전트 루프(예: run + tool_outputs 패턴 사용)에서는 도구의 실행 결과가 thread 또는 step 구조에 엄격히 따라 반환되어야 합니다. 형식이 잘못되면 모델은 이전 모든 도구 출력을 무시하여 에이전트 워크플로우가 중단됩니다.

구체적인 오류 시나리오:

• 다단계 툴체인에서는 먼저 search_database를 호출해 10개의 레코드를 반환한 후, format_results로 호출하여 이전 단계 결과를 바탕으로 테이블 생성을 요청합니다. 하지만 새로운 API에서 search_database의 출력을 비표준 방식으로 tool_outputs에 삽입하면, 모델은 이 단계를 실패로 간주하고 format_results를 건너뛸습니다.
• 해결책: SDK의 submit_tool_outputs 인터페이스를 엄격히 준수하여 각 출력에 대응하는 tool_call_id가 포함되고, 출력 콘텐츠가 모델의 컨텍스트 한도(보통 4096 토큰)를 초과하지 않도록 합니다.

1단계: 감사 및 리팩토링의 도구 정의

지금 마이그레이션을 구현하고 싶다면, 첫 번째 단계는 코드를 변경하는 것이 아니라 도구 정의 감사를 수행하는 것입니다:

1. 모든 기존 함수를 나열하세요: 이름, 매개변수, 반환 형식 포함. 전제 도구의 출력에 의존하는 함수는 반드시 표시하세요(예: "차트 생성"은 "쿼리 데이터" 결과에 따라 달라집니다).
2. 세분화로 나누기: 새로운 API는 각 도구가 한 가지 기능만 하도록 권장합니다. 구형 API에서 흔히 쓰이는 "범용 함수"(예: execute_anything)는 단일 책임 함수로 분할되어야 했으며, 그렇지 않으면 모델이 쉽게 혼란스러워질 수 있었습니다.
3. 설명 덮어쓰기: 각 도구의 설명에는 전제 조건, 출력 형식, 일반적인 호출 시나리오가 포함되어야 합니다. 예를 들어:
   • 노년: "获取天气数据"
   • 신규: "根据城市名获取当前天气。需要先调用 check_city_exists 确认城市有效。返回 JSON 格式：{temperature, humidity, condition}"
4. 오류 처리 도구 추가: 모델이 처리할 수 없는 예외를 처리하기 위해 루프 호출을 피하기 위해 특별히 report_error 도구를 정의하세요.

감사를 완료한 후에는 개발 환경에서 새로운 에이전트 테스트 스크립트를 만들고 새 API의 client.responses.create 또는 client.beta.threads.runs.create를 사용해 각 도구 호출을 하나씩 검증합니다.

실용적 경로: 단순한 이주 사례

예를 들어 오래된 API 코드가 있다고 가정해 봅시다: ''python response = openai.ChatCompletion.create( model="gpt-4", messages=[{"role": "user", "content": "北京天气如何？"}], functions=[{ "name": "get_weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}} }] ) '`

迁移至新 API（OpenAI Python SDK v1.x+）： 'python from openai import OpenAI client = OpenAI()

response = client.responses.create( model="gpt-4o", input=[{"role": "user", "content": "北京天气如何？"}], tools=[{ "type": "function", "function": { "name": "get_weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}, "description": "根据城市名获取天气。参数 city 必须是中国城市的中文名称。" } }] ) '

注意新 API 使用了 input 而非 messages，且 tools 数组内每个工具需要显式 type 和更详细的 `description'.

미래 방향: 함수 호출에서 에이전트 루프로

마이그레이션의 논리를 이해하는 것은 더 복잡한 에이전트 워크플로우에 대비하는 것입니다. 도구 정의, 컨텍스트 관리, 오류 복구를 마스터하면 다중 도구 오케스트레이션, 메모리 관리,MCP프로토콜 통합 같은 고급 주제로 넘어갈 수 있습니다.

일반 개발자에서 에이전트 엔지니어로 전환하고 싶다면, 다음 단계는 더 체계적인 오리지널 유료 기사나 강좌에 참여하는 것입니다.