> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sifi.life/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI SDK & API

> 이 문서는 **[GenAI 개념](/blog/guides/genai-concepts/overview)** 섹션의 일부입니다.

## 2. Agents SDK -- 멀티에이전트 오케스트레이션

### 배경: Swarm에서 Agents SDK로

| 구분    | Swarm (2024.10) | Agents SDK (2025.03)       |
| ----- | --------------- | -------------------------- |
| 성격    | 실험적 교육용 프레임워크   | 프로덕션 레디 SDK                |
| 지원 언어 | Python만         | Python + TypeScript        |
| 모델    | OpenAI만         | 모델 무관(Model-agnostic)      |
| 추적    | 없음              | 내장 Tracing + OpenTelemetry |
| MCP   | 없음              | 네이티브 지원                    |

### 4가지 핵심 구성 요소

#### (1) Agent -- 역할 정의

```python theme={null}
from agents import Agent, Runner

sales_agent = Agent(
    name="Sales Agent",
    instructions="""당신은 영업팀 전문 상담사입니다.
    - 제품 가격, 라이선스, 할인 정책에 대해 정확히 답변하세요.
    - 기술적 질문은 직접 답하지 말고, 기술 상담 에이전트로 넘기세요.""",
    model="gpt-4.1",
    tools=[pricing_tool, crm_lookup_tool],
)
```

#### (2) Handoff -- 에이전트 간 위임

```python theme={null}
from agents import Agent, handoff

tech_agent = Agent(
    name="Tech Support Agent",
    instructions="기술적인 질문에 답변합니다.",
    tools=[docs_search_tool, code_executor_tool],
    handoffs=[handoff(sales_agent)],
)

triage_agent = Agent(
    name="Triage Agent",
    instructions="""사용자 요청을 분류하여 적절한 에이전트로 라우팅하세요.""",
    handoffs=[handoff(sales_agent), handoff(tech_agent)],
)
```

#### (3) Guardrail -- 입출력 안전장치

Guardrail은 에이전트의 입력과 출력을 **자동으로 검증** 합니다. 별도의 Safety Agent가 입력을 판단하고, `tripwire_triggered`로 차단 여부를 결정합니다.

#### (4) Tracing -- 실행 추적

Runner.run()을 호출하면 자동으로 트레이스가 생성되며, OpenTelemetry 프로토콜을 지원하여 기존 관측 인프라에 통합 가능합니다.

### 완성 예제: 멀티에이전트 고객 상담 시스템

```python theme={null}
from agents import Agent, Runner, handoff, trace
import asyncio

order_agent = Agent(
    name="Order Agent",
    instructions="주문 조회, 배송 상태 확인을 담당합니다.",
    tools=[lookup_order],
)

refund_agent = Agent(
    name="Refund Agent",
    instructions="환불, 반품 관련 문의를 처리합니다.",
    tools=[check_refund_policy],
)

triage_agent = Agent(
    name="Triage Agent",
    instructions="""고객 문의를 분류하여 적절한 에이전트로 전달하세요.""",
    handoffs=[handoff(order_agent), handoff(refund_agent)],
)

async def main():
    with trace("customer-support"):
        result = await Runner.run(
            triage_agent,
            "주문번호 ORD-2026-1234 배송이 언제 오나요?"
        )
        print(result.final_output)

asyncio.run(main())
```

***

## 3. Responses API -- Agent의 기반 API

### Chat Completions vs Responses API

| 비교 항목 | Chat Completions API      | Responses API                                                   |
| ----- | ------------------------- | --------------------------------------------------------------- |
| 출시    | 2023.03                   | 2025.03                                                         |
| 패러다임  | 단일 요청-응답                  | **에이전틱 루프**                                                     |
| 도구 호출 | function calling (개발자 구현) | **Built-in tools**                                              |
| 내장 도구 | 없음                        | `web_search`, `file_search`, `code_interpreter`, `computer_use` |

### Built-in Tools 상세

| 도구                 | 용도     | 설명                  |
| ------------------ | ------ | ------------------- |
| `web_search`       | 실시간 검색 | Bing/자체 인덱스 기반 웹 검색 |
| `file_search`      | 파일 검색  | 벡터 스토어에서 RAG 검색     |
| `code_interpreter` | 코드 실행  | Python 샌드박스에서 코드 실행 |
| `computer_use`     | 컴퓨터 제어 | 스크린샷 기반 GUI 자동화     |

> **주의**
> **Assistants API는 2026년 상반기 중 폐기 예정** 입니다. 새로운 Agent 프로젝트는 처음부터 Responses API를 권장합니다.

***

## 4. GPT-4.1 -- Agent 특화 모델

GPT-4.1(2025년 4월)은 OpenAI가 **처음으로 "Agent용"을 명시적으로 표방한** 모델입니다.

| 개선 영역                     | 내용                       |
| ------------------------- | ------------------------ |
| **Instruction Following** | 시스템 프롬프트의 복잡한 규칙을 정확히 준수 |
| **Tool Calling 신뢰성**      | Function calling 정확도 향상  |
| **Long Context 처리**       | 1M 토큰 컨텍스트               |

### 가격 비교

| 모델               | Input (1M tokens) | Output (1M tokens) | 컨텍스트 |
| ---------------- | ----------------- | ------------------ | ---- |
| **GPT-4.1**      | \$2.00            | \$8.00             | 1M   |
| **GPT-4.1 mini** | \$0.40            | \$1.60             | 1M   |
| **GPT-4.1 nano** | \$0.10            | \$0.40             | 1M   |

> **성공**
> **비용 최적화 팁**: Triage Agent에 **nano**, Specialist Agent에 **mini** 또는 **4.1**, 최종 품질 중요한 응답에만 **4.1** 을 사용하면 비용을 90% 이상 절감할 수 있습니다.