OpenAI의 AI 에이전트 도구 사용법 (개발자 API 튜토리얼)

아마도 OpenAI의 최신 혁신, 에이전트를 구축하기 위한 새로운 도구에 대해 들어보셨을 것입니다. OpenAI API로 구동되는 이 도구들은 개발자들이 지능적이고 반응성이 뛰어난 시스템을 만드는 방식을 혁신하고 있습니다. 당신이 숙련된 코더든, 이제 막 시작하는 사람이든 이 블로그 포스트는 OpenAI의 제품을 활용하여 자신의 에이전트를 구축하는 데 필요한 모든 것을 안내할 것입니다.

OpenAI의 새로운 도구가 에이전트를 만드는 데 있어 게임 체인저인 이유

OpenAI는 OpenAI API에 웹 검색 기능 통합을 발표했습니다. 이번 업데이트는 ChatGPT 검색을 지원하는 동일한 모델에 의해 제공되는 빠르고 최신의 답변과 관련 웹 소스에 대한 링크를 도입합니다. 이는 복잡한 작업을 처리하고 실시간 데이터를 가져오며 사용자와 원활하게 상호 작용할 수 있는 에이전틱 시스템을 구축하고자 하는 개발자에게 엄청난 도약입니다.

OpenAI는 Responses API, 웹 검색 기능, 파일 검색 도구, 컴퓨터 사용 기능 및 Agents SDK를 소개했습니다. 이들은 모두 더 똑똑하고 자율적으로 느껴지는 에이전트를 구축하기 위한 강력한 프레임워크를 형성합니다. 새로운 도구는 개발자들이 안전하고 효율적이며 강력한 에이전트를 만드는 데 도움이 되도록 설계되었습니다.

에이전트란 무엇인가요? 간단 요약

AI의 맥락에서 에이전트는 자신의 환경을 인식하고, 결정을 내리며, 특정 목표를 달성하기 위해 행동할 수 있는 자율 시스템 또는 프로그램입니다. 질문에 답하거나, 작업을 수행하거나, 상호 작용을 통해 학습할 수 있는 디지털 사이드킥이라고 생각하시면 됩니다.

OpenAI의 새로운 도구는 개발자들이 OpenAI API를 사용해 이러한 에이전트를 구축할 수 있도록 하여 훨씬 더 똑똑하고 빠르며 웹에 연결된 에이전트를 만들어 줍니다.

시작하기: OpenAI의 Responses API 이해하기

Responses API는 OpenAI의 Chat Completions 및 Assistants API의 최상 기능을 통합한 혁신적인 도구입니다. OpenAI의 이전 API에 익숙하다면, 이 도구가 에이전트 구축 프로세스를 얼마나 간소화하는지 알게 될 것입니다.

시작하려면 OpenAI의 개발자 문서로 이동하세요. Responses API는 복잡한 작업을 실행하기 위해 여러 도구와 모델을 통합할 수 있게 해주며, 질문에 답하는 것부터 다단계 워크플로우를 조정하는 것까지 여러 AI 에이전트를 만드는 데 안성맞춤입니다.

다음과 같이 시작할 수 있습니다:

OpenAI API는 텍스트 생성, 자연어 처리, 컴퓨터 비전 등을 위한 최신 AI 모델에 대한 간단한 인터페이스를 제공합니다. 이 예는 ChatGPT를 사용할 때와 같이 프롬프트에서 텍스트 출력을 생성합니다.

import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
    model: "gpt-4o",
    input: "유니콘에 대한 한 문장짜리 자장가 이야기를 작성하세요."
});

console.log(response.output_text);

이미지 입력 분석하기

모델에 이미지 입력을 제공할 수도 있습니다. 영수증을 스캔하거나, 스크린샷을 분석하거나, 컴퓨터 비전을 통해 실제 세계의 객체를 찾을 수 있습니다.

import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
    model: "gpt-4o",
    input: [
        { role: "user", content: "이 사진에서 어떤 두 팀이 경기를 하고 있나요?" },
        {
            role: "user",
            content: [
                {
                    type: "input_image",
                    image_url: "https://upload.wikimedia.org/wikipedia/commons/3/3b/LeBron_James_Layup_%28Cleveland_vs_Brooklyn_2018%29.jpg",
                }
            ],
        },
    ],
});

console.log(response.output_text);

도구로 모델 확장하기

새로운 데이터와 기능을 모델에 추가하여 도구를 사용하세요. 자신의 커스텀 코드를 호출하거나 OpenAI의 강력한 내장 도구 중 하나를 사용할 수 있습니다. 이 예시는 웹 검색을 사용하여 모델이 최신 인터넷 정보를 접근할 수 있도록 합니다.

import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
    model: "gpt-4o",
    tools: [{ type: "web_search_preview" }],
    input: "오늘의 긍정적인 뉴스 기사는 무엇이었나요?",
});

console.log(response.output_text);

눈부신 AI 경험 제공하기

새로운 Realtime API 또는 서버 전송 스트리밍 이벤트를 사용하여 사용자에게 고성능, 저지연의 경험을 구축할 수 있습니다.

import { OpenAI } from "openai";
const client = new OpenAI();

const stream = await client.responses.create({
    model: "gpt-4o",
    input: [
        {
            role: "user",
            content: "‘더블 버블 목욕’을 열 번 빨리 말하세요.",
        },
    ],
    stream: true,
});

for await (const event of stream) {
    console.log(event);
}

에이전트 구축하기

OpenAI 플랫폼을 사용하여 사용자를 대신해 행동을 취할 수 있는 에이전트를 구축하세요—예를 들어 컴퓨터 제어를 포함합니다. Python용 Agent SDK를 사용하여 백엔드에서 오케스트레이션 로직을 생성하세요.

from agents import Agent, Runner
import asyncio

spanish_agent = Agent(
    name="스페인어 에이전트",
    instructions="당신은 스페인어만 사용합니다.",
)

english_agent = Agent(
    name="영어 에이전트",
    instructions="당신은 영어만 사용합니다.",
)

triage_agent = Agent(
    name="트리아지 에이전트",
    instructions="요청의 언어에 따라 적절한 에이전트에게 전달합니다.",
    handoffs=[spanish_agent, english_agent],
)


async def main():
    result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?")
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

# ¡Hola! Estoy bien, gracias por preguntar. ¿Y tú, cómo estás?

API에 내장된 도구는 이러한 작업을 원활하게 실행하여 시간과 노력을 절약해 줍니다. 게다가 안전성과 신뢰성을 염두에 두고 설계되었으므로 개발자에게 큰 이점이 됩니다.

스마트 에이전트를 위한 웹 검색

OpenAI의 웹 검색 도구는 GPT-4o 검색 및 GPT-4o 미니 검색과 같은 모델에 의해 구동되며, 에이전트가 인터넷에서 최신 정보를 가져오고 출처를 인용할 수 있게 해줍니다. 이는 정확하고 실시간의 답변을 제공해야 하는 에이전트를 구축하는 데 특히 유용합니다.

웹 검색 도구는 OpenAI API를 통해 프리뷰 형태로 제공되며, 인상적인 정확성을 자랑합니다. OpenAI의 SimpleQA 기준에서 GPT-4o 검색은 90%의 점수를 기록하며, GPT-4o 미니 검색은 88%를 기록합니다. 매우 높은 정확도입니다!

당신의 에이전트에 웹 검색을 구현하려면 OpenAI의 가이드를 확인하세요. 간단한 요약은 다음과 같습니다:

• 도구 통합: Responses API를 사용하여 에이전트에 웹 검색 기능을 활성화하세요.
• 쿼리 생성: 에이전트를 설계하여 웹 검색 도구에 특정 쿼리를 보내고 관련 결과를 검색하도록 합니다.
• 결과 표시: 에이전트가 사용자에게 내용과 출처 링크를 제공하도록 할 수 있습니다.

예를 들어, 웹 검색을 이용하여 제품 가용성이나 산업 동향에 대한 질문에 답하는 고객 서비스 봇을 구축할 수 있습니다. OpenAI의 웹 검색을 통해 에이전트는 시의적절하고 정확한 답변을 제공하여 사용자 신뢰도를 높이고 만족도를 향상시킬 수 있습니다.

효율적인 데이터 접근을 위한 파일 검색 숙달하기

OpenAI의 또 다른 강력한 도구는 파일 검색입니다. 이 기능을 통해 AI 에이전트는 회사의 데이터베이스에서 정보를 빠르게 검색할 수 있습니다. 내부 문서, 보고서 또는 데이터 세트에 접근해야 하는 기업 애플리케이션에 적합합니다.

OpenAI는 이러한 파일에서 모델을 훈련하지 않을 것이라고 강조하며, 이는 기업에서 매우 중요한 개인 정보 보호 및 보안 고려사항입니다. 파일 검색에 대해 자세히 알아보세요.

여기 에이전트에 파일 검색을 통합하는 방법이 있습니다:

1. 파일 업로드: OpenAI API를 사용하여 플랫폼에 파일을 업로드하세요.
2. 에이전트 구성: Responses API 내에서 파일 검색 도구를 사용할 수 있도록 에이전트를 설정하세요.
3. 데이터 쿼리: 에이전트가 파일 내에서 특정 정보를 검색하고 관련 결과를 반환할 수 있습니다.

예를 들어, 직원 기록을 검색하여 급여 세부정보나 휴가 잔여를 제공하는 HR 에이전트를 구축할 수 있습니다. 이러한 자동화 수준은 수작업으로 수 시간을 절약하고 부서 전반의 효율성을 개선할 수 있습니다.

컴퓨터 사용 능력을 통한 작업 자동화

OpenAI의 컴퓨터 사용 에이전트 (CUA) 모델은 작업자를 위한 제품인 Operator를 구동하며, 에이전트가 마우스와 키보드 동작을 생성할 수 있게 합니다. 이는 데이터 입력, 앱 작업 흐름 및 웹사이트 탐색과 같은 작업을 자동화할 수 있음을 의미합니다.

이 도구는 현재 연구 프리뷰 단계에 있지만 이미 개발자들 사이에서 큰 가능성을 보여주고 있습니다. 그 기능을 문서에서 탐색할 수 있습니다. Operator에서 사용할 수 있는 CUA의 소비자 버전은 웹 기반 작업에 중점을 두고 있지만, 기업에서는 더 광범위한 애플리케이션을 위해 로컬에서 사용할 수 있습니다.

시작하는 방법은 다음과 같습니다:

• 프리뷰 접근: 연구 프리뷰에 가입하여 CUA 모델을 테스트하세요.
• 작업 정의: 특정 컴퓨터 작업, 예를 들면 양식 작성이나 버튼 클릭 같은 작업을 수행할 수 있도록 에이전트를 프로그래밍하세요.
• 성능 모니터링: OpenAI의 도구를 사용하여 에이전트의 동작을 디버깅하고 최적화하세요.

반복적인 사무 작업, 예를 들어 스프레드시트를 업데이트하거나 회의를 일정하는 에이전트를 구축하는 상상을 해보세요. 컴퓨터 사용 능력을 통해 에이전트가 이러한 작업을 자율적으로 처리하여 인간 근로자가 더 창의적인 일에 집중할 수 있게 됩니다.

1. 모델에 요청 보내기

우선 OpenAI 키를 설정할 것입니다.

import openai
import os

# API 키 설정
openai.api_key = os.environ.get("OPENAI_API_KEY")

컴퓨터 사용 미리보기 모델과 함께 computer-use-preview 도구를 설정하여 Response를 생성하기 위해 요청을 전송하세요. 이 요청에는 환경에 대한 상세정보와 초기 입력 프롬프트가 포함되어야 합니다.

선택적으로, 환경의 초기 상태에 대한 스크린샷을 포함할 수 있습니다.

computer_use_preview 도구를 사용하려면 truncation 매개변수를 "auto"로 설정해야 합니다 (기본적으로, 잘림은 비활성화되어 있습니다).

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="computer-use-preview",
    tools=[{
        "type": "computer_use_preview",
        "display_width": 1024,
        "display_height": 768,
        "environment": "browser" # 다른 가능한 값: "mac", "windows", "ubuntu"
    }],
    input=[
        {
            "role": "user",
            "content": "bing.com에서 최신 OpenAI 뉴스를 확인하세요."
        }
        # 선택적: 환경 초기 상태의 스크린샷 포함
        # {
        #     type: "input_image",
        #     image_url: f"data:image/png;base64,{screenshot_base64}"
        # }
    ],
    truncation="auto"
)

print(response.output)

2. 제안된 작업 수신

모델은 대화의 상태에 따라 computer_call 항목, 단순 텍스트 또는 기타 도구 호출을 포함하는 출력을 반환합니다.

computer_call 항목의 예로는 클릭, 스크롤, 키 입력 또는 API 참조에서 정의된 기타 이벤트가 있습니다. 우리 예시에서 항목은 클릭 동작입니다:

"output": [
    {
        "type": "reasoning",
        "id": "rs_67cc...",
        "content": []
    },
    {
        "type": "computer_call",
        "id": "cu_67cc...",
        "call_id": "call_zw3...",
        "action": {
            "type": "click",
            "button": "left",
            "x": 156,
            "y": 50
        },
        "pending_safety_checks": [],
        "status": "completed"
    }
]

모델은 일부 작업에 대한 응답 출력에서 reasoning 항목을 반환할 수 있습니다. 만약 그렇다면, 다음 요청을 CUA 모델에 보낼 때 항상 이론 항목을 포함해야 합니다.

이론 항목은 이를 생성한 동일한 모델과만 호환됩니다. 여러 모델을 사용하는 흐름을 구현하는 경우, 이론 항목을 다른 모델에 전달하는 입력 배열에서 필터링해야 합니다.

3. 환경에서 작업 실행하기

컴퓨터나 브라우저에서 해당 작업을 실행합니다. 컴퓨터 호출을 코드의 동작으로 매핑하는 방법은 환경에 따라 다릅니다. 이 코드는 가장 일반적인 컴퓨터 작업에 대한 구현 예를 보여줍니다.

def handle_model_action(page, action):
    """
    주어진 컴퓨터 작업(예: 클릭, 더블 클릭, 스크롤 등)에 따라 Playwright 페이지에서 해당 작업을 실행합니다.
    """
    action_type = action.type
    
    try:
        match action_type:

            case "click":
                x, y = action.x, action.y
                button = action.button
                print(f"동작: ({x}, {y})에서 '{button}' 버튼으로 클릭")
                # 중간 클릭 등의 동작은 처리하지 않음
                if button != "left" and button != "right":
                    button = "left"
                page.mouse.click(x, y, button=button)

            case "scroll":
                x, y = action.x, action.y
                scroll_x, scroll_y = action.scroll_x, action.scroll_y
                print(f"동작: ({x}, {y})에서 오프셋 (scroll_x={scroll_x}, scroll_y={scroll_y})로 스크롤")
                page.mouse.move(x, y)
                page.evaluate(f"window.scrollBy({scroll_x}, {scroll_y})")

            case "keypress":
                keys = action.keys
                for k in keys:
                    print(f"동작: 키 입력 '{k}'")
                    # 일반 키에 대한 간단한 매핑; 필요에 따라 확장
                    if k.lower() == "enter":
                        page.keyboard.press("Enter")
                    elif k.lower() == "space":
                        page.keyboard.press(" ")
                    else:
                        page.keyboard.press(k)
            
            case "type":
                text = action.text
                print(f"동작: 입력할 텍스트: {text}")
                page.keyboard.type(text)
            
            case "wait":
                print(f"동작: 대기")
                time.sleep(2)

            case "screenshot":
                # 스크린샷은 각 단계에서 촬영되므로 별도로 처리할 필요 없음
                print(f"동작: 스크린샷")

            # 기타 동작 처리

            case _:
                print(f"인식할 수 없는 동작: {action}")

    except Exception as e:
        print(f"동작 {action} 처리 중 오류 발생: {e}")

4. 업데이트된 스크린샷 캡처하기

작업을 실행한 후 환경의 업데이트된 상태를 스크린샷으로 캡처합니다. 이는 환경에 따라 달라질 수 있습니다.

def get_screenshot(page):
    """
    Playwright를 사용해 전체 페이지 스크린샷을 촬영하고 이미지 바이트를 반환합니다.
    """
    return page.screenshot()

5. 반복하기

스크린샷을 얻은 후에는 이를 computer_call_output으로 모델에 다시 전송하여 다음 작업을 얻습니다. 응답에서 computer_call 항목이 있을 때까지 이 단계를 반복하세요.

import time
import base64
from openai import OpenAI
client = OpenAI()

def computer_use_loop(instance, response):
    """
    더 이상 'computer_call'이 발견되지 않을 때까지 컴퓨터 작업을 실행하는 루프입니다.
    """
    while True:
        computer_calls = [item for item in response.output if item.type == "computer_call"]
        if not computer_calls:
            print("컴퓨터 호출을 찾을 수 없습니다. 모델의 출력을 출력합니다:")
            for item in response.output:
                print(item)
            break  # 더 이상 컴퓨터 호출이 없을 때 종료합니다.

        # 각 응답에서 최대 하나의 컴퓨터 호출이 예상됩니다.
        computer_call = computer_calls[0]
        last_call_id = computer_call.call_id
        action = computer_call.action

        # 작업 실행 (3단계에서 정의한 함수)
        handle_model_action(instance, action)
        time.sleep(1)  # 변경 사항 효과 발생을 허용합니다.

        # 작업 후 스크린샷 촬영 (4단계에서 정의한 함수)
        screenshot_bytes = get_screenshot(instance)
        screenshot_base64 = base64.b64encode(screenshot_bytes).decode("utf-8")

        # 스크린샷을 computer_call_output으로 다시 전송합니다.
        response = client.responses.create(
            model="computer-use-preview",
            previous_response_id=response.id,
            tools=[
                {
                    "type": "computer_use_preview",
                    "display_width": 1024,
                    "display_height": 768,
                    "environment": "browser"
                }
            ],
            input=[
                {
                    "call_id": last_call_id,
                    "type": "computer_call_output",
                    "output": {
                        "type": "input_image",
                        "image_url": f"data:image/png;base64,{screenshot_base64}"
                    }
                }
            ],
            truncation="auto"
        )

    return response

Agents SDK를 통한 에이전트 오케스트레이션

다중 에이전트 워크플로우를 구축하고 관리하기 위한 OpenAI의 오픈 소스 도구입니다. 이 SDK는 OpenAI의 이전 프레임워크인 Swarm을 기반으로 구축되었으며, 모델을 통합하고, 안전 장치를 구현하며, 에이전트 활동을 모니터링하는 데 사용할 수 있는 무료 도구를 개발자에게 제공합니다.

Agents SDK는 Python 우선 설계로, 내장된 에이전트 루프 및 안전 점검 기능을 포함하고 있습니다. 이는 여러 에이전트가 함께 문제를 해결하는 복잡한 시스템을 만드는 데 적합합니다.

Agents SDK를 사용하는 방법은 다음과 같습니다:

1. SDK 다운로드: OpenAI의 GitHub 리포지토리에서 오픈 소스 코드를 가져옵니다.
2. 다중 에이전트 워크플로우 설정: SDK를 사용하여 에이전트 간에 작업을 오케스트레이션하고, 에이전트의 능력에 따라 위임합니다.
3. 안전 장치 추가: 에이전트가 책임감 있고 신뢰할 수 있도록 안전 점검을 구현합니다.

예를 들어, 하나의 에이전트가 웹 검색을 수행하고, 다른 에이전트가 파일을 관리하며, 세 번째 에이전트가 컴퓨터 작업을 자동화하는 AI 에이전트의 판매 팀을 구축할 수 있습니다. Agents SDK는 이들을 연결하여 매끄럽고 효율적인 시스템을 만듭니다.

결론

Responses API에서 웹 검색, 파일 검색, 컴퓨터 사용 및 Agents SDK에 이르기까지 OpenAI는 개발자에게 자율적이고 지능적인 시스템을 만들기 위해 필요한 모든 것을 제공합니다. 비즈니스 작업을 자동화하든, 고객 서비스를 향상시키든, 새로운 연구 영역을 탐험하든 이러한 도구는 가능성의 세계를 열어줍니다.

그럼, 무엇을 기다리고 있나요? OpenAI API에 뛰어들고, 새로운 도구로 실험하며, 사용자들을 놀라게 할 에이전트를 구축하기 시작하세요. 그리고 API 개발을 간소화하고 여정을 더욱 원활하게 하기 위해 무료로 Apidog를 다운로드하는 것도 잊지 마세요!