본문 바로가기
AI 도구

🧠🤖새로운 OpenAI API와 SDK를 이용한 AI 에이전트 구축 가이드

by James AI Explorer 2025. 3. 20.
    728x90

    오늘은 OpenAI가 새롭게 공개한 Responses APIAgents SDK에 대해 알아보겠습니다. Responses API웹 검색, 파일 검색, 컴퓨터 제어 등 내장 도구를 활용해 복잡한 에이전트 작업을 단일 API로 처리할 수 있게 해 주며, Agents SDK는 Python 기반으로 다중 에이전트 조율, 가드레일, 추적 기능 등을 제공하며, 개발자가 유연하고 확장 가능한 에이전트 시스템을 쉽게 구축하도록 지원합니다. 이번 블로그에서는 Responses API Agents SDK특징과 기능, 사용방법에 대해 알아보고, 실제 활용사례를 살펴보겠습니다. 

    🧠🤖새로운 OpenAI API와 SDK를 이용한 AI 에이전트 구축 가이드(이미지 생성: Qwen2.5-Plus)

    "이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다."

    1. 개요

    1) Responses API

    Responses API는 기존의 챗 완성 API(Chat Completions API)를 단순화하고 Assistants API를 대체하기 위해 새로 도입된 API입니다. Responses API를 사용하면 이전 챗 완성 API와 유사한 방식으로 챗봇과 같은 기능을 구현할 수 있으며, client.responses.create 함수를 통해 모델을 지정하고 질문을 던져 응답을 받을 수 있습니다. Responses API는 웹 검색, 파일 검색, 컴퓨터 사용과 같은 내장 도구를 API를 통해 직접 사용할 수 있도록 지원함으로써, 에이전트가 외부 세계와 상호작용하고 정보를 얻는 방식을 크게 확장합니다.

    Chat Completions API(chat.py) Responses API(resp.py)
    from openai import OpenAI
    client = OpenAI()

    completion = client.chat.completions.create(
     model="gpt-4o-mini",
     messages=[ {"role": "user", "content": "Hi!"} ]
    )

    print(completion.choices[0].message)
    from openai import OpenAI
    client = OpenAI()

    response = client.responses.create(
     model="gpt-4o-mini",
     input="Hi!"
    )

    print(response)
    대화 중심의 응답 생성을위한 도구 다양한 작업 수행을 위한 AI 에이전트 구축 도구

    Responses API 실행결과

    2) Agents SDK

    Agents SDK는 기존의 실험적인 에이전트 프레임워크였던 Swarm을 완전히 새롭게 구축하여 프로덕션 환경에 바로 적용할 수 있도록 만든 SDK(소프트웨어 개발 도구)입니다. Agents SDK는 LLM에 지침과 도구를 장착한 에이전트, 특정 작업을 위해 다른 에이전트에게 위임할 수 있는 핸드오프, 그리고 에이전트의 입력 유효성을 검사하는 가드레일이라는 작고 강력한 기본 요소들로 구성되어 있습니다. Agents SDK는 Python과 함께 사용될 때 복잡한 도구 및 에이전트 관계를 쉽게 표현하고 실제 애플리케이션을 구축할 수 있도록 지원하며, 에이전트 흐름을 시각화하고 디버깅할 수 있는 기본 제공 트레이싱 기능과 평가 및 미세 조정 도구를 함께 제공합니다.

    기능 Response API Agents SDK
    주요 역할 API 기반 AI 응답 생성 다중 에이전트 오케스트레이션
    내장 도구 웹 검색, 파일 검색, 컴퓨터 제어 에이전트 루프, 핸드오프, 가드레일
    사용 목적 빠른 응답 생성 복잡한 AI 에이전트 구축
    개발 편의성 간단한 API 호출 Python 기반 SDK 사용
    728x90

    2. 특징 및 기능

    1) Responses API

    • 강화된 에이전트 기능: Responses API는 에이전트가 더욱 지능적으로 작업을 수행할 수 있도록 지원합니다
    • 내장 도구 활용: Responses API를 통해 개발자는 별도의 복잡한 설정 없이 웹 검색을 통해 최신 정보를 얻고, 파일 검색을 통해 사용자가 제공한 문서에서 의미론적 검색을 수행하여 관련 정보를 추출하며, 컴퓨터 사용 도구를 통해 브라우저를 제어하고 특정 작업을 수행하는 기능을 에이전트에 통합할 수 있습니다.
    • 간편한 챗봇 구축: client.responses.create 함수를 사용하여 몇 줄의 코드로 간단하게 챗봇을 만들 수 있습니다
    • RAG (Retrieval Augmented Generation) 지원: 파일 검색 도구를 활용하여 사용자의 자체 데이터를 기반으로 관련 정보를 검색하고 응답을 생성하는 RAG 애플리케이션을 구축할 수 있습니다

    2) Agents SDK

    • 에이전트 루프: 도구를 호출하고, 결과를 LLM에 보내고, LLM이 완료될 때까지 이 과정을 반복하는 기본 제공 에이전트 루프를 제공합니다.
    • 핸드오프: 여러 에이전트 간의 협업 및 작업 위임을 위한 강력한 기능인 핸드오프를 지원합니다.
    • 가드레일: 에이전트에 대한 입력 유효성 검사 실패 시 즉시 중단시키는 가드레일 기능을 제공합니다.
    • 함수 도구: Python 함수를 자동으로 스키마를 생성하고 Pydantic으로 유효성을 검사하여 도구로 변환하는 함수 도구를 제공합니다.
    • Tracing: 워크플로우를 시각화, 디버깅 및 모니터링할 수 있는 기본 제공 트레이싱 기능을 제공하며, OpenAI 플랫폼의 "Traces" 메뉴에서 에이전트의 활동을 실시간으로 모니터링하고 디버깅할 수 있습니다.

     

    3. 사용 방법

    1) OpenAI Agents SDK 설치방법: 아래 명령어로 패키지를 설치하고, API Key를 설정하면 설치가 완료됩니다. 

    pip install openai-agents
    export OPENAI_API_KEY=sk-...

    OpenAI Agents SDK 설치화면

    설치가 완료되면 다음과 같은 간단한 코드를 사용하여 에이전트를 실행할 수 있습니다:

    from agents import Agent, Runner
    
    agent = Agent(name="Assistant", instructions="You are a helpful assistant")
    result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
    
    print(result.final_output)

    위 코드는 "Assistant"라는 이름을 가진 에이전트를 생성하고, "재귀(자기 호출) 프로그래밍에 대한 하이쿠(짧은 시)를 작성하세요."라는 지시사항을 전달합니다. Runner.run_sync() 함수는 에이전트를 실행하고 결과를 반환합니다.

    OpenAI Agents SDK를 활용한 에이전트 하이쿠 작성예제 실행결과

    2) Ollama에서 OpenAI Agents SDK 사용방법

    로컬 언어모델 관리도구 Ollama에서 OpenAI의 Agents SDK를 사용하는 방법은 아래와 같습니다. Ollama를 설치한 후, "ollama pull" 명령으로 원하는 언어 모델을 로컬에 다운로드하고, 모델명과 Base_URL을 설정하면 됩니다. 

    ollama pull phi-4-mini

    Ollama 언어모델 다운로드 화면

    from agents import Agent, Runner, OpenAIChatCompletionsModel, AsyncOpenAI
    
    model = OpenAIChatCompletionsModel( 
        model="phi4-mini",
        openai_client=AsyncOpenAI(base_url="http://localhost:11434/v1")
    )
    
    agent = Agent(name="Assistant",
                  instructions="You are a helpful assistant",
                  model=model)
    
    result = Runner.run_sync(agent, "Create a meal plan for a week.")
    print(result.final_output)

    Ollama phi4-mini 모델을 활용한 OpenAI Agents SDK 사용

    3) Responses API

    Responses API는 기존의 Chat Completions API를 사용하여 더욱 복잡했던 도구 사용, 코드 실행, 상태 관리와 관련된 워크플로우를 간소화하는 것을 목표로 합니다. Chat Completions API는 AI 애플리케이션 구축을 위한 업계 표준으로, 앞으로도 계속 지원될 예정이며, 내장 도구가 필요하지 않은 애플리케이션에 적합합니다.

    # Developer quickstart
    https://platform.openai.com/docs/quickstart?api-mode=responses

    OpenAI는 Assistants API와 Responses API 간의 완전한 기능 동등성을 달성하고, 2026년 상반기에 Assistants API를 단계적으로 폐지할 계획입니다. 새로운 Responses API는 에이전트 동작을 강화하기 위한 웹 검색, 파일 검색, 컴퓨터 사용 등의 기능을 API를 통해 직접 사용할 수 있습니다.

    4. Response API 활용 사례

    1) AI 챗봇: 아래와 같이 간단한 코드로 AI 모델과 대화할 수 있습니다. 

    from openai import OpenAI
    client = OpenAI()
    
    response = client.responses.create(
      model="gpt-4o-mini",
      input="Hi!"
    )
    
    print(response)

    Reponse API의 응답

    Response API의 응답은 다음과 같은 객체로 구성됩니다. 

    • id: 응답의 고유 식별자
    • created_at: 응답이 생성된 시간(유닉스 타임스탬프)
    • model: 사용된 모델('gpt-4o-mini-2024-07-18')
    • output: 응답 메시지 목록(여기서는 "Hello! How can I assist you today?"라는 텍스트를 포함)
    • status: 응답 상태('completed')
    • usage: 토큰 사용량 정보

    2) Gradio 인터페이스: Gradio를 사용하여 챗봇에 사용자 인터페이스를 추가할 수 있습니다.

    from openai import OpenAI
    from rich import print
    import gradio as gr
    
    client = OpenAI()
    
    def generate_response(prompt):
        response = client.responses.create(
            model="gpt-4o-mini",
            input=prompt
        )
        return response.output_text
    
    # Create Gradio interface
    demo = gr.Interface(
        fn=generate_response,
        inputs=gr.Textbox(placeholder="Enter your prompt here...", label="Prompt"),
        outputs=gr.Textbox(label="Response"),
        title="OpenAI GPT-4o-mini",
        description="Enter a prompt to get a response from GPT-4o-mini"
    )
    
    if __name__ == "__main__":
        demo.launch()

    Responses API 활용 Gradio 챗봇 인터페이스

    3) 웹 검색 도구: 웹 검색 도구를 사용하는 예제는 다음과 같습니다:

    from openai import OpenAI
    client = OpenAI()
    
    response = client.responses.create(
        model="gpt-4o-mini",
        tools=[{"type": "web_search_preview"}],
        input="What was a headline news story from aitime.com?"
    )
    
    print(response.output_text)

    웹 검색도구 실행결과

    4) 파일 검색 및 RAG 도구: 파일 검색 도구를 사용하려면 먼저 OpenAI 플랫폼에서 벡터 스토어를 생성하고 파일을 업로드한 후, 해당 벡터 스토어 ID를 사용하여 파일 검색 도구를 사용할 수 있습니다.

    OpenAI 플랫폼 벡터 스토어 생성화면

    from openai import OpenAI
    client = OpenAI()
    
    response = client.responses.create(
      model="gpt-4o-mini",
      input="Figure 1 설명해줘",
      tools=[{"type": "file_search", "vector_store_ids": ["vs_67d134235e0c8191a116bc67fb0fcba1"]}],
    )
    
    print(response)

    파일 검색 도구 실행결과

    5) 컴퓨터 사용 도구: 컴퓨터 사용 도구를 사용하면 에이전트가 컴퓨터 또는 브라우저를 제어할 수 있습니다.

    • 모델: computer-use-preview 모델을 사용하며, 이 모델은 GPT-4o의 시각 능력과 추론 능력을 활용합니다.
    • API: Responses API를 통해서만 사용 가능하며, Chat Completions API에서는 사용할 수 없습니다.
    • 베타 버전: 현재 베타(preview) 버전으로 제공되며, 잠재적인 보안 취약점이나 예기치 않은 오류가 있을 수 있으므로 중요한 작업이나 완전히 인증된 환경에서의 사용은 권장되지 않습니다.
    • 연속적인 루프: 모델의 액션 제안, 코드 실행, 스크린샷 캡처, 그리고 이를 다시 모델에 전달하는 과정이 반복적으로 이루어집니다
    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" # other possible values: "mac", "windows", "ubuntu"
        }],
        input=[
            {
                "role": "user",
                "content": "Check the latest OpenAI news on bing.com."
            }
            # Optional: include a screenshot of the initial state of the environment
            # {
            #     type: "input_image",
            #     image_url: f"data:image/png;base64,{screenshot_base64}"
            # }
        ],
        reasoning={
            "generate_summary": "concise",
        },
        truncation="auto"
    )
    
    print(response.output)

    6) Tracing 도구

    OpenAI 플랫폼에서 제공하는 Tracing 도구를 사용하여 에이전트의 동작을 모니터링하고 디버깅할 수 있습니다. Tracing 도구를 사용하면 에이전트가 수행하는 작업, 사용하는 도구, 반환하는 응답 등을 실시간으로 확인할 수 있습니다. 이를 통해 에이전트의 성능을 측정하고 개선할 영역을 식별할 수 있습니다.

    OpenAI 플랫폼 Traces 화면

    "이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다."

    5. 맺음말

    Responses API와 Agents SDK는 AI 에이전트 개발의 새로운 가능성을 열어주는 강력한 도구입니다. Responses API를 통해 보다 직관적이고 효율적인 AI 응답 시스템을 구축할 수 있으며, Agents SDK는 복잡한 다중 에이전트 조율과 가드레일 기능을 제공해 AI 시스템의 신뢰성과 확장성을 높여줍니다.

     

    이 블로그에 소개된 개념과 코드들이 AI 에이전트 개발에 관심 있는 분들에게 도움이 되었기를 바라면서, 저는 다음 시간에 더 유익한 정보를 가지고 다시 찾아뵙겠습니다. 감사합니다.

     

    https://fornewchallenge.tistory.com/

     

     

    2024.11.16 - [AI 도구] - 🛠️Phidata Agents: 코드 4줄로 완성하는 강력한 AI 에이전트 프레임워크

     

    🛠️Phidata Agents: 코드 4줄로 완성하는 강력한 AI 에이전트 프레임워크

    안녕하세요! 오늘은 AI 에이전트를 쉽고 효과적으로 개발할 수 있는 프레임워크인 Phidata Agents에 대해 알아보겠습니다. 인공지능 기술이 빠르게 발전하면서, 자율적으로 작업을 수행하는 AI 에이

    fornewchallenge.tistory.com

     

    728x90