DEV Community: Rihpig

AWS Strands Agents란? 오픈 소스 모델 기반 에이전트 SDK

Rihpig — Fri, 26 Jun 2026 08:27:21 +0000

거대한 if/else 상태 머신으로 AI 에이전트를 만들면 기능이 늘어날수록 라우팅, 예외 처리, 재시도 로직이 빠르게 취약해집니다. Strands Agents는 반대로 접근합니다. 사용자는 시스템 프롬프트와 도구 목록을 제공하고, 모델이 계획 수립과 도구 호출 순서를 결정하게 합니다. Strands Agents는 AWS의 오픈소스 SDK로, 2025년 5월 Apache License 2.0에 따라 공개되었으며 Amazon Q Developer 및 AWS Glue와 같은 Amazon 팀의 프로덕션 에이전트에도 사용됩니다.

지금 Apidog를 사용해 보세요

Strands Agents의 실제 동작 방식

Strands Agents는 몇 줄의 코드로 AI 에이전트를 만들고 실행하기 위한 SDK입니다. 기본 구성은 단순합니다.

사용할 모델을 선택합니다.
에이전트의 역할을 시스템 프롬프트로 정의합니다.
모델이 호출할 수 있는 도구를 등록합니다.
에이전트를 함수처럼 호출합니다.

실행 시 모델은 프롬프트를 읽고, 필요한 도구를 선택하고, 도구 실행 결과를 확인한 뒤, 작업이 끝났다고 판단할 때까지 이 루프를 반복합니다.

Strands는 Python과 TypeScript를 지원합니다. 이름은 에이전트를 구성하는 핵심 요소인 모델과 도구를 가리킵니다. AWS가 내부에서 운영한 뒤 오픈소스로 공개했기 때문에, 설계는 단순 데모보다 프로덕션 요구 사항에 가깝습니다. 미리보기 출시 이후 PyPI 다운로드 수가 15만 회를 넘었고, 다중 에이전트 기본 요소와 에이전트 간 A2A 프로토콜 지원을 포함한 1.0 릴리스에 도달했습니다.

이미 다른 에이전트 SDK를 검토했다면 Strands의 위치는 익숙할 수 있습니다. Strands는 LangGraph 및 Google ADK와 같은 범주에 있지만, 사용자가 직접 그래프를 설계하기보다 모델의 추론 루프에 더 많은 제어권을 줍니다.

모델 중심 방식과 하드코딩된 오케스트레이션 비교

초기 에이전트 프레임워크는 보통 워크플로우를 먼저 정의하도록 요구했습니다. 노드, 엣지, 조건, 라우팅 규칙을 작성하고, 모델은 그 안에서 선택을 수행합니다.

Strands는 이 책임을 모델 쪽으로 이동합니다. 최신 모델은 목표를 이해하고, 중간 단계를 계획하고, 도구를 호출하고, 결과를 바탕으로 다음 행동을 정할 수 있습니다. 따라서 개발자는 모든 분기를 코드로 인코딩하는 대신 다음 두 가지에 집중합니다.

좋은 시스템 프롬프트 작성
모델이 사용할 수 있는 도구 제공

접근 방식	개발자가 정의하는 것	제어 흐름 위치	새 기능 추가 비용
하드코딩된 오케스트레이션	노드, 엣지, 조건, 라우팅	사용자 그래프 코드	그래프 수정, 경로 재테스트
모델 중심 방식, Strands	프롬프트, 도구 목록	모델의 추론 루프	도구 추가, 프롬프트 업데이트

트레이드오프는 명확합니다. 모델 중심 에이전트는 빠르게 만들고 변경하기 쉽지만, 완전한 결정론은 줄어듭니다. 항상 동일한 순서로 실행되어야 하는 워크플로우라면 훅, 다중 에이전트 구조, 또는 그래프 기반 프레임워크가 더 적합할 수 있습니다.

최소 Strands 에이전트 만들기

가장 작은 Strands 프로그램은 Agent와 @tool만으로 시작할 수 있습니다.

from strands import Agent, tool

@tool
def word_count(text: str) -> int:
    """Count the words in a block of text."""
    return len(text.split())

agent = Agent(
    system_prompt="You are a concise writing assistant.",
    tools=[word_count],
)

response = agent("How many words are in this sentence?")
print(response)

여기서 핵심은 @tool 데코레이터입니다. 일반 Python 함수를 모델이 호출 가능한 도구로 변환합니다.

실무에서 확인해야 할 부분은 다음과 같습니다.

함수 이름은 모델이 이해하기 쉬워야 합니다.
독스트링은 도구의 목적을 명확히 설명해야 합니다.
타입 힌트는 입력 스키마로 사용되므로 가능한 한 정확해야 합니다.
도구는 예측 가능한 응답 형태를 반환해야 합니다.

예를 들어 외부 API를 호출하는 도구라면 다음처럼 실패 케이스를 명시적으로 반환하는 편이 디버깅에 유리합니다.

from strands import tool
import requests

@tool
def get_user_status(user_id: str) -> dict:
    """Fetch the current status for a user by user_id."""
    try:
        res = requests.get(
            f"https://api.example.com/users/{user_id}/status",
            timeout=5,
        )
        res.raise_for_status()
        return {
            "ok": True,
            "data": res.json(),
        }
    except requests.RequestException as exc:
        return {
            "ok": False,
            "error": str(exc),
        }

이렇게 하면 모델이 도구 실패를 일반 예외가 아니라 처리 가능한 결과로 볼 수 있습니다.

모델 제공업체 선택하기

Strands는 모델 제공업체에 유연합니다. 기본 제공업체는 Amazon Bedrock이며, 기본적으로 에이전트는 us-west-2 리전의 Claude Sonnet 모델을 사용합니다. 정확한 기본 모델 ID는 SDK 버전에 따라 달라질 수 있으므로 코드에 하드코딩하기보다 설치된 SDK 문서를 확인하는 것이 좋습니다.

지원 가능한 모델 경로는 다음과 같습니다.

도구 사용 및 스트리밍을 지원하는 Amazon Bedrock 모델
Anthropic API를 통한 Claude 제품군
Llama API를 통한 Llama 모델
로컬 개발용 Ollama
LiteLLM을 통한 OpenAI 등 기타 제공업체

실무에서는 다음 흐름이 유용합니다.

로컬에서는 Ollama 또는 개발용 모델로 빠르게 반복합니다.
도구 스키마와 프롬프트를 안정화합니다.
프로덕션에서는 Bedrock 또는 관리형 제공업체로 전환합니다.
에이전트 코드와 도구 코드는 최대한 그대로 유지합니다.

제공업체 전환은 보통 모델 객체 변경에 가깝고, 에이전트 루프나 도구 자체를 다시 작성하는 작업은 아닙니다.

도구 설계 체크리스트

Strands에서 도구는 에이전트가 외부 세계와 상호작용하는 인터페이스입니다. 도구는 다음 중 하나일 수 있습니다.

직접 작성한 Python 함수
커뮤니티 패키지에서 제공하는 도구
MCP 서버를 통해 노출된 도구
REST API를 감싼 래퍼 함수

도구를 작성할 때는 다음 기준을 적용하세요.

@tool
def search_orders(customer_id: str, limit: int = 10) -> dict:
    """
    Search recent orders for a customer.

    Args:
        customer_id: The customer identifier.
        limit: Maximum number of orders to return.
    """
    ...

권장 사항:

입력 파라미터를 작게 유지합니다.
반환값은 JSON 직렬화 가능한 구조로 유지합니다.
성공과 실패 응답의 형태를 일관되게 만듭니다.
외부 API 호출에는 timeout을 설정합니다.
인증 정보는 코드에 직접 넣지 말고 환경 변수나 시크릿 관리자를 사용합니다.
모델이 오해하지 않도록 독스트링에 도구의 목적과 제한을 적습니다.

다중 에이전트와 MCP 사용하기

단일 에이전트로도 많은 작업을 처리할 수 있지만, 실제 서비스에서는 역할 분리가 필요할 수 있습니다. Strands 1.0은 다중 에이전트 애플리케이션을 위한 기본 요소를 제공합니다.

대표적인 패턴은 다음과 같습니다.

Agent-as-Tool: 한 에이전트를 다른 에이전트가 호출 가능한 도구처럼 사용합니다.
Swarm 스타일 조정: 여러 에이전트가 하나의 문제를 함께 해결합니다.
A2A 프로토콜: Strands 에이전트가 다른 프레임워크로 만든 에이전트와 통신할 수 있습니다.

예를 들어 고객 지원 시스템에서는 다음처럼 역할을 나눌 수 있습니다.

라우터 에이전트: 사용자 요청을 분류
주문 조회 에이전트: 주문 API 호출
환불 정책 에이전트: 정책 문서 검색
응답 작성 에이전트: 최종 답변 정리

MCP도 Strands에서 중요한 통합 방식입니다. 모델 컨텍스트 프로토콜, MCP는 모델을 도구 및 데이터 소스에 연결하기 위한 개방형 표준입니다. Strands는 게시된 MCP 서버에 연결하고, 해당 서버의 도구를 에이전트에 전달할 수 있습니다.

이미 MCP 서버를 운영 중이라면 새 기능을 에이전트에 붙이는 가장 빠른 방법이 될 수 있습니다. 단, MCP 서버의 응답 안정성에 에이전트 품질이 직접 의존하므로 엔드포인트 테스트와 모의 응답 검증이 중요합니다.

Strands 에이전트 배포하기

Strands는 노트북이나 로컬 스크립트에서 시작해 프로덕션 환경으로 이동할 수 있도록 설계되었습니다. 에이전트는 일반 Python 또는 TypeScript 애플리케이션이므로 기존 배포 방식을 그대로 적용할 수 있습니다.

배포 대상 예시는 다음과 같습니다.

관리형 에이전트 런타임을 위한 Amazon Bedrock AgentCore
이벤트 기반 단기 작업을 위한 AWS Lambda
컨테이너화된 장기 실행 서비스를 위한 AWS Fargate 또는 Amazon EKS
컨테이너를 실행할 수 있는 일반 Docker 환경

배포 전에는 최소한 다음 항목을 확인하세요.

# 예시: 환경 변수 확인
echo $AWS_REGION
echo $MODEL_PROVIDER
echo $TOOL_API_BASE_URL

운영 환경에서는 다음을 분리하는 것이 좋습니다.

모델 설정
도구 API의 base URL
인증 토큰
timeout 및 retry 정책
로깅 레벨
관찰성 설정

AWS는 관찰성 훅도 문서화하고 있으므로, 운영 중에는 다음 정보를 추적해야 합니다.

모델이 선택한 도구
도구 호출 입력값
도구 응답 상태
실패한 외부 API
최종 응답 생성까지 걸린 시간

Apidog로 Strands 에이전트의 API 의존성 테스트하기

Strands는 에이전트를 구축하는 SDK입니다. 하지만 에이전트가 호출하는 API 자체를 검증해 주지는 않습니다. 실제 Strands 에이전트는 보통 두 종류의 HTTP 엔드포인트에 의존합니다.

모델 뒤에 있는 LLM 제공업체 API
@tool 함수 또는 MCP 서버 뒤에 있는 REST API 및 도구 API

이 엔드포인트가 불안정하면 에이전트는 모델 문제처럼 보이는 방식으로 실패할 수 있습니다. 실제 원인은 잘못된 상태 코드, 변경된 응답 필드, 인증 실패, timeout일 수 있습니다.

Apidog는 에이전트가 실제 API에 접근하기 전에 엔드포인트를 테스트하고 모의할 수 있는 작업 공간입니다.

실무에서 사용할 수 있는 패턴은 다음과 같습니다.

모델 또는 도구 엔드포인트 모의

개발 루프에서 매번 실제 모델 호출 비용을 쓰거나 rate limit에 걸리지 않도록 합니다. 관련 패턴은 Apidog로 AI 에이전트 테스트 하네스 구축 문서에서 확인할 수 있습니다.
도구 응답 형태 검증

도구가 잘못된 payload를 반환하면 프로덕션이 아니라 테스트 단계에서 발견해야 합니다. 필드, 타입, 상태 코드 검증은 API 단언 가이드를 참고하세요.
모의 API 구성

실제 서비스와 유사한 정상 응답, 오류 응답, 빈 결과, 인증 실패 케이스를 만들어 에이전트가 어떻게 반응하는지 테스트합니다. 자세한 내용은 모의 API를 참고하세요.
환경별 API 키 관리

개발, 스테이징, 프로덕션 에이전트가 서로 다른 백엔드에 안전하게 인증하도록 구성합니다. 인증 정보를 코드에 직접 넣지 않는 것이 핵심입니다.

예를 들어 Strands 도구가 다음 API에 의존한다고 가정합니다.

@tool
def get_invoice(invoice_id: str) -> dict:
    """Get invoice details by invoice_id."""
    ...

Apidog에서는 다음 케이스를 먼저 정의할 수 있습니다.

케이스	예상 상태	에이전트가 처리해야 할 동작
정상 invoice 조회	`200`	금액, 상태, 만기일을 사용자에게 요약
존재하지 않는 invoice	`404`	찾을 수 없다고 명확히 응답
인증 실패	`401`	내부 인증 문제로 안내하거나 재시도 중단
서버 오류	`500`	일시적 실패로 처리하고 안전하게 종료

분명히 말하면 Apidog는 에이전트 프레임워크가 아니며 오케스트레이션을 수행하지 않습니다. Strands가 에이전트의 두뇌라면, Apidog는 그 아래 API 배관을 검증하는 작업대입니다. Apidog를 다운로드해 도구 엔드포인트에 대한 모의를 빠르게 설정할 수 있습니다.

Strands Agents를 사용할 시점

Strands는 다음 상황에 잘 맞습니다.

모델의 계획 능력을 활용해 빠르게 에이전트를 만들고 싶을 때
AWS와 Bedrock을 이미 사용 중일 때
단일 에이전트로 시작해 나중에 다중 에이전트로 확장하고 싶을 때
MCP 도구를 별도 통합 코드 없이 사용하고 싶을 때
도구 목록과 프롬프트를 중심으로 에이전트를 반복 개선하고 싶을 때

반대로 다음 상황에서는 신중해야 합니다.

모든 분기가 사전에 정의되어야 할 때
감사 가능한 결정론적 실행 흐름이 필수일 때
모델이 제어 흐름을 선택하면 안 되는 규제 환경일 때
그래프 기반 워크플로우가 이미 명확하게 정의되어 있을 때

Strands에서도 훅과 다중 에이전트 구조로 제어를 추가할 수 있습니다. 하지만 기본 철학은 그래프 우선이 아니라 모델 중심입니다.

구현 전 체크리스트

Strands로 첫 에이전트를 만들기 전에 다음 항목을 정리하면 시행착오를 줄일 수 있습니다.

[ ] 에이전트가 해결할 작업을 한 문장으로 정의했는가?
[ ] 시스템 프롬프트에 역할, 제한, 출력 형식을 명시했는가?
[ ] 각 도구의 입력과 출력이 명확한가?
[ ] 도구 함수에 타입 힌트와 독스트링이 있는가?
[ ] 외부 API 호출에 timeout이 있는가?
[ ] 실패 응답 형태가 일관적인가?
[ ] 실제 API 대신 사용할 mock이 있는가?
[ ] 개발, 스테이징, 프로덕션 환경 변수가 분리되어 있는가?
[ ] 모델 호출과 도구 호출 로그를 추적할 수 있는가?

자주 묻는 질문

Strands Agents는 무료이며 오픈소스인가요?

네. Strands Agents는 GitHub에 소스가 공개된 Apache License 2.0 기반 오픈소스입니다. SDK 자체에는 라이선스 비용이 없습니다. 다만 모델 추론, Bedrock 사용, Lambda 실행, 컨테이너 인프라와 같은 클라우드 리소스 비용은 별도로 발생합니다.

Strands와 함께 Amazon Bedrock을 반드시 사용해야 하나요?

아니요. Bedrock이 기본 제공업체이지만 Strands는 Anthropic API, Llama API, 로컬 실행용 Ollama, LiteLLM을 통한 기타 제공업체도 지원합니다. 모델 객체를 변경하고 나머지 에이전트 코드와 도구는 그대로 유지하는 방식으로 전환할 수 있습니다.

Strands와 그래프 기반 프레임워크의 차이는 무엇인가요?

Strands는 모델 중심입니다. 프롬프트와 도구를 제공하면 모델이 다음 단계를 결정합니다. 그래프 기반 프레임워크는 제어 흐름을 노드와 엣지로 정의하도록 요구합니다. Strands는 빠른 구축과 변경에 유리하고, 그래프 기반 방식은 더 엄격하고 예측 가능한 실행에 유리합니다.

Strands 에이전트가 의존하는 API는 어떻게 테스트하나요?

에이전트와 독립적으로 테스트하는 것이 좋습니다. LLM 및 도구 엔드포인트를 모의하고, 응답 형태를 단언하며, CI에서 검사를 실행하세요. Apidog 같은 도구는 mock과 assertion을 처리할 수 있습니다. Apidog로 ChatGPT API 테스트하기 가이드는 인증, 스트리밍, 도구 호출 테스트와 같은 에이전트 백엔드에 직접 연결되는 내용을 다룹니다.

결론

Strands Agents는 에이전트 구축을 단순화합니다. 모델, 시스템 프롬프트, 도구를 정의하면 모델이 추론 루프를 실행합니다. 단일 에이전트에서 다중 에이전트로 확장할 수 있고, MCP 및 A2A를 지원하며, AWS 스택 또는 일반 컨테이너 환경으로 배포할 수 있습니다.

구현에서 중요한 부분은 에이전트 자체만이 아닙니다. 에이전트가 호출하는 API가 안정적이어야 합니다. 도구 엔드포인트를 모의하고, 응답 형태를 검증하고, 실패 케이스를 미리 테스트하면 모델 문제가 아닌 API 문제를 더 빨리 발견할 수 있습니다. 이 지점에서 Strands와 Apidog를 함께 사용하면 에이전트 개발 루프를 더 안전하게 만들 수 있습니다.

세마틱 커널이란 무엇인가? 마이크로소프트 AI 오케스트레이션용 SDK

Rihpig — Fri, 26 Jun 2026 08:21:43 +0000

Microsoft 스택에서 AI 기능을 추가해야 하지만 별도의 Python 서비스를 운영하고 싶지 않다면, Semantic Kernel은 현실적인 선택지입니다. Semantic Kernel은 기존 코드와 API를 대규모 언어 모델에 연결하는 Microsoft의 오픈소스 SDK이며, C#, Python, Java에서 사용할 수 있습니다. 이 글에서는 Semantic Kernel의 핵심 구조, 커널과 플러그인의 동작 방식, 그리고 OpenAPI 사양을 통해 REST API를 모델이 호출 가능한 도구로 바꾸는 방법을 구현 관점에서 정리합니다.

오늘 Apidog를 사용해 보세요

Semantic Kernel이란 무엇인가

Semantic Kernel은 Microsoft가 AI 에이전트를 구축하고 LLM을 애플리케이션 코드에 연결하기 위해 제공하는 경량 오픈소스 SDK입니다.

실무적으로는 다음 역할을 합니다.

애플리케이션 코드와 LLM 사이에 위치합니다.
모델이 사용할 수 있는 함수 목록을 제공합니다.
모델이 함수를 호출하면 실제 코드를 실행합니다.
실행 결과를 다시 모델에 전달합니다.

즉, 개발자는 일반적인 메서드나 API를 작성하고, Semantic Kernel은 이를 모델이 호출할 수 있는 도구로 노출합니다.

Semantic Kernel이 특히 유용한 이유는 세 가지입니다.

C#/.NET, Python, Java 공식 지원

Python 중심 에이전트 프레임워크와 달리 .NET 백엔드에서도 자연스럽게 사용할 수 있습니다.
모델 공급자에 덜 종속됨

OpenAI, Azure OpenAI 등 커넥터를 통해 모델을 연결합니다. 모델을 교체할 때 애플리케이션 전체를 다시 작성하기보다 설정을 변경하는 방식에 가깝습니다.
엔터프라이즈 환경을 고려한 구조

텔레메트리, 필터, 후크를 통해 AI 호출 흐름을 로깅하고 감사하거나 중간에 가로챌 수 있습니다.

커널, 플러그인, 함수 구조

Semantic Kernel의 핵심 객체는 Kernel입니다. AI 기능을 위한 종속성 주입 컨테이너처럼 생각하면 됩니다.

기본 흐름은 다음과 같습니다.

커널을 생성합니다.
LLM 커넥터를 등록합니다.
모델이 호출할 수 있는 플러그인을 등록합니다.
프롬프트를 실행합니다.
모델이 필요하다고 판단하면 플러그인의 함수를 호출합니다.
함수 실행 결과를 다시 모델에 전달합니다.

플러그인과 함수

플러그인은 모델에 노출할 함수들의 묶음입니다. 함수는 모델이 호출할 수 있는 단일 기능입니다.

Semantic Kernel에서 함수는 크게 두 종류입니다.

네이티브 함수

C# 메서드나 Python 함수처럼 실제 코드로 작성된 함수입니다. 어노테이션이나 설명을 통해 모델이 이해할 수 있게 만듭니다.
프롬프트 함수

텍스트 요약, 분류, 재작성처럼 모델 호출 자체를 템플릿화한 함수입니다.

C#에서 Semantic Kernel 시작하기

아래 예시는 커널을 만들고, OpenAI 채팅 모델을 등록한 뒤, LightsPlugin을 모델이 호출할 수 있도록 추가하는 기본 구조입니다.

var builder = Kernel.CreateBuilder();

builder.AddOpenAIChatCompletion(
    modelId: "gpt-4o",
    apiKey: apiKey
);

builder.Plugins.AddFromType<LightsPlugin>("Lights");

Kernel kernel = builder.Build();

var result = await kernel.InvokePromptAsync(
    "Turn the kitchen light blue"
);

이제 모델은 프롬프트를 해석하다가 조명 상태 변경이 필요하다고 판단하면 LightsPlugin 안의 함수를 호출할 수 있습니다.

예를 들어 플러그인은 다음과 같은 형태가 될 수 있습니다.

public class LightsPlugin
{
    [KernelFunction("change_light_state")]
    [Description("Changes the state or color of a light")]
    public string ChangeLightState(
        [Description("The name of the light")] string lightName,
        [Description("The target color")] string color
    )
    {
        // 실제 조명 API 호출 또는 내부 서비스 호출
        return $"{lightName} light changed to {color}";
    }
}

핵심은 함수명과 파라미터 설명입니다. 모델은 이 메타데이터를 보고 어떤 함수를 어떤 인자로 호출할지 결정합니다.

OpenAPI-투-플러그인 패턴

Semantic Kernel의 실무 활용에서 가장 중요한 기능 중 하나는 OpenAPI 사양을 플러그인으로 가져오는 기능입니다.

이미 REST API가 있고 OpenAPI 문서가 있다면, 별도의 래퍼 코드를 많이 작성하지 않아도 됩니다. Semantic Kernel이 OpenAPI 사양을 읽고 각 엔드포인트를 모델이 호출 가능한 함수로 변환합니다.

C#에서 OpenAPI 플러그인 가져오기

await kernel.ImportPluginFromOpenApiAsync(
    pluginName: "lights",
    uri: new Uri("https://example.com/v1/swagger.json"),
    executionParameters: new OpenApiFunctionExecutionParameters
    {
        EnablePayloadNamespacing = true
    }
);

Python에서는 add_plugin_from_openapi를 사용하고, Java에도 동등한 임포터가 있습니다.

Semantic Kernel은 내부적으로 다음 작업을 수행합니다.

OpenAPI 사양을 파싱합니다.
각 path와 operation을 함수로 변환합니다.
파라미터 이름, 타입, 설명, 스키마를 추출합니다.
해당 메타데이터를 모델에 전달합니다.
모델이 함수를 선택하면 HTTP 요청을 생성합니다.
인증 콜백을 적용하고 요청을 전송합니다.
응답을 다시 모델에 전달합니다.

Semantic Kernel은 OpenAPI 2.0 및 3.0을 지원하며, 가능한 경우 3.1 사양을 3.0으로 다운그레이드합니다.

모델이 잘 호출하는 OpenAPI 사양 작성법

OpenAPI 사양은 사람만 읽는 문서가 아닙니다. Semantic Kernel에서는 모델이 읽는 도구 설명이 됩니다.

따라서 사양 품질이 낮으면 모델의 함수 호출 품질도 떨어집니다.

다음 항목을 우선 점검하세요.

1. operationId를 명확하게 작성하기

좋지 않은 예:

operationId: update

더 나은 예:

operationId: updateKitchenLightColor

모델은 operationId를 보고 함수의 목적을 추론합니다. 짧고 모호한 이름보다 행동과 대상을 포함한 이름이 좋습니다.

2. 파라미터 설명 추가하기

parameters:
  - name: lightId
    in: path
    required: true
    description: The unique identifier of the light to update.
    schema:
      type: string
  - name: color
    in: query
    required: true
    description: The target color name, such as blue, red, or warm_white.
    schema:
      type: string

설명이 없으면 모델은 인자를 추측해야 합니다.

3. 가능한 경우 enum 사용하기

느슨한 문자열보다 enum이 더 안전합니다.

schema:
  type: string
  enum:
    - blue
    - red
    - warm_white
    - cool_white

4. 엔드포인트 수를 과도하게 늘리지 않기

모델에 너무 많은 도구를 한 번에 노출하면 선택 오류가 늘어날 수 있습니다. 에이전트가 실제로 필요한 API만 플러그인으로 가져오는 편이 좋습니다.

에이전트 및 플래닝

Semantic Kernel은 초기에는 목표를 단계별로 분해하는 명시적 플래너 중심으로 시작했습니다. 이후 최신 모델의 함수 호출 성능이 좋아지면서, 프레임워크도 모델이 직접 어떤 함수를 어떤 순서로 호출할지 결정하는 방식으로 이동했습니다.

현재 Semantic Kernel은 다음 기능도 제공합니다.

에이전트 패턴
다중 에이전트 패턴
세션 기반 상태 관리
에이전트 루프
외부 도구 연결을 위한 MCP 지원

다른 에이전트 SDK와 비교하면 다음과 같습니다.

프레임워크	주요 언어	오케스트레이션 모델	최적의 활용처
Semantic Kernel	C#/.NET, Python, Java	함수 호출 + 에이전트	.NET 및 엔터프라이즈 팀
LangGraph	Python, JS	명시적 상태 그래프	복잡하고 분기되는 에이전트 흐름
Google ADK	Python	에이전트 + 도구 모델	Google Cloud 및 Gemini 스택
OpenAI Agents SDK	Python, JS	에이전트 + 핸드오프	OpenAI 중심 앱

절대적으로 더 좋은 프레임워크는 없습니다. 선택 기준은 다음입니다.

현재 사용하는 언어
모델 공급자
실행 흐름을 얼마나 명시적으로 제어해야 하는지
기존 API와 OpenAPI 사양의 품질
엔터프라이즈 감사 및 로깅 요구사항

Semantic Kernel과 Microsoft Agent Framework의 관계

Microsoft는 Microsoft Agent Framework, 즉 MAF를 도입했습니다. 문서에서는 이를 Semantic Kernel과 AutoGen의 직접적인 후속작으로 설명하며, 동일한 팀이 구축했다고 설명합니다.

MAF는 다음 방향을 가집니다.

AutoGen의 에이전트 추상화
Semantic Kernel의 엔터프라이즈 기능
다중 에이전트 오케스트레이션을 위한 그래프 기반 워크플로우

실무적으로는 다음처럼 판단하면 됩니다.

이미 Semantic Kernel로 만든 애플리케이션이 있다면 계속 사용해도 됩니다. SK는 안정적이고 지원됩니다.
새로운 에이전트 프로젝트라면 Microsoft Agent Framework 문서를 함께 검토하세요.
OpenAPI 사양을 통해 REST API를 에이전트 도구로 노출하는 패턴은 두 프레임워크 모두에서 중요한 방향입니다.

즉, Semantic Kernel은 여전히 프로덕션에서 사용할 수 있는 안정적인 선택지입니다. 다만 Microsoft의 최신 에이전트 투자는 MAF 쪽으로 이동하고 있다는 점은 고려해야 합니다.

Semantic Kernel을 사용해야 할 때

다음 조건에 해당하면 Semantic Kernel을 검토할 만합니다.

.NET 또는 Java 기반 백엔드에서 AI 오케스트레이션을 구현해야 한다.
Python 사이드카 서비스를 추가하고 싶지 않다.
기존 REST API를 OpenAPI 사양으로 관리하고 있다.
모델이 REST API를 도구처럼 호출하게 만들고 싶다.
텔레메트리, 필터, 후크, 감사 로그가 필요하다.
OpenAI, Azure OpenAI 등 모델 공급자를 교체할 가능성이 있다.

반대로 다음 경우에는 다른 선택지도 검토하세요.

팀이 Python 중심이고 최신 다중 에이전트 기능이 최우선이다.
복잡한 상태 그래프와 분기 흐름을 명시적으로 제어해야 한다.
Microsoft의 최신 에이전트 방향을 바로 따라가고 싶다.

이 경우 MAF 또는 그래프 우선 에이전트 프레임워크가 더 적합할 수 있습니다.

Semantic Kernel 에이전트 뒤의 API 테스트

Semantic Kernel은 API를 대체하지 않습니다. API를 호출합니다.

따라서 에이전트 품질은 다음 두 가지에 크게 의존합니다.

LLM 엔드포인트가 안정적으로 동작하는가
OpenAPI 플러그인으로 가져온 REST API가 정확하게 설계되고 테스트되었는가

여기서 Apidog 같은 API 도구가 유용합니다.

1. OpenAPI 사양을 먼저 검증하기

Semantic Kernel은 OpenAPI의 각 operation을 함수로 바꿉니다. 따라서 사양이 모호하면 모델 호출도 모호해집니다.

가져오기 전에 다음을 확인하세요.

모든 엔드포인트가 실제로 호출 가능한가
요청 파라미터 설명이 충분한가
응답이 스키마와 일치하는가
인증 방식이 명확한가
불필요한 엔드포인트가 플러그인에 포함되어 있지 않은가

2. 개발 중에는 Mock API 사용하기

백엔드가 아직 완성되지 않았거나 LLM 호출 비용을 줄이고 싶다면 Mock API를 사용할 수 있습니다.

예를 들어 아직 구현되지 않은 조명 API를 다음처럼 모의할 수 있습니다.

{
  "lightId": "kitchen",
  "state": "on",
  "color": "blue"
}

관련 내용은 모의 API와 API 호출 모의 방법을 참고할 수 있습니다.

3. 응답 형태를 단언하기

에이전트는 API 응답 구조에 민감합니다. 백엔드 응답 필드가 바뀌면 모델의 후속 추론이 달라질 수 있습니다.

API 단언을 사용해 다음을 확인하세요.

필수 필드가 존재하는가
타입이 스키마와 일치하는가
에러 응답 형식이 일관적인가
모델이 기대하는 데이터 구조를 유지하는가

4. 환경별 키 분리하기

LLM API 키와 내부 API 자격 증명을 코드에 하드코딩하지 마세요.

최소한 다음 환경을 분리하는 것이 좋습니다.

개발
스테이징
프로덕션

Semantic Kernel 설정에서도 환경별로 모델 엔드포인트, API 키, 플러그인 URL을 분리해 관리하는 것이 안전합니다.

자세한 하네스 구성은 Apidog로 에이전트의 도구 호출 테스트하기에서 확인할 수 있습니다.

자주 묻는 질문

Semantic Kernel은 무료이며 오픈소스인가요?

네. Semantic Kernel은 Microsoft가 GitHub에 공개한 오픈소스 SDK입니다. C#/.NET, Python, Java SDK를 제공합니다.

Semantic Kernel 자체는 무료로 사용할 수 있지만, OpenAI, Azure OpenAI 같은 모델 사용 비용은 별도로 발생합니다.

Semantic Kernel은 어떤 언어를 지원하나요?

C#/.NET, Python, Java를 지원합니다. 세 언어 모두 1.0+ 안정성을 보장합니다.

C# SDK가 가장 성숙하지만, Python과 Java SDK도 커널, 플러그인, OpenAPI 가져오기 같은 핵심 기능을 제공합니다.

Semantic Kernel은 OpenAPI 사양을 어떻게 사용하나요?

C#에서는 ImportPluginFromOpenApiAsync, Python에서는 add_plugin_from_openapi를 사용해 OpenAPI 사양을 가져올 수 있습니다.

Semantic Kernel은 사양을 파싱하고 각 operation을 호출 가능한 함수로 변환합니다. 모델은 operation 설명, 파라미터 설명, 스키마 정보를 보고 어떤 함수를 호출할지 결정합니다.

따라서 사양을 먼저 검증하는 것이 중요합니다. Apidog를 사용하면 OpenAPI 사양 검증과 실시간 엔드포인트 테스트를 함께 수행할 수 있습니다.

Semantic Kernel을 사용해야 하나요, 아니면 Microsoft Agent Framework를 사용해야 하나요?

이미 Semantic Kernel 애플리케이션을 운영 중이라면 계속 사용해도 됩니다. Semantic Kernel은 안정적이고 지원됩니다.

새 프로젝트라면 Microsoft Agent Framework 문서를 함께 검토하는 것이 좋습니다. Microsoft는 MAF를 Semantic Kernel과 AutoGen의 후속 방향으로 제시하고 있습니다.

어떤 프레임워크를 선택하든, 에이전트가 호출하는 API를 테스트해야 합니다. 관련 예시는 Apidog로 ChatGPT API를 테스트하는 방법을 참고하세요.

마무리

Semantic Kernel은 Microsoft 스택에서 AI 기능을 구현하는 실용적인 방법입니다. 커널은 모델과 코드를 연결하고, 플러그인은 모델이 호출할 수 있는 기능을 제공하며, OpenAPI 가져오기는 기존 REST API를 에이전트 도구로 노출합니다.

이미 .NET, Java, 또는 엔터프라이즈 API 기반 시스템을 운영하고 있다면 Semantic Kernel은 여전히 안정적인 선택입니다. 다만 새 프로젝트에서는 Microsoft Agent Framework의 방향도 함께 확인하는 것이 좋습니다.

무엇을 선택하든 에이전트가 호출하는 API 계약은 견고해야 합니다. 에이전트에 연결하기 전에 사양을 설계하고, Mock API로 검증하고, 응답을 테스트하려면 Apidog를 다운로드해 API 계약을 먼저 정리하세요.

PydanticAI란 무엇인가? 타입 안전 파이썬 에이전트 프레임워크 완벽 가이드

Rihpig — Fri, 26 Jun 2026 08:19:38 +0000

LLM 기능을 프로덕션에 배포한 뒤 잘못된 형식의 JSON 때문에 파이프라인이 깨진 적이 있다면, PydanticAI를 검토할 만합니다. Pydantic 팀이 만든 Python 에이전트 프레임워크로, 에이전트 출력과 도구 호출을 Pydantic 모델로 검증하는 데 초점을 둡니다. 이 글에서는 PydanticAI의 핵심 개념, 기본 구현 방식, 그리고 LangGraph 같은 Python 에이전트 프레임워크와의 차이를 정리합니다.

오늘 Apidog를 사용해 보세요

PydanticAI란 무엇인가

PydanticAI는 Python용 오픈 소스, 공급업체 독립적인 에이전트 프레임워크입니다. Pydantic Validation 및 Pydantic Logfire를 개발하는 팀이 유지 관리하며, 목표는 에이전트 개발에 “FastAPI 같은” 타입 안전성과 개발 경험을 제공하는 것입니다.

PydanticAI에서는 다음 세 가지를 명확히 정의합니다.

에이전트가 따라야 할 지침
에이전트가 호출할 수 있는 도구
에이전트가 반환해야 하는 출력 구조

프레임워크는 모델 호출을 실행하고, 결과를 Pydantic 모델로 검증합니다. 모델이 유효하지 않은 값을 반환하면 검증 오류를 기반으로 재시도합니다.

설치는 다음 중 하나로 시작할 수 있습니다.

pip install pydantic-ai

또는:

uv add pydantic-ai

PydanticAI는 여러 베타 버전을 거쳐 2026년 6월 23일 안정적인 v2.0.0 릴리스에 도달했습니다. v2는 도구, 훅, 지침, 모델 설정을 재사용 가능한 단위로 구성하는 하네스 우선 설계를 지향합니다.

왜 타입 안전성이 에이전트에게 중요한가

LLM은 비결정적입니다. 같은 프롬프트를 두 번 실행해도 서로 다른 형태의 응답을 받을 수 있습니다. 채팅 UI에서는 큰 문제가 아닐 수 있지만, 모델 출력을 다음과 같은 코드에 연결하면 문제가 됩니다.

데이터베이스 쓰기
REST API 호출
결제 또는 청구 계산
사용자 권한 판단
자동화 워크플로 실행

대표적인 실패 사례는 다음과 같습니다.

{
  "category": "billing",
  "priority": "high"
}

코드는 priority를 정수로 기대하지만, 모델은 문자열을 반환할 수 있습니다. 또는 필드를 누락하거나 JSON 앞뒤에 설명 문장을 붙일 수도 있습니다.

PydanticAI는 이 문제를 출력 계약으로 해결합니다. 출력 타입을 Pydantic 모델로 정의하면, 에이전트 결과는 해당 모델과 일치해야 합니다. 유효하지 않으면 프레임워크가 LLM에 오류를 전달하고 다시 생성하도록 요청합니다.

즉, 하위 코드는 문자열을 파싱하는 대신 검증된 Python 객체를 받습니다.

도구 호출도 동일합니다. 모델이 도구를 호출할 때 PydanticAI는 함수의 타입 힌트를 기준으로 인수를 검증합니다. 잘못된 인수는 비즈니스 로직까지 도달하지 않습니다.

핵심 개념

PydanticAI로 에이전트를 만들 때 주로 다루는 개념은 다음 다섯 가지입니다.

에이전트
타입이 지정된 출력
도구
종속성
모델 공급업체 및 스트리밍

1. 에이전트 만들기

Agent 클래스가 기본 진입점입니다. 모델 식별자와 지침을 전달해 에이전트를 생성합니다.

from pydantic_ai import Agent

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    instructions='Be concise, reply with one sentence.',
)

result = agent.run_sync('Where does "hello world" come from?')
print(result.output)

모델을 바꾸려면 모델 문자열만 변경하면 됩니다.

agent = Agent(
    'openai:gpt-4o',
    instructions='Be concise, reply with one sentence.',
)

이 방식은 코드 구조를 공급업체에 강하게 묶지 않도록 해줍니다.

2. 타입이 지정된 출력 사용하기

구조화된 응답이 필요하면 Pydantic 모델을 정의하고 output_type으로 전달합니다.

from pydantic import BaseModel
from pydantic_ai import Agent

class SupportTicket(BaseModel):
    category: str
    priority: int
    summary: str

agent = Agent(
    'openai:gpt-4o',
    output_type=SupportTicket,
)

result = agent.run_sync('My payment failed three times today.')

ticket = result.output

print(ticket.category)
print(ticket.priority)
print(ticket.summary)

이제 result.output은 단순 문자열이 아니라 SupportTicket 객체입니다.

예를 들어 모델이 다음처럼 반환하면:

{
  "category": "payment",
  "priority": "urgent",
  "summary": "Payment failed three times today."
}

priority가 int가 아니므로 검증이 실패합니다. PydanticAI는 오류를 모델에 전달하고 올바른 구조로 다시 생성하도록 요청합니다.

실무에서는 출력 모델을 더 구체적으로 만들 수 있습니다.

from typing import Literal
from pydantic import BaseModel, Field

class SupportTicket(BaseModel):
    category: Literal['billing', 'technical', 'account']
    priority: int = Field(ge=1, le=5)
    summary: str

이렇게 하면 다음 조건을 강제할 수 있습니다.

category는 허용된 값 중 하나여야 함
priority는 1부터 5 사이의 정수여야 함
summary는 반드시 있어야 함

3. 도구 등록하기

도구는 에이전트가 외부 시스템과 상호작용할 수 있게 합니다.

예:

데이터베이스 조회
REST API 호출
내부 서비스 호출
계산 실행
사용자 정보 조회

PydanticAI에서는 @agent.tool 데코레이터로 도구를 등록합니다.

from pydantic_ai import Agent, RunContext

agent = Agent('openai:gpt-4o', deps_type=str)

@agent.tool
async def get_user_balance(ctx: RunContext[str], account_id: str) -> float:
    """Return the current balance for an account."""
    return await lookup_balance(ctx.deps, account_id)

여기서 중요한 점은 다음과 같습니다.

account_id: str 타입 힌트가 도구 스키마에 사용됩니다.
모델이 도구를 호출할 때 인수가 검증됩니다.
ctx.deps를 통해 외부 종속성을 사용할 수 있습니다.

예를 들어 실제 구현에서는 ctx.deps에 API 기본 URL, 데이터베이스 클라이언트, 인증 토큰 등을 넣을 수 있습니다.

4. 종속성 주입 사용하기

프로덕션 에이전트는 보통 외부 리소스가 필요합니다.

HTTP 클라이언트
데이터베이스 연결
현재 사용자 정보
API 키
설정 객체

PydanticAI는 deps_type과 RunContext로 종속성 주입을 처리합니다.

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class AppDeps:
    api_base_url: str
    api_key: str

agent = Agent(
    'openai:gpt-4o',
    deps_type=AppDeps,
)

@agent.tool
async def get_order_status(ctx: RunContext[AppDeps], order_id: str) -> str:
    """Return the status of an order."""
    # 실제 구현에서는 ctx.deps.api_base_url 및 ctx.deps.api_key 사용
    return await fetch_order_status(
        base_url=ctx.deps.api_base_url,
        api_key=ctx.deps.api_key,
        order_id=order_id,
    )

deps = AppDeps(
    api_base_url='https://api.example.com',
    api_key='secret',
)

result = agent.run_sync(
    'Check order A123.',
    deps=deps,
)

테스트에서는 실제 종속성을 가짜 객체로 교체할 수 있습니다.

test_deps = AppDeps(
    api_base_url='https://mock.example.com',
    api_key='test-key',
)

이 구조는 에이전트 로직과 외부 시스템 연결을 분리하는 데 유용합니다.

5. 모델 공급업체와 스트리밍

PydanticAI는 여러 모델 공급업체를 지원합니다.

OpenAI
Anthropic
Gemini
DeepSeek
Grok
Cohere
Mistral
Perplexity
Azure AI Foundry
Amazon Bedrock
자체 호스팅 모델

공급업체 전환은 일반적으로 모델 문자열 변경으로 처리합니다.

Agent('openai:gpt-4o')

Agent('anthropic:claude-sonnet-4-6')

또한 PydanticAI는 데이터가 도착하는 대로 구조화된 출력을 스트리밍할 수 있습니다. 이를 통해 부분 결과를 렌더링하면서도 타입 검증 흐름을 유지할 수 있습니다.

Pydantic Logfire와의 연계도 중요합니다. 실행 추적, 디버깅, 비용 추적 같은 관찰 가능성 기능을 함께 사용할 수 있습니다.

PydanticAI와 다른 Python 에이전트 프레임워크 비교

하나의 “최고” 프레임워크가 있는 것은 아닙니다. 각 프레임워크는 다른 문제를 최적화합니다.

프레임워크	핵심 강점	적합한 경우
PydanticAI	타입 안전하고 유효성이 검증된 출력 및 도구 인수	프로덕션 신뢰성과 타입 지정 데이터 흐름이 중요할 때
LangGraph	명시적인 상태 저장 그래프 및 제어 흐름	장기 실행, 분기, 다단계 워크플로가 필요할 때
Google ADK	Google 생태계 내 다중 에이전트 오케스트레이션	Gemini 및 Vertex AI 통합이 중요할 때
OpenAI Agents SDK	핸드오프 기능이 있는 OpenAI 통합	OpenAI 우선 스택에서 빠르게 구축할 때

PydanticAI의 강점은 검증 계층입니다. 에이전트 출력이 다른 시스템으로 전달된다면, 출력이 Pydantic 모델과 일치한다는 보장이 런타임 오류를 줄여줍니다.

LangGraph는 상태 머신과 복잡한 제어 흐름에 더 적합합니다. 여러 단계, 분기, 재시도, 상태 전이가 명확한 워크플로라면 LangGraph가 더 직접적인 제어 수단을 제공합니다.

OpenAI Agents SDK는 OpenAI 중심 스택에서 빠르게 시작하기 좋습니다. 에이전트 핸드오프나 MCP 서버 지원 같은 기능이 필요할 때 자연스러운 선택입니다.

혼합해서 사용할 수도 있습니다. 예를 들어 LangGraph로 전체 워크플로를 제어하고, 특정 노드에서 PydanticAI를 사용해 검증된 구조화 출력을 생성할 수 있습니다.

PydanticAI를 사용해야 하는 경우

다음 조건에 해당하면 PydanticAI가 잘 맞습니다.

에이전트 출력이 채팅 UI가 아니라 실제 코드로 들어간다.
출력 형태가 정확해야 한다.
Pydantic 모델로 응답 구조를 강제하고 싶다.
IDE와 타입 체커가 에이전트 결과를 이해해야 한다.
이미 코드베이스에서 Pydantic 또는 FastAPI를 사용하고 있다.
모델 공급업체를 바꿀 가능성이 있다.
Logfire 기반 관찰 가능성이 필요하다.

반대로 다음 경우에는 다른 도구가 더 적합할 수 있습니다.

복잡한 상태 머신이 필요하다.
워크플로가 여러 분기와 장기 실행 상태를 가진다.
에이전트 간 오케스트레이션이 핵심 요구사항이다.
그래프 기반 제어 흐름이 더 중요하다.

에이전트 뒤의 API 테스트 및 모킹

PydanticAI 에이전트는 의존하는 API만큼만 안정적입니다. 모든 실행은 LLM 공급업체를 호출하며, 대부분의 유용한 에이전트는 내부 REST API나 서드파티 도구도 호출합니다.

이 지점에서 다음 문제가 발생할 수 있습니다.

API 응답 형태가 예상과 다름
필수 필드 누락
인증 실패
스트리밍 형식 불일치
공급업체 속도 제한
테스트 중 불필요한 토큰 비용 발생

PydanticAI는 모델의 출력은 검증할 수 있지만, 여러분이 호출하는 업스트림 API가 올바른 응답을 반환하는지는 직접 보장하지 않습니다.

이때 Apidog를 사용할 수 있습니다. Apidog는 에이전트 프레임워크가 아니라, 에이전트가 통신하는 API를 테스트하고 모의하는 API 플랫폼입니다.

실무에서 사용할 수 있는 방식은 다음과 같습니다.

1. LLM 또는 도구 엔드포인트 모의하기

개발 중에는 실제 공급업체 대신 결정적인 응답을 반환하는 모의 API를 사용할 수 있습니다.

이렇게 하면 다음을 줄일 수 있습니다.

반복 테스트 중 토큰 비용
공급업체 rate limit 문제
비결정적 응답으로 인한 테스트 불안정성

2. REST 응답 형태 단언하기

@agent.tool 함수가 REST API를 호출한다면, 먼저 API 응답 구조를 검증해야 합니다.

API 단언을 사용하면 다음을 API 계층에서 확인할 수 있습니다.

필수 필드 존재 여부
응답 타입
상태 코드
중첩 객체 구조
에러 응답 형식

이렇게 하면 에이전트 실행 중간이 아니라 API 테스트 단계에서 문제를 잡을 수 있습니다.

3. 환경별 키와 기본 URL 관리하기

로컬, 스테이징, CI 환경에서 서로 다른 API 키와 기본 URL을 사용해야 한다면 Apidog 환경을 분리해 관리할 수 있습니다.

예:

Local
Staging
Production
CI Mock

코드를 바꾸지 않고 환경만 전환하면 테스트 대상도 바꿀 수 있습니다.

4. LLM 엔드포인트 직접 검증하기

HTTP로 LLM 공급업체를 직접 호출한다면, 에이전트에 연결하기 전에 ChatGPT API 테스트를 통해 다음을 확인할 수 있습니다.

인증 헤더
요청 본문
스트리밍 응답
도구 호출 형식
에러 응답

Apidog는 PydanticAI의 대안이 아닙니다. PydanticAI가 에이전트와 타입 검증을 담당한다면, Apidog는 에이전트가 호출하는 API 표면을 테스트하고 모의하는 역할을 합니다.

시작하려면 Apidog를 다운로드하고, 먼저 에이전트 도구 엔드포인트 하나를 모의해보세요.

자주 묻는 질문

PydanticAI는 무료이며 오픈 소스인가요?

네. PydanticAI는 오픈 소스이며 PyPI에서 설치할 수 있습니다.

pip install pydantic-ai

또는:

uv add pydantic-ai

다만 사용하는 LLM 공급업체의 API 비용은 별도로 발생합니다. 개발 중 비용을 줄이려면 매번 실제 모델을 호출하는 대신 테스트 중 API 응답을 모의할 수 있습니다.

PydanticAI는 어떤 모델과 작동하나요?

공급업체 독립적으로 설계되어 있습니다. 문서에는 OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity가 포함되어 있으며, Azure AI Foundry, Amazon Bedrock, 자체 호스팅 모델도 지원 대상으로 나열되어 있습니다.

모델은 Agent 생성자에 문자열로 지정합니다.

Agent('anthropic:claude-sonnet-4-6')

또는:

Agent('openai:gpt-4o')

전환은 일반적으로 이 문자열을 바꾸는 방식으로 처리합니다.

PydanticAI는 LangChain 또는 LangGraph와 어떻게 다른가요?

PydanticAI는 타입 안전성과 검증된 구조화 출력에 집중합니다. Pydantic 모델을 기반으로 출력과 도구 인수를 검증합니다.

LangGraph는 다단계, 분기, 장기 실행 워크플로를 위한 명시적인 상태 저장 그래프에 집중합니다.

정리하면 다음과 같습니다.

출력 형태 보장과 타입 지정 데이터 흐름이 중요하면 PydanticAI
복잡한 상태 머신과 그래프 기반 제어가 중요하면 LangGraph

사용하려면 Pydantic을 알아야 하나요?

기본 개념을 알면 좋습니다. PydanticAI에서는 BaseModel을 상속한 클래스로 데이터 형태를 정의합니다.

from pydantic import BaseModel

class Answer(BaseModel):
    title: str
    confidence: float

FastAPI를 사용해본 적이 있거나 API 테스트용 Python을 다뤄본 적이 있다면 익숙한 방식입니다.

결론

PydanticAI는 에이전트 개발에서 자주 발생하는 문제를 직접 다룹니다. 모델 출력과 도구 호출이 선언한 타입과 일치하는지 검증하고, 유효하지 않으면 재시도합니다.

다음이 중요하다면 PydanticAI를 선택하세요.

프로덕션 신뢰성
구조화된 출력
Pydantic 기반 검증
타입 체커와 IDE 지원
공급업체 유연성

반대로 복잡한 그래프 오케스트레이션이 핵심이라면 LangGraph 같은 프레임워크가 더 적합할 수 있습니다.

어떤 에이전트 프레임워크를 사용하든, 에이전트 아래의 API는 별도로 테스트해야 합니다. LLM 및 도구 엔드포인트를 모의하고, 응답 형태를 단언하며, Apidog에서 환경별 키를 관리하면 에이전트를 더 검증된 기반 위에서 실행할 수 있습니다.

APIDOG 6월 업데이트: AI 기반 CLI 워크플로우, 가져오기 개선, OAuth 2.0 자동 새로 고침

Rihpig — Fri, 26 Jun 2026 06:18:42 +0000

6월 업데이트에서는 AI 기반 CLI 작업, 더 깔끔한 가져오기, OAuth 2.0 자동 토큰 갱신, 테스트/구성 워크플로우 개선을 통해 일상적인 API 작업을 더 쉽게 자동화하고 안정적으로 실행할 수 있도록 했습니다.

오늘 Apidog 사용해 보기

이번 릴리스의 핵심은 API 팀이 반복적으로 시간을 쓰는 지점을 줄이는 것입니다.

AI 에이전트가 실제 Apidog 프로젝트 리소스를 안전하게 다루도록 지원
Postman/OpenAPI/Swagger 가져오기 후 수동 정리 감소
OAuth 2.0 보호 API 요청 중 토큰 만료로 인한 중단 최소화
테스트 스위트, 예약 작업, 웹 앱 요청 헤더 구성 개선

새로운 업데이트

Apidog CLI: AI 기반 API 워크플로우 실행 레이어

Apidog CLI는 AI 기반 API 워크플로우의 실행 레이어 역할을 강화하고 있습니다.

목표는 사용자가 모든 CLI 명령을 직접 익히는 것이 아니라, AI 에이전트가 Apidog 프로젝트 리소스를 구조화된 방식으로 읽고, 변경하고, 검증하고, 내보내고, 테스트할 수 있도록 하는 것입니다.

이번 업데이트에서 Apidog CLI는 다음 작업을 지원합니다.

Apidog 프로젝트 리소스에서 동작하는 AI 에이전트 실행 레이어로 활용
테스트 케이스 실행
시나리오 케이스에서 엔드포인트, 테스트 케이스, 다른 시나리오 참조
네이티브 형식 및 OpenAPI 형식 내보내기 시 더 세분화된 범위 제어

예를 들어 AI 에이전트가 API 테스트를 생성하거나 기존 시나리오를 수정하는 흐름에서는 다음과 같은 패턴을 만들 수 있습니다.

1. AI 에이전트가 Apidog 프로젝트 리소스를 읽음
2. 필요한 엔드포인트 또는 테스트 케이스를 참조
3. 변경 사항 또는 테스트 시나리오를 생성
4. CLI로 실행 또는 검증
5. 필요한 범위만 내보내기

Apidog Skills와 함께 사용하면 CLI는 AI 에이전트에 더 명확한 작업 지침과 안전한 실행 경계를 제공합니다. 에이전트는 Apidog 리소스 사용 방식을 더 잘 이해하고, 생성한 변경 사항을 다시 작성하기 전에 검증하며, 추측을 줄인 상태로 API 작업을 완료할 수 있습니다.

CLI는 자연어 AI 지침과 구조화된 Apidog 프로젝트 작업 사이의 브리지 역할을 합니다.

가져오기 및 내보내기 개선

이번 릴리스는 Postman에서 데이터를 이전하거나 OpenAPI/Swagger 기반으로 API 정의를 관리하는 팀에 유용한 가져오기/내보내기 개선을 포함합니다.

Postman API 가져오기 후 정리 감소

Postman API를 통해 데이터를 가져올 때 Apidog는 이제 변수 이름의 공백을 제거할 수 있습니다.

예를 들어 다음과 같은 변수 이름은 가져오기 후 사용하기 불편할 수 있습니다.

base url
access token
user id

공백 제거를 적용하면 다운스트림 요청, 스크립트, 환경 변수 참조에서 더 일관된 이름을 사용할 수 있습니다.

baseurl
accesstoken
userid

또한 Postman API를 통해 워크스페이스를 가져올 때, Apidog는 워크스페이스 생성자를 기반으로 혼란스러운 "내 워크스페이스" 이름을 변경할 수 있습니다. 여러 워크스페이스를 가져오는 팀은 가져온 데이터의 출처를 더 쉽게 식별하고 정리할 수 있습니다.

OpenAPI 및 Swagger 가져오기/내보내기 개선

OpenAPI 및 Swagger 가져오기/내보내기는 객체 유형 매개변수와 참조 유형 매개변수를 지원합니다.

즉, 더 복잡한 API 사양 구조를 가져오거나 내보낼 때 수동으로 보정해야 하는 경우가 줄어듭니다.

이전	현재
가져온 변수에 수동 정리가 필요할 수 있었습니다. 여러 가져온 워크스페이스에 혼란스러운 이름이 있을 수 있었습니다. 복잡한 OpenAPI 매개변수는 가져오기/내보내기 후 추가 조정이 필요할 수 있었습니다.	Postman API 가져오기는 변수 이름에서 공백을 제거할 수 있습니다. 모호한 워크스페이스 이름은 더 쉬운 식별을 위해 변경될 수 있습니다. OpenAPI/Swagger 가져오기/내보내기는 객체 유형 및 참조 유형 매개변수를 지원합니다.

OAuth 2.0: 자동 토큰 갱신 지원

OAuth 2.0 인증은 이제 자동 토큰 갱신을 지원합니다.

액세스 토큰이 만료되었거나 만료가 임박한 경우, Apidog는 자동으로 토큰을 갱신할 수 있습니다. 따라서 사용자는 요청 중간에 다시 인증하거나 새 토큰을 복사해 붙여 넣을 필요가 줄어듭니다.

OAuth로 보호된 API를 반복적으로 디버깅하는 경우 특히 유용합니다.

기존 흐름:
요청 실행 → 토큰 만료 → 요청 실패 → 재인증 → 토큰 복사 → 다시 요청

개선된 흐름:
요청 실행 → 토큰 만료 감지 → 자동 갱신 → 요청 계속

API 디버깅, 테스트, 반복적인 요청 검증 중 인증으로 인한 중단을 줄일 수 있습니다.

사용자 피드백 기반 개선 사항

MCP 클라이언트 호환성 개선

Apidog는 MCP 클라이언트 호환성을 개선했으며, 이제 비표준 스키마를 더 안정적으로 구문 분석할 수 있습니다.

이는 MCP 서버 또는 도구의 스키마 출력이 예상 형식을 엄격히 따르지 않는 경우에 유용합니다. 스키마 차이로 초기에 실패하는 대신, Apidog는 더 많은 실제 MCP 응답을 처리하고 도구 통합 및 디버깅 성공률을 높일 수 있습니다.

테스트 스위트에서 이름으로 정적 단계 검색

이제 테스트 스위트에 정적 단계를 추가할 때 이름으로 검색할 수 있습니다.

엔드포인트, 테스트 케이스, 시나리오가 많은 프로젝트에서는 긴 목록을 직접 스크롤하는 대신 이름으로 필요한 단계를 빠르게 찾을 수 있습니다.

예시 워크플로우:
1. 테스트 스위트 열기
2. 정적 단계 추가 선택
3. 단계 이름 검색
4. 필요한 엔드포인트/테스트 케이스/시나리오 추가

예약된 작업에 "8시간마다" 옵션 추가

예약된 작업에 "8시간마다" 실행 옵션이 추가되었습니다.

다음과 같은 워크플로우에 사용할 수 있습니다.

반복적인 자동 테스트
모니터링 성격의 API 검사
주기적인 API 유효성 검증
하루 3회 실행이 필요한 회귀 테스트

Apidog 웹 앱: 자동 생성 헤더 구성 지원

Apidog 웹 앱은 이제 자동 생성 헤더 구성을 지원합니다.

웹 앱 사용자는 생성된 요청 헤더를 팀 또는 프로젝트 요구 사항에 맞게 조정할 수 있습니다. 브라우저 기반 워크플로우에서도 요청 동작을 더 세밀하게 제어할 수 있습니다.

버그 수정 및 사소한 개선 사항

이번 달에는 다음 수정 사항과 개선 사항도 포함되었습니다.

자식 브랜치에서 대규모 테스트 시나리오를 선택할 때 성능이 향상되어 타임아웃 오류 가능성이 줄어듭니다.
스프린트 브랜치 및 일반 브랜치 목록에서 브랜치 ID 표시 및 복사를 지원합니다.
macOS가 인트라넷 요청을 보낼 수 없을 때 더 사용자 친화적인 메시지가 표시됩니다.
새 모듈로 Apidog 데이터를 다시 가져올 때 서비스 기본 URL이 가져와지지 않고 엔드포인트가 지정된 서비스에 바인딩되지 않던 문제를 수정했습니다.
요청 헤더에 추가되도록 설정된 OAuth 1.0 인증이 실제로 요청 헤더에 추가되지 않던 문제를 수정했습니다.
Basic Auth가 중국어 변수를 사용할 때 생성된 엔드포인트 요청 코드가 올바르게 작동하지 않던 문제를 수정했습니다.
엔드포인트가 HTTP를 사용할 때 생성된 요청 코드가 잘못 HTTPS를 사용하던 문제를 수정했습니다.
시나리오 단계가 원시 형식 응답 본문을 참조할 때 CLI 시나리오 실행 시 "예상치 못한 토큰" 오류가 보고될 수 있던 문제를 수정했습니다.
자동화된 테스트 시나리오가 비정상적으로 종료된 후에도 테스트 보고서 세부 정보가 계속 실행 중으로 표시되던 문제를 수정했습니다.
루트 폴더에서 시나리오 케이스를 실행한 후 해당 보고서가 테스트 보고서 목록에 표시되지 않던 문제를 수정했습니다.
Apidog 웹 앱을 새로 고칠 때 프로젝트가 자동으로 메인 브랜치로 다시 전환되던 문제를 수정했습니다.
브랜치 가져오기 및 Markdown에 엔드포인트를 삽입할 때 태그 필터 옵션에 내용이 없던 문제를 수정했습니다.
여러 모듈과 서비스가 있는 Apidog 파일을 가져올 때 비기본 서비스가 반복적으로 추가되던 문제를 수정했습니다.
Apidog 데이터를 가져올 때 Markdown 문서 태그가 올바르게 가져와지지 않던 문제를 수정했습니다.
일부 경우에 엔드포인트를 메인 브랜치로 병합한 후에도 충돌이 계속 표시되던 문제를 수정했습니다.
일부 경우에 SSE 엔드포인트를 디버깅할 때 프론트엔드 오류가 발생할 수 있던 문제를 수정했습니다.
On-Premises 프로젝트 통계가 기본 모듈의 데이터만 계산하던 문제를 수정했습니다.
팀 세부 정보 페이지에서 다중 모듈 Apidog 파일을 가져올 때 엔드포인트가 기본 모듈로 잘못 가져와지던 문제를 수정했습니다.
수정 사항을 제출한 후 일부 경우에 변경 사항이 사라지던 문제를 수정했습니다.
비밀번호 변경 시 이메일 인증 흐름에서 잘못된 오류 메시지가 표시되던 문제를 수정했습니다.

개발팀에 의미하는 바

이번 업데이트는 사람, AI 에이전트, API 사양, 자동화된 테스트가 함께 동작하는 워크플로우를 더 안정적으로 만듭니다.

영역	개선 사항	중요성
AI 기반 CLI 워크플로우	CLI는 AI 에이전트가 실제 Apidog 프로젝트 리소스에서 작업하고, 테스트 케이스를 실행하고, 기존 자산을 참조하고, 내보내기를 더 정확하게 제어하는 데 도움이 될 수 있습니다.	AI 에이전트가 구조화되지 않은 정보에서 추측하는 대신 구조화된 프로젝트 컨텍스트를 사용하여 API 작업을 더 쉽게 완료할 수 있습니다.
가져오기 및 내보내기	Postman API 가져오기는 변수 이름을 정리하고 워크스페이스 이름을 명확히 할 수 있습니다; OpenAPI/Swagger 가져오기/내보내기는 객체 유형 및 참조 유형 매개변수를 지원합니다.	마이그레이션 후 정리 작업이 줄어들고 API 사양 교환이 더 완벽해집니다.
인증	OAuth 2.0 토큰이 자동으로 갱신될 수 있습니다.	API 디버깅 및 테스트 중 중단이 줄어듭니다.
MCP 호환성	MCP 클라이언트가 더 많은 비표준 스키마를 구문 분석할 수 있습니다.	실제 MCP 도구 및 서버와의 호환성이 향상됩니다.
테스트 워크플로우	정적 단계를 더 쉽게 찾을 수 있으며, 예약된 작업은 추가적인 8시간 간격을 지원합니다.	더 빠른 테스트 스위트 설정과 더 유연한 반복 테스트 실행.
웹 앱 구성	Apidog 웹 앱에서 자동 생성 헤더를 구성할 수 있습니다.	브라우저 기반 워크플로우에서 요청 동작에 대한 더 많은 제어 권한.

정리하면 다음과 같습니다.

AI 에이전트 → 더 나은 프로젝트 컨텍스트 확보
가져온 데이터 → 수동 정리 감소
OAuth 요청 → 토큰 만료 중단 감소
테스트 워크플로우 → 검색 및 예약 옵션 개선
웹 앱 요청 → 헤더 구성 제어 강화

대화에 참여하세요

동료 API 엔지니어 및 Apidog 팀과 연결하세요.

실시간 토론 및 지원을 위해 Discord 커뮤니티에 참여하세요.
기술적인 대화를 위해 Slack 커뮤니티에 참여하세요.
최신 업데이트를 위해 X (Twitter)를 팔로우하세요.

추신. 모든 업데이트에 대한 자세한 내용은 Apidog Changelog를 확인하세요.

감사합니다,

Apidog 팀 드림

GPT-5.6에 무슨 일이?

Rihpig — Fri, 26 Jun 2026 05:24:38 +0000

OpenAI의 다음 주력 모델로 알려진 GPT-5.6은 일반적인 방식으로 바로 공개 출시되지 않을 가능성이 큽니다. 2026년 6월 25일 보도에 따르면, 미국 정부는 OpenAI에 공개 출시를 보류하고 소수의 검증된 파트너에게 먼저 모델을 제공할 것을 요청했습니다. 이는 2주 전 Anthropic이 정부 지시에 따라 Fable 5 및 Mythos 5 모델을 오프라인으로 전환해야 했던 사례와 같은 흐름입니다. 결론은 단순합니다. 첨단 모델 API를 기반으로 제품을 만든다면, 특정 모델 하나에 강하게 결합된 아키텍처는 더 이상 안전하지 않습니다.

오늘 Apidog 사용해 보기

GPT-5.6에 무슨 일이 일어나고 있는가

현재까지 알려진 내용은 공식 발표가 아니라 보도 기반입니다. OpenAI와 백악관 모두 세부 사항을 공개적으로 확정하지 않았기 때문에, 아래 내용은 “보고된 상황”으로 봐야 합니다.

요청 주체: 트럼프 행정부, 특히 국가 사이버 국장실과 과학기술정책실이 OpenAI에 단계별 출시를 요청한 것으로 보도되었습니다. 이 내용은 The Information, Axios, SiliconANGLE에서 다뤄졌습니다.
단계별 출시의 의미: 공개 API에 즉시 개방하는 대신, GPT-5.6은 먼저 소수의 파트너에게 제공될 수 있습니다. 보도에 따르면 미리보기 기간에는 고객별 정부 승인이 필요할 수 있습니다.
이유: 국가 안보입니다. 특히 모델이 소프트웨어 취약점 탐지, 공격 경로 구성, 강화된 시스템 침투 등에 활용될 수 있다는 우려가 언급되었습니다.
시기: 6월 출시 기대는 지연되었습니다. 6월 말 출시를 예상했던 예측 시장은 약화되었고, 2026년 7월 출시 가능성이 더 높게 거론되고 있습니다.

즉, GPT-5.6은 제품 출시라기보다 통제된 배포에 가까운 방식으로 다뤄지고 있습니다. 현재 공개 API에서 사용 가능한 주력 모델은 여전히 GPT-5.5로 알려져 있습니다.

Fable 5와 Mythos 5 사례가 이미 있었다

GPT-5.6 상황은 독립적인 사건이 아닙니다. 2026년 6월 12일, Anthropic은 정부 지시에 따라 새로 발표한 Fable 5 및 Mythos 5 모델을 비활성화해야 했습니다.

CNBC, Fortune, Anthropic 공식 성명에 따르면 핵심은 다음과 같습니다.

이 조치는 국가 안보 당국을 인용한 수출 통제 지시였습니다.
Anthropic은 모든 외국인에 대한 모델 접근을 중단하라는 지시를 받았습니다.
촉발 요인은 Fable 5의 안전장치를 우회하는 기술이었습니다. 해당 안전장치는 Mythos 5의 더 강력한 사이버 보안 기능 접근을 차단하도록 설계된 것으로 설명되었습니다.
Anthropic은 외국인과 미국인을 실시간으로 확실하게 구분할 수 없었기 때문에, 결과적으로 모든 사용자에게 모델을 비활성화했습니다.
Anthropic은 명령을 따랐지만, 좁은 범위의 단일 탈옥 사례가 광범위하게 배포된 모델 회수로 이어져야 하는지에 대해서는 반발했습니다.

GPT-5.6 보도에서 이 사례가 자주 언급되는 이유는 명확합니다. 첨단 모델이 사이버 기능을 갖출수록, 출시 여부와 접근 범위가 공급업체만의 결정이 아니게 됩니다.

개발자에게 중요한 변화

이 이슈는 정책 뉴스가 아니라 운영 리스크입니다.

예를 들어 제품의 핵심 기능이 특정 모델 하나에 의존한다고 가정해 보겠습니다.

사용자 요청
  -> 백엔드
  -> 특정 모델 API
  -> 결과 후처리
  -> 사용자 응답

이 구조에서 모델이 갑자기 비활성화되면 재시도 로직은 도움이 되지 않습니다. 장애 원인이 네트워크, rate limit, 일시적 5xx가 아니라 접근 권한 자체의 철회일 수 있기 때문입니다.

GPT-5.6처럼 단계별 출시되는 모델도 비슷합니다.

출시일에 맞춰 기능을 배포하려 했지만 접근 권한이 없을 수 있습니다.
벤치마크를 미리 실행할 수 없을 수 있습니다.
승인된 파트너와 일반 API 사용자의 사용 가능 시점이 다를 수 있습니다.
문서상 모델은 존재하지만, 실제 프로덕션에서 호출할 수 없을 수 있습니다.

따라서 교훈은 “첨단 모델을 쓰지 말라”가 아닙니다.

교훈은 특정 모델을 교체 불가능한 종속성으로 만들지 말라는 것입니다.

모델 장애에 대비한 구현 패턴

정부 지시나 공급업체 정책은 통제할 수 없습니다. 대신 애플리케이션이 모델에 얼마나 강하게 결합되어 있는지는 통제할 수 있습니다.

아래 패턴은 실제 서비스에서 적용하기 쉽습니다.

1. 모델 호출을 내부 인터페이스 뒤에 숨기기

애플리케이션 코드 곳곳에서 직접 OpenAI, Anthropic, Google API를 호출하지 마세요. 대신 내부 LLMClient 같은 추상 계층을 둡니다.

export type ChatMessage = {
  role: "system" | "user" | "assistant";
  content: string;
};

export type LLMResponse = {
  text: string;
  model: string;
  provider: string;
};

export interface LLMClient {
  chat(messages: ChatMessage[]): Promise<LLMResponse>;
}

그다음 공급업체별 구현을 분리합니다.

export class OpenAIClient implements LLMClient {
  async chat(messages: ChatMessage[]): Promise<LLMResponse> {
    const res = await fetch("https://api.openai.com/v1/chat/completions", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        model: process.env.OPENAI_MODEL,
        messages,
      }),
    });

    if (!res.ok) {
      throw new Error(`OpenAI error: ${res.status}`);
    }

    const data = await res.json();

    return {
      text: data.choices[0].message.content,
      model: process.env.OPENAI_MODEL ?? "unknown",
      provider: "openai",
    };
  }
}

이렇게 하면 모델 변경은 코드 수정이 아니라 구성 변경에 가까워집니다.

LLM_PROVIDER=openai
OPENAI_MODEL=gpt-5.5

나중에 다른 공급업체나 라우터로 전환할 때도 호출부는 그대로 유지할 수 있습니다.

공급업체 독립적인 설계를 고민한다면 OpenRouter 대안과 LiteLLM 사용 가이드를 참고할 수 있습니다.

2. 장애 조치용 모델을 미리 정의하기

모델이 비활성화된 뒤에 대체 모델을 찾으면 늦습니다. 프로덕션 배포 전부터 fallback 순서를 정해두는 것이 좋습니다.

const candidates = [
  { provider: "openai", model: "gpt-5.5" },
  { provider: "anthropic", model: "fallback-model" },
  { provider: "google", model: "fallback-model" },
];

export async function callWithFallback(messages: ChatMessage[]) {
  const errors: unknown[] = [];

  for (const candidate of candidates) {
    try {
      const client = createClient(candidate.provider, candidate.model);
      return await client.chat(messages);
    } catch (error) {
      errors.push({
        provider: candidate.provider,
        model: candidate.model,
        error,
      });
    }
  }

  throw new Error(`All model providers failed: ${JSON.stringify(errors)}`);
}

실제 운영에서는 모든 오류에 대해 즉시 fallback하면 안 됩니다. 예를 들어 400 계열의 잘못된 요청은 fallback해도 실패할 가능성이 큽니다.

권장 분류는 다음과 같습니다.

오류 유형	fallback 권장 여부
401 / 403 접근 거부	예
404 모델 없음	예
429 rate limit	예
5xx 공급업체 장애	예
400 잘못된 요청 형식	아니요
응답 파싱 실패	상황에 따라 다름

3. 동일한 테스트 스위트를 여러 모델에 실행하기

대체 모델이 있다고 해서 바로 프로덕션에 넣을 수 있는 것은 아닙니다. 응답 형식, 길이, JSON 안정성, 금지 케이스 처리 등이 기존 모델과 다를 수 있습니다.

예를 들어 앱이 항상 JSON 응답을 기대한다면, 테스트는 단순히 HTTP 200만 확인하면 안 됩니다.

{
  "summary": "string",
  "riskLevel": "low | medium | high",
  "actions": ["string"]
}

테스트에서는 다음을 검증해야 합니다.

응답이 유효한 JSON인지
필수 필드가 있는지
enum 값이 허용 범위 안에 있는지
빈 응답이 아닌지
토큰 초과나 잘림이 없는지

예시 어설션은 다음과 같습니다.

function validateModelOutput(output: unknown) {
  if (typeof output !== "object" || output === null) {
    throw new Error("Output must be an object");
  }

  const data = output as Record<string, unknown>;

  if (typeof data.summary !== "string") {
    throw new Error("summary must be a string");
  }

  if (!["low", "medium", "high"].includes(String(data.riskLevel))) {
    throw new Error("riskLevel is invalid");
  }

  if (!Array.isArray(data.actions)) {
    throw new Error("actions must be an array");
  }
}

이 테스트를 기본 모델과 fallback 모델에 모두 실행해야 합니다.

API 요청과 검증을 재사용하는 방법은 Apidog로 ChatGPT API를 테스트하는 방법과 API 어설션을 참고하세요.

4. 모델 API를 목업해서 개발 중단을 막기

모델 접근이 막히면 프로덕션만 문제가 되는 것이 아닙니다. 프런트엔드 개발, QA, CI 테스트도 멈출 수 있습니다.

이를 막으려면 모델 API의 대표 응답을 목업해두세요.

{
  "id": "mock-chatcmpl-001",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"summary\":\"예시 요약\",\"riskLevel\":\"low\",\"actions\":[\"로그 확인\",\"재시도\"]}"
      },
      "finish_reason": "stop"
    }
  ]
}

개발 환경에서는 실제 모델 대신 목업 서버를 바라보게 구성합니다.

LLM_BASE_URL=https://mock-api.example.com
LLM_PROVIDER=mock

이 방식의 장점은 명확합니다.

실제 모델 장애와 무관하게 UI 개발 가능
CI에서 안정적인 테스트 가능
응답 포맷 변경에 대한 계약 테스트 가능
rate limit 비용 없이 반복 테스트 가능

목업 API를 사용하면 실제 모델 API의 응답 구조를 흉내 내는 엔드포인트를 만들고, 프런트엔드와 백엔드 테스트를 계속 진행할 수 있습니다.

5. 모델별 비용과 지연 시간을 추적하기

fallback은 무료가 아닙니다. 대체 모델이 더 비싸거나 느릴 수 있습니다.

최소한 다음 필드는 로그로 남기는 것이 좋습니다.

{
  "feature": "support-ticket-summary",
  "provider": "openai",
  "model": "gpt-5.5",
  "latencyMs": 1830,
  "inputTokens": 1200,
  "outputTokens": 320,
  "status": "success",
  "fallbackUsed": false
}

장애 조치가 발생하면 다음을 바로 확인할 수 있어야 합니다.

어떤 기능에서 fallback이 발생했는가
어떤 모델로 전환되었는가
지연 시간이 얼마나 증가했는가
비용이 얼마나 변했는가
실패율이 줄었는가

기능별 비용 추적은 기능별 API 지출을 참고할 수 있습니다.

권장 아키텍처

모델 API를 직접 호출하는 구조보다 다음과 같은 구조가 안전합니다.

Application
  -> Internal LLM Gateway
      -> Provider Adapter: OpenAI
      -> Provider Adapter: Anthropic
      -> Provider Adapter: Google
      -> Provider Adapter: Mock
  -> Logging / Cost Tracking
  -> Contract Tests

핵심은 세 가지입니다.

호출부는 공급업체를 몰라야 합니다.
fallback 후보는 사전에 테스트되어 있어야 합니다.
목업 서버로 개발과 테스트를 계속할 수 있어야 합니다.

이렇게 설계하면 특정 모델이 갑자기 사라져도 전체 앱이 멈추지 않습니다.

자주 묻는 질문

GPT-5.6이 이미 출시되었나요?

아니요. 2026년 6월 말 기준 공개 출시되지 않은 것으로 보도되었습니다. 보도에 따르면 OpenAI는 먼저 소수의 검증된 파트너에게 모델을 제공할 수 있으며, 정부 검토가 잘 진행되면 몇 주 후 더 광범위한 출시가 가능하다고 언급되었습니다. OpenAI는 공식 출시일을 확인하지 않았고, 공개 API는 여전히 GPT-5.5로 운영되는 것으로 알려져 있습니다.

정부가 GPT-5.6 출시에 개입한 이유는 무엇인가요?

보도된 이유는 국가 안보입니다. 특히 첨단 모델이 소프트웨어 취약점을 찾거나 시스템 침투에 활용될 수 있다는 우려가 언급되었습니다. 요청은 국가 사이버 국장실과 과학기술정책실에서 나온 것으로 알려졌습니다.

Anthropic의 Fable 5와 Mythos 5에는 무슨 일이 있었나요?

2026년 6월 12일, Anthropic은 외국인에 대한 접근을 중단하라는 수출 통제 지시를 받았습니다. 외국인 사용자와 미국인 사용자를 실시간으로 확실하게 구분할 수 없었기 때문에, Anthropic은 모든 사용자에게 Fable 5와 Mythos 5를 비활성화했습니다. 이 사례는 이후 GPT-5.6 보도에서 선례로 언급되고 있습니다.

모델이 회수되면 앱을 어떻게 계속 작동시킬 수 있나요?

단일 모델에 직접 의존하지 않도록 설계해야 합니다. 내부 LLM 인터페이스를 만들고, 여러 공급업체 어댑터를 분리하며, fallback 모델을 사전에 테스트하세요. 또한 Apidog 목업 서버 같은 도구로 모델 API를 목업하면 실제 모델 접근이 막혀도 개발과 테스트를 계속할 수 있습니다.

마무리

Fable 5와 Mythos 5가 회수된 지 2주 만에 GPT-5.6이 단계별 출시 대상으로 보도된 것은 우연으로 보기 어렵습니다. 첨단 모델은 이제 단순한 SaaS API가 아니라, 국가 안보 검토와 접근 통제의 영향을 받을 수 있는 인프라 종속성입니다.

개발자가 할 일은 첨단 모델을 피하는 것이 아닙니다. 특정 모델 하나를 영구적인 전제로 삼지 않는 것입니다.

모델 호출을 내부 인터페이스 뒤에 숨기세요.
fallback 모델을 미리 테스트하세요.
모델 API를 목업하세요.
모델별 비용, 지연 시간, 실패율을 추적하세요.
공급업체 전환을 코드 수정이 아니라 구성 변경으로 만드세요.

이런 구조를 Apidog에서 테스트, 목업, 문서화하면 단일 모델을 단일 장애 지점으로 두는 위험을 줄일 수 있습니다.

OpenAI 함수 호출 사용법

Rihpig — Fri, 26 Jun 2026 05:22:24 +0000

이 가이드에서는 OpenAI 함수 호출(도구 호출)을 실제 애플리케이션에 연결하는 흐름을 구현합니다. 도구를 정의하고, OpenAI에 전달하고, 모델이 반환한 도구 호출을 파싱한 뒤, 구조화된 인수로 직접 함수를 실행합니다. 이후 엄격 모드와 병렬 호출을 설정하고, Apidog로 도구 인수와 하위 API 계약을 검증합니다. 공식 기준은 OpenAI의 함수 호출 문서를 참고하고, 더 큰 그림은 OpenAI Agents SDK로 에이전트 구축을 함께 확인하세요.

지금 Apidog를 사용해 보세요

시작하기 전에 필요한 것

함수 호출은 모델이 코드 또는 외부 시스템과 상호작용하는 방식입니다. 앱에서 사용할 수 있는 함수를 모델에 설명하면, 모델은 사용자 요청을 해석하고 적절한 함수 이름과 인수를 JSON 형태로 반환합니다.

중요한 점은 모델이 함수를 직접 실행하지 않는다는 것입니다.

흐름은 다음과 같습니다.

개발자가 함수 스키마를 정의합니다.
모델이 사용자 요청에 맞는 함수 호출을 생성합니다.
개발자가 arguments를 파싱합니다.
개발자 코드가 실제 함수를 실행합니다.
실행 결과를 다시 모델에 전달합니다.
모델이 최종 응답을 생성합니다.

예를 들어 사용자가 “파리의 날씨를 알려줘”라고 말하면, 모델은 직접 날씨 API를 호출하지 않고 다음과 같은 구조화된 호출을 반환합니다.

get_weather({
  location: "Paris, France"
})

따라하려면 다음이 필요합니다.

OpenAI API 키
모델이 호출할 수 있는 자체 함수
함수가 기대하는 입력 스키마
선택적으로 하위 API를 테스트하거나 모의 처리할 도구

OpenAI에서는 Chat Completions API와 Responses API 모두 함수 호출을 지원합니다. 이 글에서는 두 방식의 차이도 함께 다룹니다.

1단계: 도구 정의하기

도구는 모델이 읽을 수 있는 함수 정의입니다. 일반적으로 다음 정보를 포함합니다.

함수 이름
함수 설명
인수 스키마
필수 필드
허용 가능한 값
추가 필드 허용 여부

설명은 단순한 라벨이 아니라 모델에게 “언제 이 함수를 사용해야 하는지” 알려주는 지침입니다.

Chat Completions API용 도구 정의

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the current weather for a city. Use when the user asks about temperature or conditions.",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City and country, e.g. Bogotá, Colombia"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"]
        }
      },
      "required": ["location"],
      "additionalProperties": false
    }
  }
}

Responses API용 도구 정의

Responses API에서는 function 래퍼 없이 더 평탄한 형태를 사용합니다.

{
  "type": "function",
  "name": "get_weather",
  "description": "Get the current weather for a city. Use when the user asks about temperature or conditions.",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City and country, e.g. Bogotá, Colombia"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"]
      }
    },
    "required": ["location"],
    "additionalProperties": false
  }
}

이미 OpenAPI 사양을 관리하고 있다면 함수 인수 스키마를 거의 그대로 재사용할 수 있습니다. OpenAPI 사양에서 테스트 컬렉션 생성 가이드도 함께 참고하세요.

2단계: 첫 번째 요청 보내기

사용자 메시지와 도구 정의를 함께 모델에 전달합니다.

Chat Completions API 예시는 다음과 같습니다.

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Paris right now?"
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a city.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string"
              }
            },
            "required": ["location"],
            "additionalProperties": false
          }
        }
      }
    ]
  }'

tools 배열에는 이번 턴에서 모델에게 노출할 함수들을 넣습니다. 모델은 사용자 메시지를 읽고 다음 중 하나를 선택합니다.

일반 텍스트 응답
하나 이상의 도구 호출
도구 호출 없이 추가 설명

날씨 요청처럼 함수가 적합한 경우, 모델은 일반 문장이 아니라 도구 호출을 반환합니다.

3단계: 모델이 반환한 도구 호출 읽기

모델이 함수를 호출하기로 결정하면 응답 구조 안에 호출 정보가 들어 있습니다.

Chat Completions API 응답 형태

Chat Completions에서는 assistant 메시지의 tool_calls 배열을 확인합니다.

{
  "id": "call_12345xyz",
  "type": "function",
  "function": {
    "name": "get_weather",
    "arguments": "{\"location\":\"Paris, France\"}"
  }
}

여기서 확인할 필드는 다음입니다.

id: 나중에 함수 결과를 되돌려줄 때 사용
function.name: 실행할 함수 이름
function.arguments: JSON 문자열 형태의 인수

Responses API 응답 형태

Responses API에서는 output 배열 안에 function_call 항목이 들어갑니다.

{
  "type": "function_call",
  "call_id": "call_12345xyz",
  "name": "get_weather",
  "arguments": "{\"location\":\"Paris, France\"}"
}

중요한 점은 arguments가 객체가 아니라 JSON으로 인코딩된 문자열이라는 것입니다. 따라서 반드시 직접 파싱해야 합니다.

const toolCall = {
  id: "call_12345xyz",
  type: "function",
  function: {
    name: "get_weather",
    arguments: "{\"location\":\"Paris, France\"}"
  }
};

const args = JSON.parse(toolCall.function.arguments);

console.log(args.location);
// Paris, France

실제 코드에서는 파싱 직후 스키마 검증도 수행하는 것이 좋습니다.

4단계: 직접 함수 실행하기

모델은 함수 이름과 인수만 제공합니다. 실제 실행은 애플리케이션 코드가 담당합니다.

예를 들어 Node.js에서는 다음처럼 매핑할 수 있습니다.

async function getWeather({ location, unit = "celsius" }) {
  // 실제로는 외부 날씨 API 또는 내부 서비스를 호출
  return {
    location,
    unit,
    temperature: 18,
    condition: "cloudy"
  };
}

const availableFunctions = {
  get_weather: getWeather
};

async function executeToolCall(toolCall) {
  const functionName = toolCall.function.name;
  const args = JSON.parse(toolCall.function.arguments);

  const fn = availableFunctions[functionName];

  if (!fn) {
    throw new Error(`Unknown function: ${functionName}`);
  }

  return await fn(args);
}

이 단계에서 해야 할 검증은 다음과 같습니다.

함수 이름이 허용된 목록에 있는지 확인
arguments가 올바른 JSON인지 확인
필수 필드가 있는지 확인
enum 값이 허용 범위 안에 있는지 확인
비즈니스 규칙에 맞는지 확인

예를 들어 location이 문자열이어도 서비스하지 않는 지역일 수 있습니다. 스키마 검증과 비즈니스 검증은 별도로 처리해야 합니다.

5단계: 실행 결과를 모델에 반환하기

함수 실행이 끝나면 결과를 모델에 다시 보내야 합니다. 그래야 모델이 사용자에게 최종 답변을 생성할 수 있습니다.

Chat Completions API 방식

Chat Completions에서는 tool 역할 메시지를 추가하고, 원래 도구 호출의 id를 tool_call_id로 연결합니다.

{
  "role": "tool",
  "tool_call_id": "call_12345xyz",
  "content": "{\"location\":\"Paris, France\",\"temperature\":18,\"unit\":\"celsius\",\"condition\":\"cloudy\"}"
}

전체 흐름은 다음과 같습니다.

사용자 메시지 전송
모델이 tool_calls 반환
앱이 함수 실행
tool 메시지로 결과 전달
모델이 최종 답변 생성

Responses API 방식

Responses API에서는 function_call_output 항목을 사용하고 call_id로 연결합니다.

{
  "type": "function_call_output",
  "call_id": "call_12345xyz",
  "output": "{\"location\":\"Paris, France\",\"temperature\":18,\"unit\":\"celsius\",\"condition\":\"cloudy\"}"
}

핵심은 동일합니다.

모델이 요청하고, 애플리케이션이 실행하고, 결과를 다시 모델에 전달합니다.

6단계: 병렬 호출과 엄격 모드 설정하기

기본 루프가 동작하면 신뢰성과 실행 방식을 조정합니다.

병렬 도구 호출

기본적으로 모델은 한 번의 턴에서 여러 도구 호출을 반환할 수 있습니다.

예를 들어 사용자가 다음처럼 요청할 수 있습니다.

서울, 파리, 뉴욕의 현재 날씨를 알려줘.

모델은 세 개의 get_weather 호출을 동시에 반환할 수 있습니다.

[
  {
    "function": {
      "name": "get_weather",
      "arguments": "{\"location\":\"Seoul, South Korea\"}"
    }
  },
  {
    "function": {
      "name": "get_weather",
      "arguments": "{\"location\":\"Paris, France\"}"
    }
  },
  {
    "function": {
      "name": "get_weather",
      "arguments": "{\"location\":\"New York, USA\"}"
    }
  }
]

각 호출이 독립적이라면 병렬 실행이 유리합니다.

const results = await Promise.all(
  toolCalls.map((toolCall) => executeToolCall(toolCall))
);

반대로 호출 순서가 중요하거나 이전 결과에 의존한다면 parallel_tool_calls를 false로 설정합니다.

{
  "parallel_tool_calls": false
}

엄격 모드

엄격 모드는 모델이 반환하는 인수가 JSON 스키마와 일치하도록 강제합니다.

OpenAI는 엄격 모드 사용을 권장합니다.

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the current weather for a city.",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string"
        },
        "unit": {
          "type": ["string", "null"],
          "enum": ["celsius", "fahrenheit", null]
        }
      },
      "required": ["location", "unit"],
      "additionalProperties": false
    }
  }
}

엄격 모드에서는 다음 규칙을 지켜야 합니다.

모든 객체에 additionalProperties: false를 설정합니다.
properties의 모든 필드는 required에 포함합니다.
선택적 필드는 생략하지 않고 null을 허용합니다.

예를 들어 unit이 선택 사항이라면 required에서 제거하는 대신 다음처럼 정의합니다.

{
  "unit": {
    "type": ["string", "null"],
    "enum": ["celsius", "fahrenheit", null]
  }
}

이렇게 하면 모델은 다음 중 하나를 반환합니다.

{
  "location": "Paris, France",
  "unit": "celsius"
}

또는:

{
  "location": "Paris, France",
  "unit": null
}

키가 항상 존재하므로 파싱 코드가 단순해집니다.

주요 설정 요약

설정	제어하는 내용	기본값	변경 시점
`parallel_tool_calls`	한 턴에서 여러 도구 호출을 반환할 수 있는지 여부	`true`	호출 순서가 중요하거나 서로 의존할 때 `false`
`strict`	인수가 스키마와 일치해야 하는지 여부	미설정 시 최선 노력	프로덕션 또는 안정적인 파싱이 필요할 때 활성화
`tool_choice`	모델이 도구를 사용할 수 있는지, 특정 도구를 강제할지 여부	`auto`	호출 강제는 `required`, 비활성화는 `none`, 특정 함수 지정 가능

엄격 모드는 잘못된 형식의 JSON을 줄이는 데 도움이 됩니다. 하지만 값이 비즈니스적으로 유효한지는 보장하지 않습니다.

예를 들어 다음 값은 스키마상 문자열이므로 유효할 수 있습니다.

{
  "location": "Unknown City",
  "unit": "celsius"
}

하지만 실제 서비스에서는 지원하지 않는 지역일 수 있습니다. 따라서 별도의 비즈니스 검증과 오류 처리가 필요합니다.

Apidog에서 테스트하는 방법

모델이 도구 호출을 반환하더라도, 실제 함수에 연결하기 전에 두 가지를 확인해야 합니다.

모델이 만든 arguments가 함수 스키마와 일치하는가?
함수가 호출할 하위 API가 예상대로 동작하는가?

Apidog는 이 두 영역을 검증하는 데 사용할 수 있습니다.

Apidog가 직접 애플리케이션 함수를 실행하는 것은 아닙니다. 대신 함수 주변의 API 계약을 검증하고 모의 처리합니다.

1. 도구 호출 인수 검증하기

OpenAI 응답에서 arguments 문자열을 추출합니다.

"{\"location\":\"Paris, France\",\"unit\":\"celsius\"}"

이를 JSON으로 파싱하면 다음과 같습니다.

{
  "location": "Paris, France",
  "unit": "celsius"
}

Apidog에서 이 JSON을 요청 본문처럼 다루고 다음을 검증할 수 있습니다.

location이 존재하는지
location이 문자열인지
unit이 허용된 enum 값인지
필수 필드가 모두 있는지
추가 필드가 없는지

필드 추출에는 JSONPath 표현식을 사용할 수 있습니다. 더 엄격한 구조 검사는 JSON 스키마 유효성 검사를 적용하면 됩니다.

권장 방식은 OpenAI 도구 정의에 사용한 스키마와 동일한 스키마를 Apidog 검증에도 반영하는 것입니다. 그러면 모델 출력과 함수 입력 계약을 같은 기준으로 확인할 수 있습니다.

2. 함수가 호출할 하위 API 모의 처리하기

get_weather 함수는 보통 외부 날씨 API 또는 내부 서비스를 호출합니다. 하지만 개발 중에는 다음 문제가 있을 수 있습니다.

실제 API가 아직 준비되지 않음
호출 비용이 발생함
속도 제한이 있음
오류 응답을 재현하기 어려움
테스트 데이터가 불안정함

이 경우 Apidog에서 모의 API를 만들고 함수가 해당 모의 API를 호출하도록 설정합니다.

예를 들어 모의 응답은 다음처럼 구성할 수 있습니다.

{
  "location": "Paris, France",
  "temperature": 18,
  "unit": "celsius",
  "condition": "cloudy"
}

오류 케이스도 직접 만들 수 있습니다.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests"
  }
}

이렇게 하면 실제 API를 소모하지 않고도 다음을 테스트할 수 있습니다.

정상 응답 처리
타임아웃 처리
429 응답 처리
잘못된 응답 형식 처리
빈 데이터 처리
하위 API 장애 시 사용자 응답 처리

권장 워크플로우는 다음과 같습니다.

OpenAI에서 도구 호출을 캡처합니다.
arguments를 파싱합니다.
Apidog에서 JSON 스키마로 인수를 검증합니다.
함수가 호출할 하위 API를 Apidog 모의 API로 대체합니다.
정상 응답과 오류 응답을 모두 테스트합니다.
검증이 끝나면 실제 API로 전환합니다.

자주 묻는 질문

함수 호출은 Chat Completions와 Responses API 모두에서 작동하나요?

예. 두 엔드포인트 모두 함수 호출을 지원합니다.

차이는 응답과 도구 정의의 형태입니다.

Chat Completions는 함수를 function 키 아래에 중첩하고, 응답에서 tool_calls를 반환합니다.

Responses API는 더 평탄한 도구 정의를 사용하고, output 배열 안에 function_call 항목을 반환합니다.

모델이 인수를 객체가 아니라 문자열로 반환하는 이유는 무엇인가요?

arguments 필드는 JSON으로 인코딩된 문자열입니다. 따라서 사용 전 반드시 파싱해야 합니다.

const args = JSON.parse(toolCall.function.arguments);

파싱 후에는 스키마 검증을 수행하는 것이 안전합니다. JSON 스키마 유효성 검사를 적용하면 잘못된 페이로드가 실제 함수에 도달하기 전에 차단할 수 있습니다.

엄격 모드는 함수 성공을 보장하나요?

아니요. 엄격 모드는 인수 구조가 JSON 스키마와 일치하도록 돕습니다.

하지만 다음은 보장하지 않습니다.

외부 API 성공
비즈니스 규칙 충족
사용자가 요청한 값의 실제 존재 여부
함수 내부 로직 성공
네트워크 장애 방지

따라서 엄격 모드와 별도로 값 검증, 예외 처리, 재시도, 타임아웃 처리를 구현해야 합니다.

Apidog가 실제 함수를 실행할 수 있나요?

아니요. Apidog는 애플리케이션 함수를 대신 실행하지 않습니다.

Apidog의 역할은 다음에 가깝습니다.

모델이 생성한 인수 구조 검증
JSON 스키마 기반 계약 확인
함수가 의존하는 API 모의 처리
정상 및 오류 응답 테스트
API 문서와 테스트 컬렉션 관리

실제 함수 실행은 여전히 애플리케이션 코드가 담당합니다.

마무리

OpenAI 함수 호출 구현의 핵심 루프는 단순합니다.

도구를 명확하게 정의합니다.
사용자 메시지와 함께 도구를 모델에 전달합니다.
모델이 반환한 tool_calls 또는 function_call을 읽습니다.
arguments를 JSON으로 파싱합니다.
허용된 함수만 실행합니다.
실행 결과를 모델에 다시 전달합니다.
모델이 최종 응답을 생성합니다.

프로덕션에 가까워질수록 다음 설정을 추가하세요.

strict: true로 인수 구조 안정화
additionalProperties: false로 예상 외 필드 차단
parallel_tool_calls로 병렬 실행 제어
스키마 검증으로 잘못된 입력 차단
Apidog 모의 API로 하위 API 의존성 테스트

테스트 측면을 강화하고 싶다면 Apidog를 다운로드하여 도구 호출 인수를 스키마에 대해 확인하고, 함수가 의존하는 API를 한 곳에서 모의 처리해 보세요.

OpenAI Responses API 사용법

Rihpig — Fri, 26 Jun 2026 03:15:23 +0000

이 가이드는 OpenAI Responses API를 처음부터 끝까지 구현하는 방법을 다룹니다. 완료하면 POST /v1/responses로 요청을 보내고, 중첩된 output을 파싱하고, 내장 도구를 활성화하고, 호출 간 대화 상태를 유지하며, Apidog에서 API 계약을 테스트할 수 있습니다. Responses API는 OpenAI의 새로운 모델 출력 생성 인터페이스이며, 공식 Responses 가이드는 OpenAI가 왜 새 프로젝트에 이 API를 권장하는지 설명합니다. 기존 엔드포인트를 테스트 중이라면 ChatGPT API 테스트 가이드의 워크플로를 대부분 재사용할 수 있습니다.

오늘 Apidog를 사용해 보세요

먼저 필요한 것

요청을 보내기 전에 다음을 준비하세요.

현재 범용 모델에 접근할 수 있는 OpenAI API 키
계정에서 실제로 호출 가능한 모델 이름
원시 HTTP 요청을 보내고 JSON 응답을 확인할 도구
- 첫 호출: curl
- 반복 테스트, 어설션, 목업: Apidog

API 키는 환경 변수에 저장하세요. 명령어, 문서, 공유 컬렉션에 직접 붙여넣지 않는 것이 좋습니다.

Responses API의 핵심 엔드포인트는 하나입니다.

POST /v1/responses

API 레퍼런스에 따르면 이 엔드포인트는 모델 이름과 input을 받아 응답 객체를 반환합니다. 응답에는 일반 텍스트뿐 아니라 함수 호출, 웹 검색, 파일 검색 같은 OpenAI 호스팅 도구 실행 결과가 포함될 수 있습니다.

예를 들어 한 번의 호출에서 모델은 다음을 수행할 수 있습니다.

사용자 입력을 해석합니다.
필요한 경우 웹 검색을 실행합니다.
검색 결과를 읽습니다.
최종 답변을 작성합니다.
각 단계를 output 배열에 기록합니다.

Responses API가 일반 텍스트 생성 API와 다른 점은 크게 두 가지입니다.

첫째, 내장 도구를 서버 측에서 실행할 수 있습니다. 자체 검색 파이프라인이나 코드 실행 샌드박스를 직접 붙이지 않아도 됩니다.

둘째, 기본적으로 상태를 가질 수 있습니다. 각 응답은 id를 가지며, 다음 요청에서 이 값을 previous_response_id로 전달하면 OpenAI가 이전 대화 컨텍스트를 이어서 처리합니다.

OpenAI는 Responses API를 Chat Completions의 진화로 설명하며, 새로운 프로젝트에는 Responses API 사용을 권장합니다.

Chat Completions와 다른 점

POST /v1/chat/completions를 사용해 봤다면 가장 큰 차이는 요청/응답 형태와 상태 관리 방식입니다.

Chat Completions는 messages 배열을 받고 choices를 반환합니다. 대화 기록은 클라이언트가 직접 관리해야 하며, 매 호출마다 이전 메시지를 다시 보내는 방식이 일반적입니다.

Responses API는 input을 받고 output을 반환합니다. input은 문자열이거나 유형화된 항목 목록일 수 있습니다. 또한 store와 previous_response_id를 통해 서버 측 대화 상태를 이어갈 수 있습니다.

측면	Chat Completions	Responses API
엔드포인트	`POST /v1/chat/completions`	`POST /v1/responses`
요청 본문	`messages` 배열	`input` + `instructions`
출력 형태	`choices[].message`	유형화된 항목 목록인 `output`
대화 상태	전체 기록을 다시 전송	`store` + `previous_response_id`
내장 도구	직접 구현	`web_search`, `file_search`, `code_interpreter` 등
상태	계속 지원됨	새 프로젝트에 권장됨

Chat Completions는 폐기 예정이 아닙니다. 따라서 기존 통합을 한 번에 모두 바꿀 필요는 없습니다. 사용자 흐름 단위로 점진적으로 마이그레이션할 수 있습니다.

반면 Assistants API는 폐기 예정입니다. OpenAI는 2025년 8월 26일 폐기를 발표했고, 2026년 8월 26일을 서비스 종료일로 명시했습니다. 새 에이전트형 작업은 Responses API에서 시작하는 것이 적절합니다.

첫 요청 보내기

가장 작은 형태의 호출부터 시작합니다.

먼저 API 키를 환경 변수로 설정하세요.

export OPENAI_API_KEY="your_api_key"

그다음 POST /v1/responses를 호출합니다.

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Write one sentence describing what an API mock server does.",
    "instructions": "You are a concise technical writer. No marketing language.",
    "store": true
  }'

여기서 핵심 필드는 다음과 같습니다.

model: 호출할 모델 이름
input: 사용자 입력 또는 프롬프트
instructions: 시스템 수준의 지시
store: 응답을 저장해 이후 대화에 재사용할지 여부

모델 이름은 계정 권한에 따라 달라질 수 있습니다. 하드코딩하기 전에 OpenAI 대시보드에서 사용할 수 있는 모델을 확인하세요.

응답 읽기

간략화된 응답은 다음과 같습니다.

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "A mock server returns predefined API responses so clients can be developed and tested before the real backend exists."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 28,
    "output_tokens": 24,
    "total_tokens": 52
  }
}

텍스트는 최상위 필드에 있지 않습니다. 원시 HTTP 응답에서 실제 답변 텍스트는 다음 경로에 있습니다.

output[0].content[0].text

확인해야 할 주요 필드는 다음과 같습니다.

id: 다음 요청에서 previous_response_id로 사용할 수 있는 응답 ID
status: 요청 처리 상태
output: 메시지, 도구 호출 등 유형화된 출력 항목
usage.total_tokens: 입력과 출력에 사용된 전체 토큰 수

SDK에서는 여러 텍스트 항목을 합쳐주는 output_text 같은 편의 접근자를 제공할 수 있습니다. 하지만 원시 HTTP JSON에서는 중첩된 output[].content[].text 경로를 직접 읽어야 합니다.

예를 들어 jq로 텍스트만 추출하려면 다음처럼 처리할 수 있습니다.

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Write one sentence describing what an API mock server does."
  }' | jq -r '.output[0].content[0].text'

내장 도구 추가하기

Responses API의 중요한 기능 중 하나는 OpenAI가 특정 도구를 대신 실행할 수 있다는 점입니다.

도구는 tools 배열에 선언합니다. 모델은 입력을 보고 도구 호출이 필요한지 결정합니다.

사용 가능한 내장 도구 유형은 다음과 같습니다.

web_search: 인용문을 포함한 실시간 인터넷 검색
file_search: 업로드한 파일 기반 검색
code_interpreter: 샌드박스에서 코드 실행 및 분석
computer_use: 컴퓨터 인터페이스 제어
image_generation: 인라인 이미지 생성

예를 들어 웹 검색을 허용하려면 다음처럼 요청합니다.

{
  "model": "gpt-5.5",
  "input": "What changed in the latest OpenAPI release? Cite sources.",
  "tools": [
    {
      "type": "web_search"
    }
  ]
}

모델이 도구를 사용하면 output 배열에는 최종 메시지뿐 아니라 도구 실행 단계를 나타내는 항목도 포함됩니다.

예를 들어 웹 검색을 실행했다면 web_search_call 유형의 항목이 나타날 수 있습니다. 따라서 통합 테스트에서는 단순히 텍스트가 반환됐는지만 확인하지 말고, 필요한 도구가 실제로 호출됐는지도 확인하는 것이 좋습니다.

호출 간 대화 계속하기

Responses API에서 상태 관리는 store와 previous_response_id로 처리합니다.

기본적으로 store는 true입니다. 이 경우 OpenAI는 응답 객체를 저장하고, 이후 요청에서 참조할 수 있는 id를 반환합니다.

첫 요청에서 받은 응답 ID가 다음과 같다고 가정합니다.

{
  "id": "resp_abc123"
}

이후 요청에서 previous_response_id로 전달하면 이전 대화를 이어갈 수 있습니다.

{
  "model": "gpt-5.5",
  "input": "Now rewrite that for a non-technical audience.",
  "previous_response_id": "resp_abc123"
}

이 방식의 장점은 클라이언트가 전체 대화 기록을 매번 다시 보내지 않아도 된다는 점입니다.

반대로 상태 비저장 방식이 필요하다면 store를 false로 설정하고 컨텍스트를 직접 관리하세요.

{
  "model": "gpt-5.5",
  "input": "Summarize this text.",
  "store": false
}

실시간 음성 또는 오디오 기반 저지연 흐름은 다른 인터페이스를 사용합니다. 해당 사례는 GPT 실시간 API 가이드에서 다룹니다. 다단계 에이전트를 구성하는 경우에는 OpenAI Agents SDK 패턴과도 연결됩니다.

Apidog에서 테스트하는 방법

Apidog는 API 테스트, 설계, 목업 플랫폼입니다. OpenAI SDK나 코드 라이브러리가 아니므로 Python 코드를 작성하지 않습니다.

대신 Apidog에서 다음 작업을 수행합니다.

/v1/responses에 대한 원시 HTTP 요청을 만듭니다.
환경 변수로 API 키를 관리합니다.
요청을 전송합니다.
반환된 JSON 구조를 확인합니다.
응답 필드에 어설션을 추가합니다.
필요하면 응답을 목업으로 저장합니다.

이 방식은 실제 앱이 의존하는 API 계약을 직접 검증하는 데 적합합니다.

1. 환경 변수에 API 키 저장하기

Apidog에서 새 환경을 만듭니다.

예:

OpenAI Prod

그다음 환경 변수로 API 키를 추가합니다.

OPENAI_API_KEY=your_api_key

요청에는 실제 키를 직접 넣지 말고 변수를 사용합니다.

Authorization: Bearer {{OPENAI_API_KEY}}

이렇게 하면 공유 컬렉션이나 문서에 비밀 값이 노출되는 것을 피할 수 있습니다.

2. `/v1/responses` 요청 만들기

Apidog에서 새 POST 요청을 생성합니다.

POST https://api.openai.com/v1/responses

헤더를 추가합니다.

Authorization: Bearer {{OPENAI_API_KEY}}
Content-Type: application/json

본문은 JSON으로 설정합니다.

{
  "model": "gpt-5.5",
  "input": "Write one sentence describing what an API mock server does.",
  "instructions": "You are a concise technical writer. No marketing language.",
  "store": true
}

전송하면 Apidog에서 전체 응답 객체와 중첩된 output 배열을 확인할 수 있습니다.

3. 응답 필드에 어설션 추가하기

HTTP 200만 확인하는 것은 충분하지 않습니다. 앱이 기대하는 JSON 형태가 유지되는지 확인해야 합니다.

/v1/responses 응답에서 유용한 어설션은 다음과 같습니다.

status가 completed와 같음
output[0].content[0].text가 존재함
output[0].content[0].text가 빈 문자열이 아님
usage.total_tokens가 0보다 큼
tools를 보낸 경우 output 항목 중 type이 web_search_call인 항목이 존재함

Apidog의 시각적 어설션 빌더를 사용하면 테스트 스크립트를 직접 작성하지 않고도 JSON 경로 기반 검사를 추가할 수 있습니다. 더 구체적인 구성 방식은 API 테스트 케이스 템플릿을 참고하세요.

요청을 컬렉션에 저장하면 반복 가능한 테스트로 사용할 수 있고, CI에서 실행할 수도 있습니다.

4. 내장 도구 호출 테스트하기

웹 검색 도구를 테스트하려면 본문에 tools 배열을 추가합니다.

{
  "model": "gpt-5.5",
  "input": "What changed in the latest OpenAPI release? Cite sources.",
  "tools": [
    {
      "type": "web_search"
    }
  ]
}

응답에서 다음을 확인하세요.

output[*].type

도구가 실행되었다면 web_search_call 같은 항목이 포함됩니다.

테스트 기준은 다음처럼 잡을 수 있습니다.

최종 답변 메시지가 존재한다.
도구 호출 항목이 존재한다.
도구 호출 후 생성된 텍스트가 비어 있지 않다.

이렇게 하면 모델이 단순히 답변을 생성했는지뿐 아니라, 기대한 방식으로 도구를 사용했는지도 검증할 수 있습니다.

5. 오프라인 개발을 위한 응답 목업 만들기

OpenAI 호출은 비용이 발생하고 네트워크 접근이 필요합니다. UI 개발이나 CI 테스트에서 매번 실제 API를 호출하면 느리고 불안정할 수 있습니다.

Apidog의 목업 기능을 사용하면 대표적인 /v1/responses 응답을 저장하고, 프런트엔드나 테스트 환경이 Apidog 목업 URL을 바라보게 할 수 있습니다.

예를 들어 다음과 같은 응답 형태를 목업으로 저장합니다.

{
  "id": "resp_mock123",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "A mock server returns predefined API responses."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 10,
    "output_tokens": 8,
    "total_tokens": 18
  }
}

이후 앱은 실제 OpenAI API 대신 Apidog 목업 URL에서 동일한 JSON 구조를 받을 수 있습니다.

이 접근의 장점은 다음과 같습니다.

토큰 비용 없이 UI 개발 가능
네트워크 장애와 무관하게 테스트 가능
응답 구조를 고정해 결정론적 테스트 가능
실제 API 계약 변경 시 목업만 업데이트 가능

일반적인 목업 방식은 목업 API 설명서에서 확인할 수 있습니다.

실제 엔드포인트 테스트와 목업은 목적이 다릅니다.

실제 엔드포인트 테스트: OpenAI API 계약 확인
목업: 빠르고 오프라인이며 결정론적인 개발 환경 제공

둘 다 같은 Apidog 프로젝트에서 관리할 수 있습니다.

자주 묻는 질문

Responses API가 Chat Completions를 대체하나요?

강제 대체는 아닙니다. OpenAI는 Responses API를 Chat Completions의 진화로 설명하며 새 프로젝트에 권장하지만, Chat Completions는 폐기 날짜 없이 계속 지원됩니다.

기존 앱은 한 번에 모두 옮기기보다 사용자 흐름 단위로 점진적으로 마이그레이션하는 것이 안전합니다.

Assistants API는 폐기 예정이며, 2026년에 서비스 종료될 예정입니다.

`store`와 `previous_response_id`의 차이는 무엇인가요?

store는 OpenAI가 응답 객체를 저장할지 여부를 제어합니다. 기본값은 true이며, 저장된 응답은 이후 대화 상태를 이어가는 데 사용할 수 있습니다.

previous_response_id는 새 요청을 이전 응답에 연결하는 필드입니다.

상태 저장 대화를 만들려면 다음처럼 사용합니다.

{
  "model": "gpt-5.5",
  "input": "Continue from the previous answer.",
  "previous_response_id": "resp_abc123"
}

상태 비저장 동작이 필요하면 다음처럼 설정합니다.

{
  "model": "gpt-5.5",
  "input": "Answer without storing this response.",
  "store": false
}

어떤 모델이 Responses API를 지원하나요?

OpenAI의 현재 범용 모델은 Responses API와 작동하도록 설계되었지만, 사용 가능 여부는 계정과 모델 권한에 따라 달라집니다.

권장 절차는 다음과 같습니다.

OpenAI 대시보드에서 사용 가능한 모델을 확인합니다.
모델 이름을 요청 본문에 넣습니다.
Apidog 또는 curl로 테스트 요청을 보냅니다.
응답의 model 필드를 확인합니다.

모델 이름을 코드에 하드코딩하기 전에 실제 키로 호출 가능한지 검증하세요.

코드 작성 없이 내장 도구를 테스트할 수 있나요?

네. Apidog에서 JSON 본문에 tools 배열을 추가하고 요청을 보내면 됩니다.

예:

{
  "model": "gpt-5.5",
  "input": "Search the web and summarize the result.",
  "tools": [
    {
      "type": "web_search"
    }
  ]
}

그다음 output 배열에 도구 호출 항목이 나타나는지 어설션합니다.

예:

output[*].type contains web_search_call

SDK 없이 HTTP 요청만으로 OpenAI의 도구 호출 동작을 확인할 수 있습니다. 에이전트 도구 호출을 더 넓은 범위에서 테스트하려면 OpenAPI 스펙에서 API 테스트 컬렉션을 생성하는 방법을 참고하세요.

마무리

Responses API의 기본 구현 흐름은 다음과 같습니다.

POST /v1/responses로 요청을 보냅니다.
input과 instructions로 모델 동작을 제어합니다.
응답의 output[0].content[0].text에서 텍스트를 읽습니다.
검색이나 코드 실행이 필요하면 tools 배열을 추가합니다.
대화를 이어가려면 이전 응답의 id를 previous_response_id로 전달합니다.
상태 비저장이 필요하면 store: false를 사용합니다.

Responses API는 Chat Completions와 응답 형태가 다릅니다. 따라서 이전 API의 구조를 가정하지 말고 실제 JSON 계약을 직접 확인하는 것이 안전합니다.

Apidog를 사용하면 하나의 프로젝트에서 요청을 만들고, API 키를 환경 변수로 관리하고, 중첩된 output 필드에 어설션을 추가하고, 오프라인 개발을 위한 응답 목업까지 구성할 수 있습니다.

Apidog를 다운로드한 뒤 /v1/responses 요청을 테스트 컬렉션으로 저장해 통합이 실제로 어떤 응답을 받는지 검증하세요.

OpenAI 구조화된 출력 활용 방법

Rihpig — Fri, 26 Jun 2026 03:12:17 +0000

이 가이드를 따라 하면 OpenAI 구조화된 출력을 코드에서 호출하고, JSON Schema와 strict: true로 응답 형식을 고정하며, Apidog에서 요청/검증/목업까지 테스트 컬렉션으로 관리할 수 있습니다.

오늘 Apidog를 사용해 보세요

시작하기 전에 필요한 것

구조화된 출력은 모델 응답이 제공한 JSON Schema를 따르도록 생성 결과를 제한합니다. strict: true와 함께 스키마를 전달하면 필수 키, 타입, enum 값이 스키마와 일치하는 응답을 받을 수 있습니다.

준비물은 다음과 같습니다.

OPENAI_API_KEY로 설정된 OpenAI API 키
엄격한 스키마 강제를 지원하는 모델
원하는 응답 형식을 설명하는 JSON Schema
응답 계약을 검증할 API 테스트 환경

올바른 모델 선택

구조화된 출력은 GPT-4o 제품군부터 GPT-5 시리즈까지 OpenAI의 최신 모델에서 사용할 수 있습니다. OpenAI 문서는 현재 최신 플래그십 모델(gpt-5.5, 이 글 작성 시점 기준)에서 새 프로젝트를 시작하는 것을 권장합니다.

이전 모델과 gpt-3.5 시대 모델은 JSON 모드를 지원하지만, 엄격한 스키마 강제는 지원하지 않습니다. strict: true에 의존한다면 배포 전에 사용하려는 정확한 모델 ID가 구조화된 출력을 지원하는지 확인하십시오.

OpenAI에는 혼동하기 쉬운 두 기능이 있습니다.

JSON 모드

{
  "response_format": {
    "type": "json_object"
  }
}

JSON 모드는 출력이 구문적으로 유효한 JSON임을 보장합니다. 하지만 필드, 타입, 필수 키, enum 값은 보장하지 않습니다.

구조화된 출력

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "strict": true
    }
  }
}

구조화된 출력은 유효한 JSON을 생성하고, 동시에 스키마 준수까지 강제합니다. 새 작업에는 일반적으로 구조화된 출력을 사용하는 것이 더 안전합니다.

	JSON 모드	구조화된 출력 (엄격 모드)
매개변수	`response_format: {"type":"json_object"}`	`response_format`에 `type: "json_schema"`, `strict: true`
유효한 JSON	예	예
스키마 일치 여부	아니요	예
필수 필드 강제 여부	아니요	예
타입 및 열거형 강제 여부	아니요	예
하위에서 여전히 검증 필요	항상	권장됨

API 참고 사항:

Chat Completions API는 response_format을 사용합니다.
Responses API는 text.format 아래에 type: "json_schema"를 사용합니다.
스키마 규칙은 동일하지만 필드 경로가 다르므로, 사용하는 엔드포인트의 최신 문서를 확인하십시오.

첫 번째 요청 보내기

예제로 지원 티켓을 구조화된 레코드로 추출해 보겠습니다.

다음 요청은 사용자의 자연어 문의를 support_ticket 스키마에 맞는 JSON으로 반환하도록 강제합니다.

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "system",
        "content": "Extract the ticket into the schema."
      },
      {
        "role": "user",
        "content": "My checkout 500s every time I use a saved card. Started today. Account: acct_8842."
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "support_ticket",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "summary": {
              "type": "string"
            },
            "category": {
              "type": "string",
              "enum": ["billing", "bug", "account", "other"]
            },
            "severity": {
              "type": "integer"
            },
            "account_id": {
              "anyOf": [
                { "type": "string" },
                { "type": "null" }
              ]
            }
          },
          "required": ["summary", "category", "severity", "account_id"],
          "additionalProperties": false
        }
      }
    }
  }'

핵심 설정은 다음 세 가지입니다.

{
  "type": "json_schema",
  "strict": true,
  "additionalProperties": false
}

type: "json_schema": 구조화된 출력 사용
strict: true: 스키마 준수 강제
additionalProperties: false: 정의되지 않은 키 생성 차단

응답 읽기

모델은 스키마와 일치하는 JSON 문자열을 content로 반환합니다.

예상 응답 예시는 다음과 같습니다.

{
  "summary": "Checkout returns HTTP 500 when paying with a saved card",
  "category": "bug",
  "severity": 3,
  "account_id": "acct_8842"
}

account_id는 다음처럼 string 또는 null을 허용합니다.

"account_id": {
  "anyOf": [
    { "type": "string" },
    { "type": "null" }
  ]
}

구조화된 출력에서는 일반적인 의미의 선택적 필드가 없습니다. 키는 항상 존재해야 하며, 값이 없을 수 있는 필드는 null 허용으로 모델링합니다.

스키마를 지원되는 하위 집합 안에 유지하기

구조화된 출력은 JSON Schema 전체가 아니라 하위 집합을 사용합니다. 스키마를 작성할 때 다음 규칙을 지키십시오.

1. 루트는 객체여야 합니다

최상위 레벨은 배열이나 문자열이 될 수 없습니다.

잘못된 예:

{
  "type": "array",
  "items": {
    "type": "string"
  }
}

권장 방식:

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": ["items"],
  "additionalProperties": false
}

2. 모든 속성은 `required`에 포함되어야 합니다

구조화된 출력에서는 모든 속성이 required에 있어야 합니다.

선택적 값을 표현하려면 null을 허용하십시오.

{
  "type": "object",
  "properties": {
    "phone": {
      "anyOf": [
        { "type": "string" },
        { "type": "null" }
      ]
    }
  },
  "required": ["phone"],
  "additionalProperties": false
}

3. 모든 객체에 `additionalProperties: false`를 설정하십시오

모델이 스키마에 없는 키를 추가하지 못하도록 모든 객체에 설정합니다.

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "id": { "type": "string" }
      },
      "required": ["id"],
      "additionalProperties": false
    }
  },
  "required": ["user"],
  "additionalProperties": false
}

4. 스키마 크기를 제한하십시오

스키마에는 크기 제한이 있습니다.

약 100개의 객체 속성
최대 5단계 중첩

깊고 넓은 스키마는 거부될 수 있으므로, 가능한 한 평평하게 설계하십시오.

5. 일부 검증 키워드는 보장되지 않습니다

다음과 같은 유효성 검사 전용 키워드는 모델이 보장하지 않을 수 있습니다.

pattern
format
minLength
minimum

예를 들어 이메일 형식, 정규식, 숫자 범위 같은 비즈니스 규칙은 응답을 받은 뒤 애플리케이션 코드나 테스트에서 다시 검증해야 합니다.

oneOf/anyOf/allOf로 선택적 또는 유니온 필드를 모델링해 본 적이 있다면 같은 방식으로 접근하면 됩니다. 스키마는 구조를 제한하고, 실제 값의 의미는 별도로 검증합니다.

6. 첫 호출은 느릴 수 있습니다

새 스키마로 첫 요청을 보내면 스키마 컴파일 시간이 필요합니다. 일반적으로 몇 초가 걸리며, 복잡한 스키마는 최대 1분까지 걸릴 수 있습니다. 이후에는 캐시되어 더 빨라집니다.

거부 및 잘림 처리

구조화된 출력에서도 항상 content에 스키마 형태의 JSON이 들어오는 것은 아닙니다.

모델이 안전하지 않은 요청을 거부하면 메시지에 refusal 필드가 포함될 수 있습니다. JSON을 파싱하기 전에 먼저 분기하십시오.

import json

msg = response.choices[0].message

if msg.refusal:
    handle_refusal(msg.refusal)
else:
    ticket = json.loads(msg.content)

이 방식은 응답 텍스트에서 사과 문구를 검색하는 것보다 안정적입니다.

또한 다음 상황에서는 응답이 스키마를 만족하지 못할 수 있습니다.

max_tokens에 도달해 JSON이 중간에서 잘림
구조화된 출력이 지원하지 않는 병렬 도구 호출 사용

도구 호출과 함께 사용할 때는 다음처럼 병렬 호출을 비활성화하십시오.

{
  "parallel_tool_calls": false
}

Apidog에서 테스트하는 방법

엄격 모드는 생성 시점에 스키마를 강제합니다. 하지만 테스트를 생략해도 된다는 뜻은 아닙니다.

다음 변경은 언제든 발생할 수 있습니다.

모델 변경
프롬프트 변경
스키마 변경
required 배열 수정
거부 처리 경로 변경
하위 서비스의 계약 변경

이런 변경을 CI에서 감지하려면 API 응답이 계약과 일치하는지 테스트해야 합니다. 이때 Apidog를 사용할 수 있습니다.

역할을 명확히 나누면 다음과 같습니다.

OpenAI 구조화된 출력: 스키마에 맞는 JSON 생성
Apidog: 받은 응답이 예상 스키마와 일치하는지 검증

Apidog가 모델에 스키마를 강제하는 것은 아닙니다. Apidog는 응답을 검증하고, 계약 위반을 프로덕션이 아니라 테스트 단계에서 발견하도록 도와줍니다.

Apidog 테스트 워크플로

1. Chat Completions 요청 만들기

Apidog에서 OpenAI Chat Completions 요청을 생성합니다.

요청 본문에는 앞에서 사용한 response_format 블록을 그대로 넣습니다.

{
  "model": "gpt-5.5",
  "messages": [
    {
      "role": "system",
      "content": "Extract the ticket into the schema."
    },
    {
      "role": "user",
      "content": "My checkout 500s every time I use a saved card. Started today. Account: acct_8842."
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_ticket",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "summary": { "type": "string" },
          "category": {
            "type": "string",
            "enum": ["billing", "bug", "account", "other"]
          },
          "severity": { "type": "integer" },
          "account_id": {
            "anyOf": [
              { "type": "string" },
              { "type": "null" }
            ]
          }
        },
        "required": ["summary", "category", "severity", "account_id"],
        "additionalProperties": false
      }
    }
  }
}

반복 실행할 수 있도록 컬렉션에 저장하십시오.

2. 응답 스키마 검증 추가하기

Apidog에서 응답 검증을 추가합니다.

검증 대상은 다음과 같습니다.

summary가 문자열인지
category가 billing, bug, account, other 중 하나인지
severity가 정수인지
account_id가 문자열 또는 null인지
스키마에 없는 추가 필드가 없는지

Apidog는 응답을 JSON Schema에 대해 검증할 수 있으므로, OpenAI에 전달한 스키마와 동일한 스키마를 테스트에도 사용하십시오.

3. CI에서 컬렉션 실행하기

모델, 프롬프트, 스키마가 변경될 때마다 컬렉션을 실행하도록 파이프라인에 추가합니다.

목표는 단순합니다.

스키마가 깨지면 테스트 실패
응답 계약이 바뀌면 빌드 실패
하위 서비스가 잘못된 페이로드를 받기 전에 감지

4. 목업 API로 하위 소비자 테스트하기

실제 OpenAI 호출을 붙이기 전에도 하위 소비자를 개발할 수 있습니다.

Apidog에서 목업 API를 설정하고, 동일한 스키마를 만족하는 샘플 응답을 반환하도록 구성하십시오.

이 방식은 다음 상황에서 유용합니다.

토큰을 사용하지 않고 프론트엔드 개발
OpenAI 호출이 준비되기 전 통합 테스트
CI에서 안정적인 테스트 데이터 사용
하위 서비스의 계약 검증

동일한 스키마를 따르는 목업을 먼저 사용하고, 준비가 되면 실제 OpenAI 호출로 교체하면 됩니다. Apidog를 다운로드하면 요청, 어설션, 목업을 한 곳에서 구성할 수 있습니다.

자주 묻는 질문

구조화된 출력이 있으면 JSON 모드는 사용 중단되었나요?

아니요. JSON 모드는 여전히 작동하며 유효한 JSON을 보장합니다.

다만 스키마를 강제하지 않습니다. 새 코드에서는 strict: true를 사용하는 구조화된 출력이 더 강력한 선택입니다.

JSON 모드는 다음 경우에만 고려하십시오.

사용하는 모델이 엄격 모드를 지원하지 않음
고정된 응답 형태가 필요 없음
직접 후처리 검증을 수행할 계획이 있음

스키마의 루트가 배열일 수 있나요?

아니요. 최상위 레벨은 객체여야 합니다.

배열이 필요하면 객체 속성으로 감싸십시오.

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": ["items"],
  "additionalProperties": false
}

필드를 선택 사항으로 만드는 방법은 무엇입니까?

구조화된 출력에서는 모든 속성이 required에 있어야 합니다.

따라서 선택 사항은 “키가 없음”이 아니라 “값이 null일 수 있음”으로 모델링합니다.

{
  "anyOf": [
    { "type": "string" },
    { "type": "null" }
  ]
}

키는 항상 존재하고, 값만 null이 될 수 있습니다.

엄격 모드에서는 유효성 검사를 완전히 건너뛰어도 되나요?

형태 검사는 대부분 줄일 수 있습니다. 하지만 비즈니스 유효성 검사는 여전히 필요합니다.

특히 다음은 별도로 확인하십시오.

정규식 패턴
이메일/URL 같은 포맷
숫자 범위
문자열 길이
도메인별 허용 값
거부 응답
잘린 응답

JSON Schema가 익숙하지 않다면 JSON Schema 입문서를 먼저 확인하고, 배포마다 검증을 실행하십시오.

어떤 모델을 사용해야 합니까?

구조화된 출력은 GPT-4o 및 이후 모델, GPT-5 시리즈에서 작동합니다. OpenAI 문서는 현재 플래그십 모델에 새 프로젝트를 집중하도록 안내합니다.

엄격 모드 지원은 모델 버전별로 다를 수 있으므로, 사용하려는 정확한 모델 ID가 strict: true를 지원하는지 확인한 뒤 의존하십시오.

마무리

구현 흐름은 다음과 같습니다.

엄격 모드를 지원하는 모델을 선택합니다.
response_format.type을 json_schema로 설정합니다.
strict: true를 활성화합니다.
루트 객체, required, additionalProperties: false 규칙을 지킵니다.
선택적 필드는 null 허용으로 모델링합니다.
refusal과 잘림 응답을 분기 처리합니다.
값 수준 비즈니스 규칙은 별도로 검증합니다.
Apidog에서 요청, 응답 검증, 목업을 구성하고 CI에서 실행합니다.

구조화된 출력은 모델 응답의 형태를 고정합니다. 테스트는 그 형태가 계속 유지되는지 증명합니다.

오픈AI 배치 API 사용법

Rihpig — Thu, 25 Jun 2026 10:07:59 +0000

이 가이드에서는 OpenAI 배치 API를 사용해 수천 개의 모델 요청을 하나의 비동기 작업으로 실행하고, 결과를 50% 할인된 토큰 비용으로 가져오는 구현 흐름을 다룹니다. JSONL 파일을 만들고, 배치를 제출하고, 상태를 폴링하고, 결과를 다운로드한 뒤, 프로덕션에 연결하기 전에 Apidog에서 각 단계를 검증합니다. 작업이 사용자와 실시간으로 상호작용해야 한다면 배치 대신 동기 API를 사용하고, Apidog로 ChatGPT API를 테스트하는 흐름이 더 적합합니다.

오늘 Apidog를 사용해 보세요

배치 API란 무엇이며 언제 사용해야 할까요?

배치 API는 지연을 허용할 수 있는 대량 모델 호출을 처리하기 위한 비동기 엔드포인트입니다.

일반적인 동기 호출은 프롬프트마다 HTTP 요청을 보냅니다. 배치 API는 여러 요청을 하나의 JSONL 파일로 묶어 업로드한 뒤, 하나의 배치 작업으로 제출합니다. 이후 작업 상태를 폴링하고, 완료되면 출력 파일을 다운로드합니다.

배치 API의 핵심 이점은 두 가지입니다.

동기 API 대비 입력 및 출력 토큰 모두 50% 할인
실시간 트래픽과 분리된 별도 속도 제한 풀 사용

단점은 지연 시간입니다. OpenAI는 배치가 24시간 이내에 완료된다고 보장합니다. 많은 작업은 더 빨리 끝날 수 있지만, 시스템은 24시간 상한을 기준으로 설계해야 합니다.

배치 API는 다음과 같은 오프라인 대량 작업에 적합합니다.

과거 데이터 백로그 분류 또는 태그 지정
전체 코퍼스에 대한 임베딩 생성
제품 설명, 요약, 번역 등 대량 콘텐츠 생성
데이터셋 기반 평가 스위트 또는 모델 비교 실행

반대로 사용자가 응답을 기다리는 기능에는 사용하지 마세요. 채팅 UI, 자동 완성, 라이브 에이전트는 동기식 엔드포인트가 필요합니다. 여러 모델 또는 에이전트 구성을 한 번에 생성하는 경우에는 배치 처리가 잘 맞습니다. 관련 예시는 배치 처리로 100개 이상의 에이전트 구성 생성 가이드를 참고하세요.

전체 흐름

배치 API 구현은 크게 네 단계입니다.

단계	엔드포인트	수행 작업
1. 업로드	`POST /v1/files`	`purpose: "batch"`와 함께 `.jsonl` 파일을 업로드하고 파일 ID를 받습니다
2. 생성	`POST /v1/batches`	파일 ID, 대상 엔드포인트, 완료 기간을 제출합니다
3. 폴링	`GET /v1/batches/{id}`	`status`가 `completed`가 될 때까지 확인합니다
4. 검색	`GET /v1/files/{id}/content`	`output_file_id`로 결과 파일을 다운로드합니다

준비물은 다음과 같습니다.

OpenAI API 키
요청을 담은 JSONL 파일
curl, Apidog 등 HTTP 요청을 실행하고 응답을 확인할 도구

환경 변수로 API 키를 설정합니다.

export OPENAI_API_KEY="your_api_key"

1단계: JSONL 요청 파일 만들기

입력 파일은 JSONL 형식입니다. 각 줄은 하나의 독립적인 요청입니다.

각 줄에는 다음 필드가 필요합니다.

필드	설명
`custom_id`	결과와 원본 요청을 매칭하기 위한 고유 ID
`method`	일반적으로 `POST`
`url`	실행할 대상 엔드포인트. 예: `/v1/chat/completions`
`body`	실제 API 요청 본문

예를 들어 감정 분류 작업을 배치로 실행하려면 requests.jsonl 파일을 다음처럼 만들 수 있습니다.

{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Classify the sentiment of: 'shipping was slow but the product is great'"}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4.1-mini", "messages": [{"role": "user", "content": "Classify the sentiment of: 'returned it the same day'"}]}}

중요한 점은 custom_id입니다. 출력 결과는 입력 순서대로 반환된다는 보장이 없습니다. 따라서 결과를 원본 요청과 매칭할 때 줄 번호가 아니라 custom_id를 기준으로 처리해야 합니다.

제약 조건도 확인하세요.

단일 배치: 최대 50,000개 요청
파일 크기: 최대 200MB
파일 내 custom_id: 고유해야 함

2단계: JSONL 파일 업로드

파일 API에 purpose="batch"로 JSONL 파일을 업로드합니다.

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="batch" \
  -F file="@requests.jsonl"

응답에서 id를 확인합니다.

{
  "id": "file-abc123",
  "object": "file",
  "purpose": "batch"
}

이 id가 다음 단계에서 사용할 input_file_id입니다.

3단계: 배치 생성

업로드한 파일 ID로 배치 작업을 생성합니다.

curl https://api.openai.com/v1/batches \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h",
    "metadata": {
      "job": "sentiment-backfill"
    }
  }'

endpoint 값은 JSONL 각 줄의 url과 일치해야 합니다.

예를 들어 JSONL에서 url이 /v1/chat/completions라면 배치 생성 요청의 endpoint도 /v1/chat/completions여야 합니다.

지원되는 대상에는 다음이 포함됩니다.

/v1/chat/completions
/v1/responses
/v1/embeddings
/v1/completions
/v1/moderations

metadata는 선택 사항입니다. 최대 16개의 키-값 쌍을 넣을 수 있으며, 작업 추적이나 비용 분류에 유용합니다.

배치 생성 응답 예시는 다음과 같습니다.

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "created_at": 1733452800,
  "metadata": {
    "job": "sentiment-backfill"
  }
}

여기서 저장해야 할 값은 id입니다. 이후 상태 조회에 사용합니다.

export BATCH_ID="batch_abc123"

4단계: 배치 상태 폴링

배치는 처음에 validating 상태로 시작합니다. 이후 처리 상태에 따라 값이 변경됩니다.

curl https://api.openai.com/v1/batches/$BATCH_ID \
  -H "Authorization: Bearer $OPENAI_API_KEY"

주요 상태는 다음과 같습니다.

상태	의미
`validating`	실행 전 입력 파일을 검증 중
`in_progress`	요청 처리 중
`finalizing`	실행이 끝났고 출력 파일 준비 중
`completed`	완료. 결과 다운로드 가능
`failed`	유효성 검사 실패. 요청은 실행되지 않음
`expired`	24시간 내 모든 요청이 완료되지 않음
`cancelling` / `cancelled`	취소 요청 중 또는 취소 완료

in_progress 상태에서는 request_counts로 진행률을 확인할 수 있습니다.

{
  "request_counts": {
    "total": 50000,
    "completed": 31500,
    "failed": 12
  }
}

폴링은 너무 자주 하지 마세요. 웹훅을 기다리는 방식이 아니므로, 몇 초 단위가 아니라 몇 분 간격으로 확인하는 패턴이 적합합니다.

간단한 폴링 스크립트 예시는 다음과 같습니다.

while true; do
  curl -s https://api.openai.com/v1/batches/$BATCH_ID \
    -H "Authorization: Bearer $OPENAI_API_KEY" | jq '{id, status, request_counts, output_file_id, error_file_id}'

  sleep 120
done

잘못 제출한 배치는 취소할 수 있습니다.

curl -X POST https://api.openai.com/v1/batches/$BATCH_ID/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY"

5단계: 결과 파일 다운로드

status가 completed가 되면 배치 객체에 output_file_id가 포함됩니다.

{
  "status": "completed",
  "output_file_id": "file-output456",
  "error_file_id": "file-error789"
}

출력 파일을 다운로드합니다.

curl https://api.openai.com/v1/files/file-output456/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" > results.jsonl

결과도 JSONL 형식입니다. 각 줄에는 원래 요청의 custom_id와 응답 정보가 들어 있습니다.

출력 예시는 다음과 비슷합니다.

{"custom_id":"req-1","response":{"status_code":200,"request_id":"request-1","body":{"choices":[{"message":{"role":"assistant","content":"Mixed positive"}}]}}}
{"custom_id":"req-2","response":{"status_code":200,"request_id":"request-2","body":{"choices":[{"message":{"role":"assistant","content":"Negative"}}]}}}

오류가 있는 요청은 error_file_id가 가리키는 파일에서 확인합니다.

curl https://api.openai.com/v1/files/file-error789/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" > errors.jsonl

결과 처리 시에는 반드시 custom_id를 기준으로 원본 데이터와 조인하세요. 출력 줄 순서를 신뢰하면 안 됩니다.

비용과 처리 시간 설계

배치 API의 비용 모델은 단순합니다.

입력 토큰 50% 할인
출력 토큰 50% 할인
최대 24시간 처리 시간 허용

따라서 다음 작업에는 적합합니다.

야간 배치
일회성 백필
비동기 리포트 생성
대량 평가 작업
대량 임베딩 생성

반대로 제품의 핵심 실시간 경로에는 적합하지 않습니다.

운영 시 고려할 점은 다음과 같습니다.

할인은 지원되는 모델의 입력 및 출력 토큰 모두에 적용됩니다.
24시간은 목표 시간이 아니라 상한선입니다.
expired가 되면 완료된 요청은 반환 및 청구되고, 완료되지 않은 요청은 반환되지 않습니다.
배치 작업은 별도 대기열 토큰 제한을 사용하므로 실시간 API 속도 제한을 직접 잠식하지 않습니다.
대량 작업은 반값이어도 총액이 커질 수 있으므로 metadata로 작업별 비용을 추적하세요.

동기식 API의 속도 제한을 함께 다뤄야 한다면 GPT API 속도 제한 및 테스트 방법을 참고하세요. 작업별 비용 할당이 필요하다면 OpenAI 지출에 대한 비용 할당 플레이북을 확인할 수 있습니다.

Apidog에서 배치 API 테스트하기

배치 API는 일반적인 단일 채팅 호출보다 실패 지점이 많습니다.

JSONL 형식 오류
누락된 custom_id
잘못된 url
배치 endpoint와 JSONL url 불일치
파일 업로드 실패
폴링 로직 오류
결과 파일 파싱 오류

자동화하기 전에 Apidog에서 전체 수명 주기를 수동으로 검증하면 불필요한 24시간 왕복을 줄일 수 있습니다. Apidog는 OpenAI SDK가 아니라 API 요청을 구성, 실행, 확인, 모의할 수 있는 API 플랫폼입니다.

권장 테스트 흐름은 다음과 같습니다.

1. JSONL 형식 검증

업로드 전에 각 줄이 다음 필드를 포함하는지 확인합니다.

{
  "custom_id": "req-1",
  "method": "POST",
  "url": "/v1/chat/completions",
  "body": {}
}

특히 다음을 확인하세요.

custom_id가 비어 있지 않은지
파일 내 custom_id가 중복되지 않는지
method가 POST인지
url이 배치 생성 시 사용할 endpoint와 같은지
body.model이 있는지
messages 또는 대상 엔드포인트에 필요한 필드가 있는지

2. 파일 업로드 요청 만들기

Apidog에서 POST /v1/files 요청을 만들고 multipart form-data로 설정합니다.

키	값
`purpose`	`batch`
`file`	`requests.jsonl`

응답의 id를 환경 변수로 저장합니다.

예:

input_file_id = file-abc123

3. 배치 생성 요청 실행

POST /v1/batches 요청을 만들고 다음 본문을 보냅니다.

{
  "input_file_id": "{{input_file_id}}",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "metadata": {
    "job": "sentiment-backfill"
  }
}

응답에서 다음 필드를 확인합니다.

status가 validating인지
endpoint가 기대한 값인지
input_file_id가 업로드한 파일 ID인지
id가 반환되었는지

반환된 배치 ID도 환경 변수로 저장합니다.

batch_id = batch_abc123

4. 상태 폴링 요청 구성

GET /v1/batches/{{batch_id}} 요청을 만들고 주기적으로 실행합니다.

확인할 필드는 다음입니다.

status
request_counts.total
request_counts.completed
request_counts.failed
output_file_id
error_file_id

status가 completed가 되면 output_file_id를 저장합니다.

5. 결과 다운로드 요청 만들기

GET /v1/files/{{output_file_id}}/content 요청을 실행해 결과 JSONL을 다운로드합니다.

오류 파일이 있으면 error_file_id도 동일하게 다운로드합니다.

6. 취소 및 실패 경로 테스트

정상 경로만 테스트하지 마세요. 다음 케이스도 미리 확인하는 것이 좋습니다.

일부러 잘못된 JSONL 파일을 업로드해 failed 상태 확인
endpoint와 JSONL url을 다르게 설정해 오류 처리 확인
POST /v1/batches/{id}/cancel로 취소 요청 확인
error_file_id가 있는 경우 파싱 로직 확인

출력 파일은 나중에 도착하므로, 개발 중에는 모의 API를 만들어 샘플 배치 객체와 결과 파일을 반환하도록 구성할 수 있습니다. 이렇게 하면 실제 24시간 작업을 기다리거나 토큰을 소비하지 않고 결과 다운로드 및 파싱 로직을 구현할 수 있습니다.

팀이 사양 우선 방식으로 작업한다면 OpenAPI 사양에서 직접 테스트 컬렉션을 생성하고 CI에서 배치 엔드포인트를 회귀 테스트 범위에 포함할 수도 있습니다.

자주 묻는 질문

실제로 배치는 얼마나 걸리나요?

OpenAI는 배치가 24시간 이내에 완료된다고 보장합니다. 실제로는 더 빨리 끝나는 작업도 많지만, 시스템은 24시간 상한을 기준으로 설계해야 합니다.

작업이 기간 내 완료되지 않으면 배치는 expired 상태가 됩니다. 이 경우 완료된 요청만 반환되고 청구됩니다.

할인은 어느 정도인가요?

배치 API는 동기식 엔드포인트 대비 입력 및 출력 토큰 모두 50% 고정 할인을 제공합니다.

기능이나 작업 단위로 비용을 나누어 추적하려면 metadata를 사용해 배치 작업을 태깅하세요. 비용 분할 방식은 비용 할당 플레이북에서 확인할 수 있습니다.

배치에서 어떤 엔드포인트를 실행할 수 있나요?

JSONL의 url과 배치 생성 요청의 endpoint가 모두 같은 대상을 가리켜야 합니다.

지원되는 대상에는 다음이 포함됩니다.

/v1/chat/completions
/v1/responses
/v1/embeddings
/v1/completions
/v1/moderations
이미지 및 비디오 관련 엔드포인트

지원 목록은 시간이 지나면서 바뀔 수 있으므로 OpenAI의 최신 문서를 확인하세요.

결과 순서가 입력 순서와 다른 이유는 무엇인가요?

의도된 동작입니다. 출력 JSONL은 입력 줄 순서를 보장하지 않습니다.

그래서 모든 요청에 고유한 custom_id가 필요합니다. 결과 처리 로직은 반드시 custom_id를 기준으로 원본 요청과 응답을 매칭해야 합니다.

결론

OpenAI 배치 API의 구현 흐름은 다음과 같습니다.

요청을 JSONL 파일로 작성
POST /v1/files로 업로드
POST /v1/batches로 배치 생성
GET /v1/batches/{id}로 상태 폴링
output_file_id로 결과 다운로드
custom_id 기준으로 결과 매칭

배치 API는 실시간 응답이 필요 없는 대량 작업에서 토큰 비용을 절반으로 줄일 수 있는 실용적인 방법입니다. 다만 JSONL 형식과 폴링, 오류 파일 처리까지 포함해 전체 수명 주기를 검증해야 안정적으로 운영할 수 있습니다.

자동화 전에 Apidog를 다운로드해 업로드, 생성, 폴링, 취소, 결과 다운로드 흐름을 먼저 실행해 보세요. 잘못된 JSONL 한 줄 때문에 24시간을 낭비하는 상황을 줄일 수 있습니다.

구글 ADK (에이전트 개발 키트) 이해 및 실전 가이드

Rihpig — Thu, 25 Jun 2026 08:08:43 +0000

Google ADK는 AI 에이전트를 구축, 평가 및 배포하기 위한 오픈 소스 프레임워크입니다. Agentspace와 같은 Google 제품에서 실제 에이전트를 지원하며, OpenAI Agents SDK와 유사하게 에이전트 정의, 도구 연결, 실행, 평가까지 다룹니다. 이 글에서는 ADK의 핵심 구성 요소를 빠르게 정리하고, Apidog로 에이전트가 호출하는 API를 테스트하는 방법까지 구현 관점에서 살펴봅니다.

오늘 Apidog를 사용해 보세요

Google ADK란 무엇인가

ADK는 Agent Development Kit의 약자입니다. Google은 2025년 4월 Google Cloud Next에서 ADK를 공개했으며, 목적은 에이전트의 전체 수명 주기를 코드로 다루는 것입니다.

ADK로 할 수 있는 일은 다음과 같습니다.

에이전트 정의
도구 연결
여러 에이전트 구성
에이전트 동작 평가
프로덕션 배포

ADK는 Python으로 시작했고, 이후 Java가 추가되었으며 Go 및 TypeScript 지원도 뒤따랐습니다. Google이 Agentspace 및 Customer Engagement Suite에서 사용하는 에이전트 기반과 연결되어 있으므로, 단순한 실험용 SDK가 아니라 프로덕션 워크로드를 염두에 둔 프레임워크입니다.

ADK는 모델에 구애받지 않지만 Google 생태계에 최적화되어 있습니다. Gemini 및 Vertex AI Model Garden의 모델과 잘 맞고, LiteLLM을 통해 Anthropic, Meta, Mistral 등 다른 제공업체의 모델도 연결할 수 있습니다.

Gemini 및 Vertex AI 생태계에서 ADK의 위치

ADK를 이해하려면 세 레이어로 나누어 보는 것이 좋습니다.

모델: Gemini, Vertex AI Model Garden 모델, 또는 LiteLLM을 통한 외부 모델이 추론을 수행합니다.
프레임워크: ADK가 에이전트 정의, 도구 연결, 다중 에이전트 오케스트레이션을 담당합니다.
런타임: Vertex AI Agent Engine은 프로덕션에서 에이전트를 실행하기 위한 관리형 런타임입니다. 필요하면 Cloud Run 또는 다른 컨테이너 런타임에도 배포할 수 있습니다.

즉, ADK는 개발자가 직접 다루는 코드 레이어입니다. Gemini는 지능을 제공하고, Vertex AI Agent Engine은 관리형 실행 환경을 제공합니다. 세 가지를 함께 사용할 수도 있고, ADK를 로컬에서 실행한 뒤 다른 컨테이너 플랫폼에 배포할 수도 있습니다.

핵심 개념

ADK로 구현할 때 가장 자주 사용하는 구성 요소는 다음입니다.

1. 에이전트

ADK의 기본 단위는 LLM 기반 에이전트입니다. Python에서는 google.adk.agents에서 가져옵니다. 클래스 이름은 LlmAgent이고, Agent는 이를 위한 편리한 별칭입니다.

에이전트를 만들 때 주로 지정하는 값은 다음입니다.

name: 에이전트 이름
model: 사용할 모델
instruction: 에이전트의 역할과 행동 규칙
tools: 에이전트가 호출할 수 있는 함수 목록
sub_agents: 위임 가능한 하위 에이전트 목록

from google.adk.agents import Agent

def get_exchange_rate(base: str, target: str) -> dict:
    """Return the exchange rate between two currencies."""
    # 실제 환율 API를 여기에서 호출합니다.
    return {"base": base, "target": target, "rate": 1.08}

currency_agent = Agent(
    name="currency_exchange_agent",
    model="gemini-2.0-flash",
    instruction="You help users convert between currencies. Stick to the facts.",
    tools=[get_exchange_rate],
)

이 예제에서 currency_agent는 사용자 요청을 해석하고, 필요하면 get_exchange_rate() 함수를 도구로 호출합니다.

2. 도구

도구는 에이전트가 텍스트 생성 외의 작업을 수행하는 방법입니다. ADK에서는 일반 Python 함수가 도구가 될 수 있습니다.

모델은 다음 정보를 보고 도구 사용 여부를 판단합니다.

함수 이름
타입 힌트
독스트링
반환 구조

따라서 도구 함수는 명확하게 작성해야 합니다.

def search_order(order_id: str) -> dict:
    """Find an order by order_id and return its status, items, and total price."""
    # 실제 주문 API 호출
    return {
        "order_id": order_id,
        "status": "shipped",
        "items": ["keyboard", "mouse"],
        "total": 120.0,
    }

ADK는 자체 함수 외에도 다음을 지원합니다.

google_search 같은 내장 도구
코드 실행 도구
Model Context Protocol, MCP
LangChain 또는 LlamaIndex 같은 외부 라이브러리 래핑
다른 에이전트를 도구처럼 사용하는 패턴

실제 프로젝트에서는 대부분의 도구가 내부 REST API, 외부 SaaS API, LLM 엔드포인트 등을 호출합니다. 따라서 도구가 호출하는 API의 응답 형식을 테스트하고 목업하는 과정이 중요합니다.

3. 다중 에이전트 시스템

단일 에이전트로도 많은 작업을 처리할 수 있지만, ADK는 여러 에이전트를 조합하는 구조에 강점이 있습니다.

예를 들어 여행 계획 에이전트를 만든다면 다음처럼 역할을 나눌 수 있습니다.

항공권 검색 에이전트
호텔 검색 에이전트
일정 생성 에이전트
최종 응답을 조합하는 코디네이터 에이전트

ADK는 결정적 제어를 위한 워크플로 에이전트도 제공합니다.

SequentialAgent: 하위 에이전트를 순서대로 실행
ParallelAgent: 하위 에이전트를 동시에 실행
LoopAgent: 조건이 충족될 때까지 반복 실행

LLM 기반 라우팅과 이러한 워크플로 에이전트를 함께 사용하면, 작업을 여러 전문 에이전트에 분산하고 결과를 병합하는 구조를 만들 수 있습니다.

4. 러너

프로덕션 코드에서는 에이전트를 직접 호출하기보다 Runner를 사용합니다. Runner는 ADK의 실행 엔진입니다.

Runner가 담당하는 작업은 다음과 같습니다.

세션 관리
이벤트 흐름 처리
상태 업데이트
모델 호출
도구 호출 조정

개발 중에는 CLI를 사용하면 빠르게 확인할 수 있습니다.

adk run

adk run은 대화형 터미널 세션을 시작합니다.

adk web

adk web은 브라우저에서 에이전트와 대화하고 각 단계를 검사할 수 있는 로컬 UI를 엽니다.

5. 평가 및 배포

ADK에는 평가 기능이 포함되어 있습니다. 단순히 결과를 눈으로 확인하는 대신, 예상 응답이나 예상 실행 경로에 대해 에이전트 동작을 검증할 수 있습니다.

이 기능은 다음 상황에서 중요합니다.

프롬프트를 수정할 때
도구 응답 형식이 바뀔 때
모델을 교체할 때
하위 에이전트 구성을 변경할 때

배포 옵션은 크게 두 가지입니다.

관리형 배포: Vertex AI Agent Engine 사용
휴대 가능한 배포: 컨테이너로 패키징 후 Cloud Run 또는 다른 컨테이너 플랫폼에 배포

고수준 예시: 여행 계획 다중 에이전트

다음은 두 개의 전문 에이전트와 하나의 코디네이터 에이전트를 구성하는 예시입니다.

from google.adk.agents import Agent

flights = Agent(
    name="flight_agent",
    model="gemini-2.0-flash",
    instruction="Find flight options for the user's route and dates.",
    tools=[search_flights],   # 항공권 API를 래핑하는 함수
)

hotels = Agent(
    name="hotel_agent",
    model="gemini-2.0-flash",
    instruction="Find hotel options near the destination.",
    tools=[search_hotels],    # 호텔 API를 래핑하는 함수
)

trip_planner = Agent(
    name="trip_planner",
    model="gemini-2.0-flash",
    instruction="Plan a trip. Delegate flight and hotel lookups to your sub-agents.",
    sub_agents=[flights, hotels],
)

이 구조에서 trip_planner는 사용자 요청을 해석한 뒤, 항공권이 필요하면 flight_agent에, 숙소가 필요하면 hotel_agent에 위임합니다.

각 하위 에이전트는 도구 함수를 통해 실제 API를 호출합니다. 개발 중에는 adk web으로 실행 흐름을 확인하고, 프로덕션에서는 Runner 또는 관리형 런타임을 통해 실행할 수 있습니다.

ADK 대 OpenAI Agents SDK

둘 다 도구 호출, 핸드오프, 추적 기능을 갖춘 코드 우선 에이전트 프레임워크입니다. 차이는 주로 생태계에 있습니다.

	Google ADK	OpenAI Agents SDK
기본 모델	Gemini, Vertex AI	OpenAI 모델
기타 모델	Vertex AI Model Garden, LiteLLM	LiteLLM 및 기타
언어	Python, Java, Go, TypeScript	Python, JavaScript/TypeScript
다중 에이전트	서브 에이전트 + 순차, 병렬, 루프 워크플로 에이전트	도구로서의 에이전트 및 핸드오프
관리형 런타임	Vertex AI Agent Engine	직접 구성
도구 프로토콜	MCP, 내장 도구, 함수 도구	MCP, 함수 도구

이미 Google Cloud와 Vertex AI를 사용하고 있다면 ADK가 자연스럽습니다. OpenAI 모델과 도구 체인을 중심으로 구축한다면 OpenAI Agents SDK가 더 적합할 수 있습니다. 둘 다 MCP를 지원하므로 동일한 도구 서버를 공유하는 구조도 가능합니다.

ADK를 사용해야 하는 경우

다음 상황이라면 ADK를 고려할 만합니다.

Google Cloud 기반으로 구축하고 있다.
Gemini와 Vertex AI Agent Engine을 함께 사용하고 싶다.
순차, 병렬, 루프 기반의 명시적 다중 에이전트 제어가 필요하다.
평가 기능을 프레임워크 안에서 다루고 싶다.
모델 교체 가능성을 열어두고 싶다.
Vertex AI Model Garden 또는 LiteLLM을 통해 여러 모델을 연결해야 한다.

반대로 다음 상황이라면 ADK가 과할 수 있습니다.

단일 프롬프트와 한두 개의 함수 호출로 충분하다.
다른 모델 생태계에 이미 강하게 묶여 있다.
에이전트 오케스트레이션보다 단순 API 호출 자동화가 목적이다.

에이전트 프레임워크는 구조를 제공합니다. 하지만 작업이 작을 때는 그 구조 자체가 복잡도가 될 수 있습니다.

Apidog의 역할: 에이전트가 호출하는 API 테스트 및 목업

ADK는 에이전트를 오케스트레이션합니다. 하지만 에이전트가 의존하는 외부 API 자체를 테스트하지는 않습니다.

실제 에이전트의 도구는 보통 다음 중 하나를 호출합니다.

LLM 엔드포인트
결제 API
내부 마이크로서비스
타사 데이터 API
검색 API
주문, 사용자, 재고 같은 사내 API

이 API 중 하나가 예상과 다른 응답을 반환하면 에이전트는 잘못된 입력을 기반으로 추론합니다. 이 문제는 에이전트 로그만 보고 추적하기 어렵습니다.

여기서 Apidog의 역할은 ADK를 대체하는 것이 아닙니다. Apidog는 에이전트 프레임워크가 아니라, 에이전트 도구가 호출하는 API를 설계, 목업, 테스트하는 레이어입니다.

ADK 개발 중 Apidog를 사용하는 방법

1. 도구가 호출하는 엔드포인트 목업

실제 API가 아직 준비되지 않았거나, 호출 비용과 속도 제한이 부담된다면 목업 API를 먼저 만들 수 있습니다.

예를 들어 에이전트 도구가 다음 API를 호출한다고 가정합니다.

GET /exchange-rate?base=USD&target=KRW

Apidog에서 성공 응답을 다음처럼 정의할 수 있습니다.

{
  "base": "USD",
  "target": "KRW",
  "rate": 1380.25
}

그리고 에러 케이스도 별도로 만들 수 있습니다.

{
  "error": "unsupported_currency",
  "message": "The target currency is not supported."
}

이렇게 하면 실제 API 없이도 에이전트가 정상 응답과 오류 응답을 모두 처리하는지 테스트할 수 있습니다.

2. 도구 응답 형태 검증

에이전트 도구는 반환 필드에 민감합니다. 예를 들어 에이전트가 rate 필드를 기대하는데 API가 exchangeRate로 바뀌면, 에이전트는 잘못된 응답을 생성할 수 있습니다.

API 단언을 사용하면 응답 계약을 테스트할 수 있습니다.

검증해야 할 항목은 다음과 같습니다.

필수 필드 존재 여부
필드 타입
상태 코드
에러 응답 형식
배열 또는 객체 구조
인증 실패 응답

에이전트 코드에서 문제가 터지기 전에 API 테스트에서 계약 변경을 감지하는 것이 좋습니다.

3. 환경별 키 관리

개발, 스테이징, 프로덕션마다 API 키와 베이스 URL이 다릅니다. Apidog 환경 기능을 사용하면 같은 API 요청을 환경별 변수로 실행할 수 있습니다.

예:

{{base_url}}/exchange-rate?base=USD&target=KRW

환경별 값:

dev.base_url = https://dev-api.example.com
staging.base_url = https://staging-api.example.com
prod.base_url = https://api.example.com

이 패턴을 사용하면 ADK 도구가 호출하는 API를 배포 단계별로 더 안정적으로 검증할 수 있습니다.

더 자세한 흐름은 AI 에이전트의 도구 호출을 테스트하는 방법을 참고하십시오. Apidog를 다운로드하면 단일 엔드포인트 목업부터 바로 시작할 수 있습니다.

자주 묻는 질문

Google ADK는 무료이며 오픈 소스인가요?

네. ADK는 Apache 라이선스 하의 오픈 소스 GitHub 저장소로 제공됩니다. 프레임워크 자체는 무료로 로컬에서 실행할 수 있습니다.

다만 호출하는 모델, Vertex AI Agent Engine 같은 관리형 런타임, 클라우드 인프라 비용은 별도로 발생합니다.

ADK는 Gemini에서만 작동하나요?

아니요. ADK는 Gemini 및 Vertex AI에 최적화되어 있지만 모델에 구애받지 않습니다. Vertex AI Model Garden 및 LiteLLM을 통해 Anthropic, Meta, Mistral 등 다른 제공업체의 모델도 사용할 수 있습니다.

Gemini는 기본 선택지에 가깝지만 필수는 아닙니다.

ADK는 어떤 언어를 지원하나요?

Python이 가장 먼저 출시되었고 가장 완성도가 높습니다. 이후 Java가 추가되었으며 Go 및 TypeScript 지원도 뒤따랐습니다.

현재 가장 넓은 기능 범위를 원한다면 Python으로 시작하는 것이 안전합니다.

ADK 에이전트가 의존하는 API는 어떻게 테스트하나요?

에이전트와 API를 분리해서 테스트하는 것이 좋습니다.

실무에서는 다음 순서가 유용합니다.

도구가 호출할 API의 요청/응답 계약을 정의합니다.
Apidog에서 목업 응답을 만듭니다.
에이전트를 목업 API에 연결합니다.
정상 응답, 오류 응답, 빈 응답을 테스트합니다.
API 단언으로 응답 구조가 깨지지 않는지 검증합니다.
실제 API로 전환하기 전에 환경 변수를 정리합니다.

LLM 엔드포인트 테스트 패턴은 ChatGPT API를 테스트하는 방법에서도 확인할 수 있습니다.

마무리

Google ADK는 Gemini 및 Vertex AI와 잘 통합되면서도 다른 모델로 확장할 수 있는 에이전트 프레임워크입니다. 하나의 에이전트와 몇 개의 도구로 시작한 뒤, adk web으로 실행 흐름을 확인하고, 필요할 때 서브 에이전트와 관리형 런타임으로 확장하는 방식이 현실적입니다.

에이전트가 외부 API에 의존한다면 API 응답 계약을 먼저 안정화해야 합니다. 도구가 호출하는 엔드포인트를 목업하고, 응답 구조를 단언하고, 환경별 설정을 관리하는 레이어가 필요합니다. 이 부분을 Apidog로 처리하면 ADK 에이전트의 불안정한 동작을 더 일찍 발견할 수 있습니다.

LangGraph란? 상태 저장 AI 에이전트 구축 가이드

Rihpig — Thu, 25 Jun 2026 08:03:05 +0000

대부분의 에이전트 코드는 간단한 스크립트로 시작하지만, 재시도·분기·도구 호출이 추가되는 순간 유지보수가 어려워집니다. LLM을 연결하고 도구를 제공한 뒤 워크플로우가 루프를 돌거나, 조건에 따라 분기하거나, 사람의 승인을 기다려야 한다면 직선형 파이프라인만으로는 부족합니다. LangGraph는 에이전트를 공유 상태를 가진 그래프로 모델링해 이러한 제어 흐름을 명시적으로 다루는 프레임워크입니다. 이 글에서는 LangGraph의 핵심 개념, 최소 구현 예시, 영속성 설정, 그리고 에이전트가 실제 서비스를 호출할 때 API 테스트를 어디에 적용해야 하는지를 실무 관점에서 정리합니다.

오늘 Apidog를 사용해 보세요

LangGraph란 무엇인가

LangGraph는 장기 실행되는 상태 저장 에이전트를 만들기 위한 저수준 오케스트레이션 프레임워크이자 런타임입니다. LangChain 팀인 LangChain Inc에서 만들었지만, LangChain과는 별도의 라이브러리로 사용할 수 있습니다.

설치는 단순합니다.

pip install -U langgraph

LangGraph의 핵심은 에이전트를 그래프로 표현하는 것입니다.

노드: 모델 호출, 도구 실행, 데이터 변환 같은 작업 단위
엣지: 다음에 실행할 노드를 결정하는 연결
상태: 모든 노드가 읽고 업데이트하는 공유 객체
루프: 도구 실행 후 다시 모델로 돌아가는 순환 흐름

기존 체인 방식은 보통 1단계 → 2단계 → 3단계 → 종료 형태입니다. 반면 LangGraph는 현재 상태를 보고 다음 경로를 선택할 수 있습니다. 예를 들어 모델이 도구 호출을 요청하면 도구 노드로 이동하고, 더 이상 호출할 도구가 없으면 종료할 수 있습니다.

LangGraph가 해결하는 문제

에이전트 워크플로우는 대부분 선형이 아닙니다. 일반적인 흐름은 다음과 같습니다.

사용자의 요청을 받습니다.
모델이 다음 행동을 결정합니다.
필요한 경우 도구 API를 호출합니다.
결과를 다시 모델에 전달합니다.
완료 여부를 판단합니다.
완료되지 않았다면 다시 반복합니다.

이 흐름을 중첩된 if 문과 while 문으로 직접 구현하면 빠르게 복잡해집니다. LangGraph는 다음 기능을 구조적으로 제공합니다.

정지 조건이 있는 루프: 무한 루프를 피하면서 작업 완료 전까지 반복
상태 기반 분기: 모델 응답, 도구 결과, 사용자 입력에 따라 라우팅
영속성: 충돌, 타임아웃, 재시작 후에도 마지막 체크포인트에서 재개
Human-in-the-loop: 실행 중간에 사람이 상태를 확인하거나 수정한 뒤 계속 진행
스트리밍: 토큰과 중간 실행 결과를 실시간으로 UI에 전달

즉, LangGraph는 에이전트를 단순 함수 호출 묶음이 아니라 상태 머신으로 다룰 수 있게 해줍니다.

핵심 개념: 그래프, 상태, 노드, 엣지

LangGraph를 구현할 때는 네 가지 개념만 먼저 잡으면 됩니다.

1. 상태(State)

상태는 전체 실행 동안 공유되는 데이터 구조입니다. 보통 TypedDict 또는 LangGraph가 제공하는 MessagesState를 사용합니다.

MessagesState는 채팅 메시지 목록을 관리하는 기본 상태 스키마입니다.

2. 노드(Node)

노드는 일반 Python 함수입니다. 현재 상태를 입력으로 받고, 상태에 병합할 업데이트를 반환합니다.

def call_model(state):
    response = model.invoke(state["messages"])
    return {"messages": [response]}

3. 엣지(Edge)

엣지는 노드 사이의 이동 경로입니다.

add_edge()는 항상 같은 다음 노드로 이동합니다.
add_conditional_edges()는 상태를 보고 다음 노드를 동적으로 결정합니다.

4. START와 END

START는 그래프 실행 시작점이고, END는 종료 지점입니다.

최소 LangGraph 예제

아래 예제는 모델이 도구 호출을 요청하면 tools 노드로 이동하고, 도구 실행 후 다시 모델로 돌아가는 기본 루프입니다.

from langgraph.graph import StateGraph, START, END, MessagesState

def call_model(state: MessagesState):
    response = model.invoke(state["messages"])
    return {"messages": [response]}

def should_continue(state: MessagesState) -> str:
    last = state["messages"][-1]
    return "tools" if last.tool_calls else END

builder = StateGraph(MessagesState)

builder.add_node("model", call_model)
builder.add_node("tools", tool_node)

builder.add_edge(START, "model")
builder.add_conditional_edges("model", should_continue)
builder.add_edge("tools", "model")  # 도구 실행 후 다시 모델로 루프

graph = builder.compile()

중요한 부분은 이 줄입니다.

builder.add_edge("tools", "model")

도구 실행이 끝난 뒤 모델로 돌아가기 때문에 에이전트는 다음을 계속 판단할 수 있습니다.

추가 도구 호출이 필요한가?
사용자에게 답변할 수 있는가?
오류가 발생했는가?
종료해야 하는가?

이 순환 구조가 LangGraph를 사용하는 핵심 이유입니다.

영속성 및 human-in-the-loop 설정

LangGraph에서 체크포인터를 사용하면 각 단계 후 상태 스냅샷을 저장할 수 있습니다. 이후 같은 thread_id로 호출하면 마지막 상태를 복원합니다.

from langgraph.checkpoint.memory import InMemorySaver

graph = builder.compile(checkpointer=InMemorySaver())

config = {
    "configurable": {
        "thread_id": "user-42"
    }
}

graph.invoke(
    {"messages": [user_message]},
    config
)

InMemorySaver는 개발 환경에서 테스트하기에 적합합니다. 재시작 후에도 상태를 유지해야 한다면 데이터베이스 기반 저장소를 사용해야 합니다. LangGraph는 단일 서버용 SQLite와 다중 인스턴스 환경용 Postgres 기반 저장 옵션을 제공합니다.

이 구조를 사용하면 human-in-the-loop 흐름도 쉽게 설계할 수 있습니다.

예를 들어 다음과 같은 승인 게이트를 만들 수 있습니다.

모델이 외부 API 호출 계획을 생성합니다.
그래프를 특정 노드에서 일시 중지합니다.
사람이 요청 본문, 대상 API, 비용 등을 확인합니다.
승인 또는 수정 후 같은 체크포인트에서 실행을 재개합니다.

노드 로직에 별도의 저장·복구 코드를 넣지 않아도 런타임이 상태를 관리합니다.

스트리밍을 UI에 연결하기

LangGraph는 실행 중 모델 토큰과 노드 업데이트를 스트리밍할 수 있습니다. UI에서는 단순 로딩 스피너 대신 다음 정보를 표시할 수 있습니다.

현재 실행 중인 노드
모델의 부분 응답
도구 호출 요청
도구 실행 결과
최종 응답

에이전트 디버깅에서는 최종 답변만 보는 것보다 중간 상태를 보는 것이 훨씬 중요합니다. 특히 조건부 엣지가 예상과 다른 경로를 선택하는 경우, 스트리밍 로그가 문제 원인을 찾는 데 도움이 됩니다.

LangGraph와 LangChain의 관계

LangChain은 모델 래퍼, 프롬프트 템플릿, 검색기, 문서 로더, 다양한 제공업체 통합을 포함하는 더 넓은 도구 키트입니다. LangGraph는 그중 에이전트 실행 흐름을 담당하는 오케스트레이션 레이어에 가깝습니다.

LangGraph를 사용하기 위해 반드시 LangChain을 알아야 하는 것은 아닙니다. 노드 내부에서 원하는 모델 클라이언트를 직접 호출할 수 있습니다. 다만 LangChain의 모델 및 도구 추상화가 편리하기 때문에 많은 팀이 두 라이브러리를 함께 사용합니다.

	LangChain	LangGraph
역할	구성 요소 및 통합	오케스트레이션 및 런타임
제어 흐름	선형 체인	순환 및 분기가 있는 그래프
내장 상태	제한적	공유, 유형 지정, 내구성
영속성 / 재개	주요 초점 아님	체크포인터 + 스레드 ID
가장 적합한 용도	모델 호출 및 도구 구성	상태 저장, 다단계 에이전트

현재 LangGraph v1.0 라인에서는 사전 빌드된 에이전트 헬퍼의 위치가 변경되고 있으므로, 예전 코드를 복사하기 전에 설치된 버전과 공식 참조 문서에서 정확한 임포트 경로를 확인해야 합니다.

더 넓은 관점에서 에이전트 구조를 설계하려면 사용자 정의 AI 에이전트 구축 가이드도 참고할 수 있습니다.

LangGraph Platform 및 Studio

오픈 소스 라이브러리만으로도 로컬 개발은 가능합니다. 하지만 디버깅과 배포 단계에서는 LangGraph Studio와 LangGraph Platform이 도움이 됩니다.

LangGraph Studio

LangGraph Studio는 시각적 에이전트 IDE입니다. 그래프 구조를 렌더링하고, 실행 경로와 각 노드의 상태를 확인할 수 있습니다.

조건부 라우팅이나 루프가 있는 에이전트에서는 로그만으로 흐름을 추적하기 어렵습니다. Studio를 사용하면 실제로 어떤 노드를 거쳤는지 시각적으로 확인할 수 있습니다.

LangGraph Platform

LangGraph Platform은 에이전트를 API 엔드포인트로 배포하고, 장기 실행을 위한 영속성 및 호스팅 옵션을 제공하는 관리형 배포 레이어입니다. 자체 호스팅부터 클라우드 관리형 옵션까지 선택할 수 있습니다.

라이브러리 사용에 필수는 아니지만, 프로덕션에서 에이전트 실행 인프라를 직접 운영하고 싶지 않을 때 유용합니다.

LangGraph를 언제 사용해야 하는가

LangGraph는 모든 LLM 작업에 필요한 도구가 아닙니다. 다음 조건 중 하나라도 해당하면 사용을 검토할 만합니다.

도구 호출 후 결과를 보고 다시 판단해야 한다.
모델 출력에 따라 다음 단계가 달라진다.
실행 시간이 길고, 중간에 실패해도 재개해야 한다.
실행 도중 사람의 승인이나 수정이 필요하다.
여러 하위 에이전트 또는 액터가 같은 상태를 공유한다.
에이전트의 실행 경로를 추적하고 디버깅해야 한다.

반대로 다음 작업에는 과할 수 있습니다.

단일 프롬프트로 텍스트를 요약하는 작업
한 번의 모델 호출로 끝나는 분류 작업
짧고 고정된 선형 파이프라인

분기와 루프가 없다면 LangGraph의 구조는 오히려 오버헤드가 될 수 있습니다.

API 테스트 및 목업(Mocking)의 적용 지점

LangGraph는 에이전트의 실행 흐름을 오케스트레이션하지만, 에이전트가 호출하는 API 자체를 검증하지는 않습니다. 실제 에이전트는 보통 다음 API에 의존합니다.

LLM API
검색 API
CRM 또는 내부 백엔드 API
결제, 주문, 사용자 관리 API
벡터 데이터베이스 API
사내 도구 API

이 지점에서 Apidog를 사용할 수 있습니다.

1. 실제 API 대신 목업 API로 그래프 로직 테스트

모든 테스트 실행에서 실제 API를 호출하면 비용과 속도 문제가 생깁니다. 특히 LLM API는 토큰 비용과 속도 제한의 영향을 받습니다.

개발 중에는 에이전트가 의존하는 API를 목업(mock)해 그래프 로직을 빠르게 반복할 수 있습니다.

예를 들어 도구 노드가 다음 API를 호출한다고 가정합니다.

GET /users/{id}/orders

목업 응답을 고정해두면 LangGraph 테스트에서 항상 같은 결과를 받을 수 있습니다.

{
  "userId": "user-42",
  "orders": [
    {
      "id": "order-1001",
      "status": "shipped"
    }
  ]
}

이렇게 하면 모델 라우팅과 조건부 엣지를 검증할 때 외부 시스템 상태에 흔들리지 않습니다.

2. 응답 스키마를 단언(assert)해 노드 오류 방지

LangGraph 노드는 보통 API 응답 형태를 가정합니다.

예를 들어 노드가 status 필드를 읽는다고 가정합니다.

def route_by_order_status(state):
    order = state["order"]
    if order["status"] == "shipped":
        return "notify_user"
    return "check_again"

그런데 백엔드 API가 status를 orderStatus로 바꾸면 에이전트는 잘못된 분기로 이동하거나 예외를 낼 수 있습니다.

API 단언(assertions)을 사용하면 다음 조건을 사전에 검증할 수 있습니다.

필수 필드가 존재하는가?
필드 타입이 예상과 일치하는가?
상태 코드가 올바른가?
응답 시간이 기준 이하인가?
에러 응답 형식이 일관적인가?

API 계약이 깨졌을 때 그래프 실행 중에 발견하는 것이 아니라, API 테스트 단계에서 먼저 감지하는 것이 안전합니다.

3. 환경별 키와 엔드포인트 분리

에이전트는 개발, 스테이징, 프로덕션 환경에서 서로 다른 API 키와 엔드포인트를 사용합니다. 이 값을 노드 코드에 직접 넣으면 보안과 유지보수 문제가 생깁니다.

환경 변수 또는 API 테스트 도구의 환경 관리 기능을 사용해 다음 값을 분리해야 합니다.

BASE_URL
API_KEY
LLM_API_KEY
MOCK_SERVER_URL
STAGING_SERVER_URL

완전한 에이전트 중심 워크플로우가 필요하다면 AI 에이전트를 위한 Apidog 테스트 하네스를 참고할 수 있습니다.

중요한 점은 역할 분리입니다. LangGraph는 에이전트를 오케스트레이션하고, Apidog는 에이전트가 호출하는 API를 테스트하고 목업합니다.

자주 묻는 질문

LangGraph가 LangChain을 대체하나요?

아닙니다. LangGraph는 오케스트레이션 런타임이고, LangChain은 모델·도구·검색기·통합을 포함하는 더 넓은 구성 요소 집합입니다. 둘은 같은 팀에서 만든 별도 라이브러리이며, 함께 사용할 수도 있고 LangGraph만 단독으로 사용할 수도 있습니다.

LangGraph를 시작하기 위해 LangChain을 알아야 하나요?

아닙니다. StateGraph를 정의하고, 노드와 엣지를 추가하고, 노드 내부에서 원하는 모델 클라이언트를 호출하면 됩니다. LangChain의 모델 래퍼는 편리하지만 필수는 아닙니다.

LangGraph는 호출 간에 어떻게 내용을 기억하나요?

체크포인터를 사용합니다. 체크포인터로 그래프를 컴파일하고 thread_id를 전달하면 LangGraph가 각 단계 후 상태 스냅샷을 저장합니다. 이후 같은 thread_id로 호출하면 해당 상태를 복원합니다.

에이전트가 호출하는 API는 어떻게 테스트하나요?

그래프와 분리해서 테스트하고 목업해야 합니다. 개발 중에는 LLM 및 도구 엔드포인트를 목업해 비용과 지연을 줄이고, 응답 스키마를 단언해 필드 변경으로 인한 노드 오류를 방지해야 합니다. ChatGPT API 테스트 가이드는 인증, 스트리밍, 도구 호출처럼 에이전트가 의존하는 주요 부분을 다룹니다.

요약

LangGraph는 루프, 분기, 영속성, human-in-the-loop가 필요한 에이전트에 적합한 오케스트레이션 프레임워크입니다. 워크플로우를 공유 상태 기반 그래프로 모델링하고, 체크포인터로 실행 상태를 저장하며, 필요하면 Studio와 Platform으로 디버깅 및 배포를 보완할 수 있습니다.

다만 LangGraph는 API 계약을 검증하지 않습니다. 에이전트가 호출하는 API는 별도로 목업하고 테스트해야 합니다. 개발 비용을 줄이고 도구 호출의 신뢰성을 높이려면 Apidog에서 엔드포인트를 목업하고 응답을 단언하세요. 에이전트가 실제 엔드포인트를 호출하기 전에 테스트 환경을 구성하려면 Apidog를 다운로드하십시오.

gRPC API 테스트를 위한 최고의 grpcurl 대체 도구 (GUI 및 CLI)

Rihpig — Thu, 25 Jun 2026 07:00:44 +0000

grpcurl은 gRPC 서비스를 빠르게 확인할 때 가장 유용한 명령줄 도구입니다. 하지만 플래그가 많은 터미널 명령만으로는 API를 탐색하고, 스트리밍 호출을 재생하고, 팀원과 요청 예제를 공유하기 어렵습니다. 시각적인 gRPC 클라이언트나 저장된 요청, 환경 변수, 팀 워크플로우까지 지원하는 도구가 필요하다면 아래 6가지 grpcurl 대안을 검토해 보세요.

지금 Apidog를 사용해 보세요

grpcurl이란 무엇이며, 언제 불편해지는가

grpcurl은 gRPC용 curl입니다. 서버 주소, 서비스 이름, 메서드 이름, JSON 요청 본문을 전달하면 gRPC 응답을 터미널에서 확인할 수 있습니다.

기본 사용 흐름은 다음과 같습니다.

grpcurl \
  -plaintext \
  -d '{"id": "123"}' \
  localhost:50051 \
  demo.UserService/GetUser

서버 리플렉션이 켜져 있다면 .proto 파일 없이도 서비스와 메서드를 탐색할 수 있습니다.

grpcurl -plaintext localhost:50051 list
grpcurl -plaintext localhost:50051 list demo.UserService
grpcurl -plaintext localhost:50051 describe demo.UserService.GetUser

리플렉션이 꺼져 있다면 .proto 파일이나 프로토셋 디스크립터를 직접 지정해야 합니다.

grpcurl \
  -plaintext \
  -import-path ./proto \
  -proto user.proto \
  -d '{"id": "123"}' \
  localhost:50051 \
  demo.UserService/GetUser

grpcurl은 다음 작업에 특히 적합합니다.

CI에서 gRPC 헬스 체크 실행
터미널에서 빠른 단항 호출 테스트
셸 스크립트에 gRPC 호출 포함
리플렉션으로 서비스 목록 확인

하지만 실제 개발 워크플로우에서는 다음 지점에서 불편해집니다.

CLI 전용이라 익숙하지 않은 API를 탐색할 때 메서드와 메시지 구조를 직접 확인해야 합니다.
클라이언트 스트리밍, 서버 스트리밍, 양방향 스트리밍은 stdin/stdout 기반이라 메시지 흐름을 시각적으로 보기 어렵습니다.
요청 기록, 컬렉션, 환경 전환 기능이 내장되어 있지 않습니다.
팀원에게 공유하려면 긴 명령어 문자열이나 별도 스크립트를 전달해야 합니다.

즉, grpcurl은 나쁜 도구가 아니라 목적이 명확한 도구입니다. 작업이 “단일 명령 실행”을 넘어 API 탐색, 반복 테스트, 협업으로 확장된다면 아래 대안이 더 적합합니다.

grpcurl 대안 한눈에 보기

도구	인터페이스	스트리밍 지원	리플렉션	최적의 용도
Apidog	GUI 데스크톱	단항, 서버 스트리밍, 클라이언트 스트리밍, 양방향 스트리밍	예	REST, GraphQL, 문서와 함께 gRPC를 시각적으로 테스트
grpcui	웹 UI	단항 + 스트리밍	예	grpcurl 기반 브라우저 프런트엔드
Postman	GUI 데스크톱/웹	단항 + 스트리밍	예	이미 Postman을 사용하는 팀
Kreya	GUI 데스크톱	단항 + 스트리밍	예	gRPC 및 REST 중심 데스크톱 클라이언트
Evans	대화형 CLI	단항 + 스트리밍	예	REPL 스타일 터미널 워크플로우
BloomRPC	GUI 데스크톱	단항 + 스트리밍	제한적	레거시 프로젝트 유지보수

1. Apidog: 시각적인 gRPC 클라이언트

Apidog는 REST, GraphQL, WebSocket, SOAP, gRPC를 하나의 데스크톱 앱에서 다루는 API 플랫폼입니다. gRPC만 별도 터미널에서 테스트하지 않고, 다른 API 프로토콜과 같은 작업 공간에서 관리할 수 있습니다.

gRPC 테스트는 보통 다음 순서로 진행합니다.

Apidog에서 새 gRPC 요청을 생성합니다.
.proto 파일을 가져오거나 서버 리플렉션으로 연결합니다.
서비스와 메서드를 선택합니다.
스키마 기반 요청 필드를 입력합니다.
메타데이터, 인증, 서버 주소를 설정합니다.
단항 또는 스트리밍 호출을 실행합니다.
응답 메시지를 패널에서 확인하고 요청을 저장합니다.

grpcurl에서는 요청을 직접 JSON으로 작성해야 합니다.

grpcurl \
  -plaintext \
  -H "authorization: Bearer $TOKEN" \
  -d '{"user_id":"u_123","include_orders":true}' \
  localhost:50051 \
  demo.UserService/GetUserProfile

Apidog에서는 같은 요청을 폼 기반 UI에서 작성하고 저장할 수 있습니다. .proto 스키마를 기준으로 필드가 렌더링되므로 메시지 구조를 매번 describe로 확인할 필요가 줄어듭니다.

Apidog가 특히 유용한 경우는 다음과 같습니다.

서버 스트리밍 응답을 메시지 단위로 확인해야 할 때
클라이언트 스트리밍 또는 양방향 스트리밍을 반복 테스트해야 할 때
여러 서버 주소를 환경 변수로 전환해야 할 때
인증 헤더나 메타데이터를 요청별로 재사용해야 할 때
REST, GraphQL, gRPC를 같은 프로젝트에서 함께 관리해야 할 때
팀원에게 실행 가능한 요청 예제를 공유해야 할 때

다만 Apidog는 GUI 클라이언트입니다. 셸 파이프라인에서 실행할 수 있는 바이너리가 필요하다면 grpcurl이나 Evans가 더 적합합니다. 반대로 API 탐색, 저장된 요청, 환경 변수, 팀 협업이 중요하다면 Apidog가 더 실용적입니다.

여러 프로토콜을 함께 운영한다면 다중 프로토콜 API 워크플로우를 하나의 도구에서 관리하는 편이 더 단순합니다.

Apidog를 다운로드한 뒤 .proto 파일을 가져오거나 리플렉션으로 연결해 첫 gRPC 호출을 실행해 보세요.

2. grpcui: grpcurl에 가까운 웹 UI

grpcui는 grpcurl과 같은 fullstorydev에서 만든 도구입니다. grpcurl의 동작 방식은 유지하면서 브라우저 기반 UI를 제공합니다.

일반적인 실행 방식은 다음과 같습니다.

grpcui -plaintext localhost:50051

실행하면 로컬 웹 서버가 열리고 브라우저에서 다음 작업을 할 수 있습니다.

서비스 선택
메서드 선택
요청 메시지 입력
메타데이터 설정
단항 및 스트리밍 호출 실행

리플렉션이 꺼져 있다면 .proto 파일을 지정할 수 있습니다.

grpcui \
  -plaintext \
  -import-path ./proto \
  -proto user.proto \
  localhost:50051

grpcui가 적합한 경우는 다음과 같습니다.

grpcurl의 기능은 유지하고 싶지만 브라우저 폼이 필요할 때
로컬 개발 서버를 빠르게 탐색해야 할 때
별도 API 플랫폼 없이 단순한 gRPC UI만 필요할 때

제한점도 명확합니다. grpcui는 gRPC 탐색에 집중된 단일 목적 도구입니다. REST 테스트, 장기적인 컬렉션 관리, 팀 작업 공간, 문서화 워크플로우까지 필요하다면 다른 도구가 더 적합합니다.

설치 및 실행 방법은 grpcui 저장소에서 확인할 수 있습니다.

3. Postman: 기존 Postman 팀을 위한 선택지

Postman은 gRPC 요청을 지원합니다. 이미 팀에서 Postman을 표준 API 도구로 사용하고 있다면, 별도 도구를 도입하기 전에 Postman의 gRPC 기능을 먼저 검토할 만합니다.

기본 흐름은 다음과 같습니다.

Postman에서 gRPC 요청을 생성합니다.
서버 URL을 입력합니다.
.proto 파일을 로드하거나 리플렉션을 사용합니다.
서비스와 메서드를 선택합니다.
요청 메시지, 메타데이터, 인증 정보를 입력합니다.
호출을 실행하고 응답을 확인합니다.
요청을 컬렉션에 저장합니다.

Postman의 장점은 다음과 같습니다.

팀이 이미 익숙한 UI
컬렉션 기반 요청 관리
환경 변수 사용
기존 REST 테스트 워크플로우와의 연결

주의할 점도 있습니다. Postman의 gRPC 경험은 전통적인 REST 경험에 비해 상대적으로 최근에 추가된 기능이며, 팀 규모나 사용 방식에 따라 계정, 클라우드 동기화, 가격 정책을 함께 고려해야 합니다.

더 넓은 API 테스트 도구를 비교하려면 API 테스트를 위한 Postman 대안도 참고할 수 있습니다. Postman의 현재 gRPC 기능은 공식 gRPC 문서에서 확인하세요.

4. Kreya: gRPC와 REST 중심 데스크톱 클라이언트

Kreya는 gRPC와 REST에 중점을 둔 데스크톱 API 클라이언트입니다. .proto 파일과 서버 리플렉션을 지원하고, 스키마 기반 요청 폼을 생성하며, 단항 및 스트리밍 호출을 처리합니다.

Kreya에서 일반적으로 수행하는 작업은 다음과 같습니다.

프로젝트 생성
gRPC 엔드포인트 추가
.proto 파일 또는 리플렉션으로 서비스 로드
요청 작성 및 실행
환경 변수 구성
요청 재사용

Kreya가 적합한 경우는 다음과 같습니다.

gRPC와 REST만 집중적으로 테스트하고 싶을 때
데스크톱 기반의 깔끔한 API 클라이언트가 필요할 때
전체 API 플랫폼보다 가벼운 도구를 원할 때

반대로 모킹, 문서 생성, 설계 협업까지 한 번에 관리하려면 더 넓은 범위의 API 플랫폼이 필요할 수 있습니다.

5. Evans: REPL 스타일 대화형 CLI

Evans는 터미널에서 사용하는 대화형 gRPC 클라이언트입니다. grpcurl처럼 CLI 기반이지만, 긴 명령어를 매번 작성하는 대신 REPL 방식으로 서비스와 메서드를 탐색합니다.

예를 들어 다음처럼 실행할 수 있습니다.

evans --host localhost --port 50051 --reflection repl

REPL 안에서는 패키지, 서비스, 메서드를 선택하고 요청 값을 대화식으로 입력할 수 있습니다.

> show package
> package demo
> show service
> service UserService
> call GetUser

Evans가 적합한 경우는 다음과 같습니다.

터미널 기반 워크플로우를 유지하고 싶을 때
grpcurl 명령어의 긴 플래그 입력이 부담스러울 때
서버 리플렉션으로 빠르게 서비스 구조를 탐색하고 싶을 때
GUI 없이 스트리밍 호출을 테스트해야 할 때

Evans 역시 CLI 도구이므로 시각적인 스트리밍 패널이나 팀 작업 공간은 없습니다. 하지만 터미널 안에서 반복적으로 gRPC를 탐색해야 한다면 grpcurl보다 편한 경우가 많습니다.

설치 방법은 Evans GitHub 저장소를 참고하세요.

6. BloomRPC: 새 프로젝트에는 권장하지 않는 레거시 도구

BloomRPC는 한때 많이 사용되던 오픈 소스 gRPC GUI입니다. 데스크톱 앱에서 .proto 파일을 불러오고, 메서드를 선택하고, 요청을 작성할 수 있었습니다.

하지만 현재는 적극적으로 유지보수되지 않습니다. 따라서 다음 문제가 생길 수 있습니다.

최신 gRPC 기능 대응 부족
의존성 업데이트 지연
OS 호환성 문제
보안 업데이트 부족
팀 워크플로우 확장성 제한

새 프로젝트라면 BloomRPC를 선택하지 않는 것이 좋습니다. 이미 BloomRPC 기반 워크플로우를 물려받았다면 Apidog, grpcui, Postman, Kreya, Evans 중 하나로 마이그레이션 계획을 세우세요.

선택 기준

사용 방식에 따라 도구를 선택하면 됩니다.

시각적인 gRPC 테스트, 저장된 요청, 환경 변수, 팀 공유가 필요하다면: Apidog
grpcurl에 가장 가까운 브라우저 UI가 필요하다면: grpcui
이미 Postman을 표준으로 사용 중이라면: Postman gRPC 지원
gRPC와 REST 중심의 데스크톱 클라이언트가 필요하다면: Kreya
터미널에 머물되 대화형 탐색이 필요하다면: Evans
기존 레거시 환경을 유지보수 중이라면: BloomRPC 상태를 확인하고 마이그레이션 준비

gRPC를 처음부터 끝까지 테스트하는 워크플로우가 필요하다면 gRPC API를 효율적으로 테스트하는 방법을 참고하세요. 명령줄 중심으로 계속 작업한다면 grpc-curl 워크스루가 좋은 출발점입니다.

자주 묻는 질문

grpcurl의 GUI 버전이 있나요?

가장 직접적인 GUI 대안은 grpcui입니다. grpcurl과 같은 계열의 도구이며, 리플렉션과 프로토 처리를 기반으로 브라우저 폼을 제공합니다.

저장된 요청, 환경 변수, 시각적인 스트리밍 응답, 팀 작업 공간까지 필요하다면 Apidog 같은 데스크톱 gRPC 클라이언트가 더 적합합니다.

명령줄 없이 gRPC 스트리밍을 테스트할 수 있나요?

네. Apidog, Postman, Kreya, grpcui는 UI를 통해 gRPC 스트리밍 호출을 지원합니다. 특히 서버 스트리밍의 경우 메시지가 도착하는 흐름을 패널에서 확인할 수 있습니다.

grpcurl과 Evans도 스트리밍을 지원하지만, 메시지 입력과 출력이 터미널 기반입니다.

이 도구들은 `.proto` 파일이 필요한가요?

항상 필요한 것은 아닙니다. 서버 리플렉션이 활성화되어 있으면 클라이언트가 서비스와 메서드를 직접 검색할 수 있습니다.

리플렉션이 꺼져 있다면 .proto 파일이나 컴파일된 프로토셋을 제공해야 합니다. 대부분의 도구는 두 방식을 모두 지원합니다.

API 테스트 전체 관점이 필요하다면 API 테스트 궁극 가이드에서 REST, gRPC, 기타 프로토콜의 테스트 방식을 함께 확인할 수 있습니다.

grpcurl은 여전히 사용할 가치가 있나요?

네. grpcurl은 여전히 다음 작업에 매우 적합합니다.

CI 파이프라인에서 gRPC 상태 확인
셸 스크립트에 gRPC 호출 포함
빠른 단항 요청 테스트
리플렉션 기반 서비스 목록 확인
터미널에서 일회성 디버깅

다만 반복적으로 요청을 저장하고, 스트리밍 응답을 시각적으로 보고, 팀원과 실행 가능한 예제를 공유해야 한다면 GUI 기반 대안을 함께 사용하는 것이 효율적입니다.

결론

grpcurl은 명령줄 gRPC 테스트에 강력한 도구입니다. 스크립트화된 호출, CI 체크, 빠른 터미널 디버깅에는 여전히 좋은 선택입니다.

하지만 익숙하지 않은 서비스를 탐색하고, 스트리밍 메시지를 관찰하고, 요청을 저장하고, 팀과 공유해야 한다면 시각적인 gRPC 클라이언트가 더 빠릅니다. Apidog는 gRPC를 REST, GraphQL, 모킹, 문서화 워크플로우와 함께 관리할 수 있어 여러 프로토콜을 다루는 팀에 특히 유용합니다.

단 하나의 플래그도 작성하지 않고 gRPC 서비스를 테스트하고 싶다면 Apidog를 무료로 사용해보고, .proto 파일을 가져오거나 리플렉션으로 연결해 GUI에서 단항 및 스트리밍 호출을 실행해 보세요.