OpenAI Swarm & AI Agents

RAG

OpenAI Swarm & AI Agents

장수우 2025. 5. 4. 19:48

핵심 개념

단일 AI 모델이 아닌, 여러 AI 에이전트가 협업하는 시스템을 다룸
에이전트들은 서로 의사소통하고, 업무를 위임하고, 함께 문제를 해결함
이 프로젝트에서는 OpenAI에서 직접 제공하는 Swarm 시스템을 실습함

구성할 에이전트들

에이전트 역할

Main Agent	사용자의 요청을 이해하고 작업을 배분
Greeting Agent	인사말 제공 또는 농담 제공
News Agent	최신 뉴스 검색 및 요약

왜 중요한가?

AI의 미래 방향은 단일 모델이 아닌 복수 에이전트 협업 시스템
향후 GPT-5, GPT-6도 에이전트 기반으로 더욱 확장될 가능성 있음
사용자 상호작용에 따라 동적으로 에이전트를 조정하는 기술을 학습

OpenAI Swarm Deep Dive

Swarm이란?

OpenAI에서 실험적으로 제공하는 멀티 에이전트 프레임워크
단일 AI 모델의 한계를 넘어서기 위해 여러 개의 전문화된 에이전트가 협업하도록 설계됨
GPT API 기반으로 동작하며, 대화 흐름을 동적으로 에이전트 간에 넘길 수 있음 (handoff)

핵심 개념

요소 설명

Agent	하나의 역할(예: 인사, 뉴스, 요약 등)을 수행하는 독립적인 LLM 인스턴스
Function	에이전트가 호출할 수 있는 외부 기능 또는 API (예: 뉴스 가져오기 등)
Handoff	메인 에이전트가 다른 에이전트에게 대화 제어를 넘김
Context Variables	여러 에이전트 간 공유되는 상태 및 정보

구성 요소별 설명

1. 에이전트 (Agents)

각 에이전트는 이름, 지침(instructions), 그리고 선택적 함수를 가짐
예:
- Greeting Agent: 인사와 농담 제공
- News Agent: 특정 국가·카테고리의 뉴스를 API로 검색
- Main Agent: 요청을 이해하고 적절한 에이전트로 handoff

2. 함수(Function)

예제 함수: fetch_news(country, category)
- NewsAPI 를 통해 뉴스 기사를 가져옴
- 사용자의 입력을 바탕으로, 카테고리와 국가를 파악해 API 호출

3. 메인 에이전트 (Main Agent)

사용자의 입력을 분석해 어떤 에이전트가 처리할지 결정
조건 예시:
- 인사 요청이면 → Greeting Agent로 핸드오프
- 뉴스 요청이면 → News Agent로 핸드오프

Colab에서 Swarm 설치

https://github.com/openai/swarm

Python 3.10 이상 권장

1. Swarm 설치 명령어

아래 명령어를 사용해 설치하세요:

!pip install git+https://github.com/openai/openai-swarm

2. requests 설치

뉴스 API를 사용할 때 필요하므로 함께 설치해 주세요:

!pip install requests

3. OpenAI API 키 설정

Google Colab에서 비밀 정보를 다룰 때는 getpass나 Google Drive 연동을 사용하지만, 영상에서는 간단히 환경 변수에 저장합니다.

import os

os.environ["OPENAI_API_KEY"] = "your-api-key-here"

4. 라이브러리 불러오기

import os
import requests
from swarm import Swarm, Agent

핵심 요약

Swarm에서 에이전트를 생성하는 방법은 매우 간단함.
GPT API의 messages 구조(system/user/assistant)와 달리, Swarm은 더 직관적이고 간결한 구조를 제공함.
전체 시스템은 Triage Assistant(매니저)를 중심으로 동작하므로, 두 개 이상의 에이전트가 필요함.

Greeting Agent 코드 예시

from swarm import Agent

# 에이전트 생성
greeting_agent = Agent(
    name="Greeting Agent",
    instructions="You are a friendly assistant that greets me and tells me a joke."
)

Agent()는 Swarm에서 가장 핵심이 되는 클래스입니다.

name과 instructions는 필수이며, 필요에 따라 functions를 추가할 수도 있습니다.

Colab에서 시크릿 키 등록 및 불러오기 예시

# 예시: Colab 환경 기준
# 구글 Colab의 사용자 정보 기반 secret에서 API 키 불러오기
news_api_key = user_data.get("news_api")  # "news_api"는 Colab의 시크릿 변수명과 일치시켜야 함

또는 로컬 환경에서는 다음과 같이 사용할 수 있습니다:

python
복사편집
import os

# 환경 변수에서 API 키 불러오기 (터미널에서 export 하거나 .env 설정 필요)
news_api_key = os.environ.get("NEWS_API_KEY")

주요 목표

News API를 활용해서 사용자로부터 받은 국가(country)와 카테고리(category) 정보를 바탕으로 뉴스 헤드라인을 가져오는 함수 작성.

최종 코드 정리

import requests

def fetch_news(country="us", category=None):
    base_url = "<https://newsapi.org/v2/top-headlines>"
    params = {
        "country": country,
        "apiKey": news_api_key  # 이전에 불러온 API 키
    }

    # category가 있으면 파라미터에 추가
    if category:
        params["category"] = category

    # API 요청
    response = requests.get(base_url, params=params)
    data = response.json()

    # 응답 성공 & 기사 존재
    if response.status_code == 200 and data.get("articles"):
        articles = data["articles"]
        # 최대 10개까지만 제목 수집
        headlines = [article["title"] for article in articles[:10]]

        return (
            f"Here are the top news for {country.upper()} "
            f"in the category: {category if category else 'all categories'}:\\n\\n"
            + "\\n".join(headlines)
        )
    else:
        return f"I couldn't fetch the news at the moment. Error: {data.get('message', 'Unknown error')}"

주요 포인트 설명

country="us"	기본값으로 한국 설정.
category=None	기본적으로 전체 카테고리 조회.
params	API 호출 시 넘길 파라미터 구성.
requests.get()	실제 API 요청.
articles[:10]	상위 10개의 뉴스 제목만 추출.
.upper()	국가 코드 대문자로 변환 (e.g., us → US).
에러 처리	status_code != 200 이거나 articles 없을 경우 에러 메시지 출력.

예시 호출

python
복사편집
print(fetch_news("us", "business"))

출력 예시:

diff
복사편집
Here are the top news for US in the category: business:

- Wall Street surges on jobs report
- Tech stocks rebound amid AI optimism
- ...

팁 & 추가 가능 요소

결과 개수 조절을 위한 limit 인자 추가 가능 (ex: limit=5)
뉴스 제목 외에 source, description 등도 함께 출력할 수 있음
category 예시: "business", "entertainment", "health", "science", "sports", "technology"

목표

fetch_news 함수를 사용하는 뉴스 전용 에이전트 생성
뉴스는 국가와 카테고리를 기준으로 가져옴

코드

from swarm import Agent

news_agent = Agent(
    name="뉴스에이전트",
    instructions="특정 국가와 카테고리의 주요 뉴스 헤드라인을 제공합니다.",
    functions=[fetch_news]
)

주요 구성 요소 설명

요소 내용

name	에이전트의 이름. 나중에 메인 에이전트가 이 이름을 통해 핸드오프 가능
instructions	역할 정의: 어떤 요청을 처리해야 하는지 설명. 이 문장이 중요!
functions	이 에이전트가 사용할 수 있는 함수들. 여기서는 fetch_news() 함수 하나 사용

코드

# 1. 특정 에이전트로 전환하는 함수 정의
def transfer_to_agent(agent_name: str):
    agents = {
        "greeting_agent": greeting_agent,
        "news_agent": news_agent
    }
    return agents.get(agent_name)

# 2. 메인 에이전트 정의
main_agent = Agent(
    name="main_agent",
    instructions="""
당신은 메인 어시스턴트입니다.
사용자의 요청에 따라 작업을 처리할 전문 에이전트를 결정합니다.
- 사용자가 인사말이나 농담을 원한다면, 인사말 에이전트로 이동하세요.
- 사용자가 뉴스를 가져오고 싶다면 뉴스 에이전트로 전송하세요.
    """,
    functions=[transfer_to_agent]
)

포인트

항목 설명

transfer_to_agent()	에이전트 이름을 받아 해당 에이전트 인스턴스를 반환함
main_agent	사용자의 요청을 분기처리하며 적절한 서브 에이전트에게 위임
functions	실제 핸드오프에 쓰이는 함수 리스트. 현재는 transfer_to_agent 하나만 포함

1. 클라이언트 생성

from swarm import Swarm
client = Swarm()

OpenAI API 키를 이용해 swarm 클라이언트 인스턴스를 생성합니다.

2. 에이전트 실행

response = client.run(
    agent=main_agent,
    messages=[
        {
            "role": "user",
            "content": "Tell me the news in finance"
        }
    ]
)

main_agent를 시작점으로 실행
사용자 입력이 들어가면 적절한 하위 에이전트(news_agent or greeting_agent) 로 핸드오프

3. 응답 추출 및 표시

from IPython.display import display, Markdown

display(Markdown(response.messages[-1]["content"]))

가장 마지막 메시지의 content가 실제 에이전트 응답
Markdown을 활용해 포맷팅된 출력 제공

확장 아이디어

날씨 API	현재 날씨 제공 (ex. OpenWeather API)
구글 캘린더 연동	오늘 일정 읽어오기 (OAuth 필요)
컨텍스트 변수	사용자의 위치나 선호를 저장하고 활용
fallback 에이전트	기존 에이전트로 처리할 수 없는 입력에 대해 graceful handling