21,909 stars. OpenAI Solution Team이 GitHub에 올린 이 프로젝트는 README 맨 첫 줄에 이미 This repo is no longer maintained. We've moved development to the OpenAI Agents SDK라고 적혀 있다. 공식적으로 deprecated라고 못 박은 프로젝트를 굳이 소스 코드로 읽어야 할 이유가 뭘까.
이유는 단순하다. Swarm은 multi-agent의 "최소 작동 단위"이기 때문이다. 추상화가 단 두 개뿐이다. Agent와 handoff. 프레임워크 전체가 swarm/core.py 400줄도 안 되며, 그래프도 없고 상태 머신도 없고 영속화도 없다. 이 코드만 완전히 읽으면 multi-agent가 뭘 하는지, 왜 이렇게 설계했는지, 함정이 어디인지 전부 드러난다.
Swarm이 해결하는 문제
다중 Agent 협업에는 가능한 한 작은 mental model이 필요하다.
LangGraph는 너무 무겁다. StateGraph, Node, Edge, Conditional Edge 같은 개념을 먼저 익혀야 demo 하나를 돌릴 수 있다. Assistants API는 블랙박스다. 대화 상태가 전부 OpenAI 서버 쪽에 있어서 로컬 디버깅은 logs를 보는 게 전부다.
Swarm의 약속은 이렇다. 5분 안에 "인수인계"(handoff) primitive를 돌려보게 해준다. 한 Agent의 tools에 다른 Agent를 반환하는 함수를 넣어두면, 런타임이 도구 반환값이 Agent 인스턴스인 것을 감지하고 대화 소유권을 넘긴다. 그게 다다.
이 primitive의 이름이 handoff다. 프로토콜 레벨 handoff가 아니라 함수 반환값에 내포된 시맨틱 레벨 handoff다. LangGraph, CrewAI, AutoGen이 공통적으로 수행하는 동작의 가장 단순한 형태라 할 수 있다.
사용 방법
pip install swarm은 안 된다. Swarm은 이미 PyPI에서 내려갔고, 설치할 수 있는 유일한 방법은 다음과 같다.
pip install git+https://github.com/openai/swarm.git
이것 자체가 첫 번째 deprecation 시그널이다. OpenAI 스스로 새 프로젝트에는 쓰지 말라고 안내하는 셈이다.
설치 후 handoff를 확인하려면 최소 30줄이면 충분하다.
from swarm import Swarm, Agent
client = Swarm()
def transfer_to_agent_b():
return agent_b
agent_a = Agent(
name="Agent A",
instructions="你是接待员,听到用户想聊技术就交给 Agent B。",
functions=[transfer_to_agent_b],
)
agent_b = Agent(
name="Agent B",
instructions="只用俳句回答问题。",
)
response = client.run(
agent=agent_a,
messages=[{"role": "user", "content": "我想聊聊分布式系统"}],
)
print(response.messages[-1]["content"])
# 출력:
# 节点轻轻颤动,
# 数据在网络间流转,
# 共识悄然达成。
흐름은 이렇다. Agent A가 "分布式系统"을 받고, 모델이 인계가 필요하다고 판단해 transfer_to_agent_b()를 호출한다. 반환된 agent_b 인스턴스를 받아 다음 루프의 context에 있는 agent 필드를 B로 교체한다. B가 하이쿠로 응답한다. 전체 흐름이 이게 전부다.
동작 원리 (아키텍처)
swarm/core.py를 열어보자. 파일 전체에 핵심 클래스가 두 개, run loop가 하나뿐이다.
두 가지 primitive
Agent: 일반적인 dataclass. 필드는name,instructions,functions,model.instructions는 system prompt이고functions는 tools 리스트다. 이 외에는 아무것도 없다.- handoff: 별도의 클래스가 없다. 그냥 평범한 Python 함수가 Agent 인스턴스를 반환한다. 그것뿐이다. Swarm의 run loop가 도구 반환값을 검사해서
isinstance(result, Agent)로 분기한다. Agent면 교체하고, 아니면 일반 결과로 처리한다.
run loop의 동작
while True:
completion = client.chat.completions.create(
model=agent.model,
messages=messages,
tools=tools_from(agent.functions),
)
if no tool_call: return
execute tool_calls
if any result is Agent: agent = that_agent; continue
append results to messages; continue
무상태. 영속화 없음. 매 루프마다 messages 배열 전체를 OpenAI로 전송한다.
Swarm이 "client-side"라고 강조하는 이유가 이것이다. 모든 대화 히스토리가 로컬 메모리에 있고, 매 run마다 messages 배열을 처음부터 다시 구성해 전달한다. Assistants API의 서버 측 thread와는 정반대 방향이다.
사실 직접 Chat Completions API를 호출하는 것과 거의 다르지 않다. Swarm이 대신 해주는 건 Python 함수를 OpenAI schema로 변환하고, tool_call dispatch를 처리하고, "if result is Agent then handoff" 몇 줄을 작성해준 정도다. 나머지는 전부 OpenAI API 네이티브 호출이다.
좋은 점
Mental model이 극도로 단순하다. 개념 두 개(Agent + handoff 함수)만으로 모든 예시가 구성된다. examples/ 디렉터리에는 6개 demo가 들어 있다. basic, triage_agent, weather_agent, airline, support_bot, personal_shopper. 각 파일은 100~200줄 수준이라 agent 정의만 훑어봐도 무엇을 하는지 바로 이해된다.
클라이언트 측 디버깅이 가능하다. client.run 안에 break point를 찍으면 모든 messages, tool calls, handoff 결정이 로컬에서 보인다. Assistants API는 이런 디버깅 환경을 절대 제공하지 못한다.
코드량이 적어 통째로 읽을 수 있다. swarm/core.py와 utility 파일 두 개를 읽는 데 두 시간이 채 걸리지 않았다. examples까지 모두 돌려봐도 세 시간 정도였다. 이 과정을 거치면 multi-agent의 런타임 메커니즘이 블로그 열 편을 읽는 것보다 훨씬 또렷해진다.
도구 정의가 일반 Python 함수다. 마법 같은 decorator도, 등록 센터도 없다. def로 함수를 정의해 Agent에 넘기면 끝이다. 함수가 문자열을 반환하면 messages에 들어가고, Agent를 반환하면 handoff가 된다. 분기는 단 한 갈래뿐이다.
아쉬운 점
영속화가 없다. 프로세스가 종료되면 대화 히스토리가 전부 사라진다. 재연결하려면 직접 messages를 직렬화해야 한다. 운영 환경에서는 사실상 쓸 수 없다.
에러 복구 메커니즘이 없다. tool call 실패, 네트워크 지터, timeout — Swarm은 이런 상황을 다루지 않는다. OpenAI API가 항상 안정적으로 응답한다고 가정한다.
tracing이 없다. span도 없고, token usage 집계(OpenAI가 반환하는 usage 필드 제외)도 없고, 도구 호출 계층 뷰도 없다. 복잡한 multi-agent 대화를 디버깅하려면 print에 의존해야 한다.
그래프 오케스트레이션이 없다. handoff는 직렬 단방향이다. A→B→A→C처럼 순환과 조건 분기를 갖는 흐름을 구현하려면 Swarm으로는 한계가 있다. LangGraph라면 한 줄로 끝낸다.
handoff마다 전체 messages를 재전송한다. 이게 숨은 비용이다. Agent A가 10턴 대화한 뒤 B로 handoff하면, B의 system prompt만 교체되고 앞선 10턴의 messages는 한 글자도 빠짐없이 모델로 전송된다. 토큰이 두 배 이상으로 치솟는다.
README에서 OpenAI 스스로免責 조항을 적어뒀다. Swarm은 Assistants API가 아니며, 운영용이 아니고, 실전 시나리오에 쓰지 말라고 못 박았다. Swarm을 OpenAI의 "공식 multi-agent 프레임워크"로 오해하지 않게 하기 위함이다. 그게 아니다.
직접 돌려본 결과
examples/weather_agent 실행: "北京天气怎么样" 한 마디에 5개 도구를 한 라운드에서 처리한다. triage agent가 weather agent로 라우팅하고, 위치 조회, 날씨 API 호출, 포맷팅까지 수행한다. 한 라운드 약 2초, 약 800 토큰. 단일 Agent 경험은 매끄럽고 handoff 점프도 없다.
examples/airline 실행: 훨씬 복잡하다. 다섯 개의 자식 Agent로 구성된 고객 서비스 시나리오다. booking, refund, seat, flight_status, triage. "다음 주 SF 항공권을 LA로 바꾸고, 창가 좌석으로 하고, 시간도 변경해줘"라고 입력하니 3~4회 handoff가 발생했다. triage → booking(변경) → seat(창가) → booking(시간 변경).
관찰한 두 가지.
- 토큰 소모가 단일 Agent 대비 약 2~3배. 매 handoff마다 전체 messages를 재전송하고, 각 sub-agent의 system prompt가 총합에 또 더해진다. 이 한 라운드에서 총 3,500 토큰 정도 소비됐다.
- 지연 시간이 단일 Agent의 ~1초에서 4~6초로 뛰었다. handoff가 직렬로 일어나 매 hop마다 Chat Completions 왕복이 추가된다. handoff 체인이 N hop이면 지연도 N배가 된다.
이 수치는 Swarm의 설계 의도와 일치한다. 동시성도 없고 지름길도 없이 한 단계씩 직진한다.
이런 사용자라면 쓸만하다 / 쓰지 마라
쓰면 좋은 경우
- multi-agent mental model을 이해하고 싶은 엔지니어. 어떤 튜토리얼보다 Swarm 소스를 직접 읽는 게 빠르다.
- 교육 목적. handoff, tool call, context 전달을 가르치기에 Swarm은 가장 깔끔한 예시다.
- handoff 아이디어를 빠르게 프로토타이핑하고 싶을 때. LangGraph 도입 여부를 판단 중이라면 먼저 Swarm으로 한 버전 만들어 multi-agent가 본인 문제에 맞는지 확인하라.
쓰지 마라
- 운영 시스템. OpenAI Agents SDK(Swarm의 공식 후속으로 영속화, tracing, session 관리 지원)로 가라.
- 병렬 처리, 영속화, 조건 분기가 필요한 복잡한 시나리오. LangGraph나 AutoGen을 바로 도입하고 Swarm에 기능을 억지로 덧붙이지 마라.
결론은 직관적이다. Swarm을 교재로 삼아라. 도구로 삼지는 마라. 2024~2025년에 나온 multi-agent 구현 중 통독 가치가 가장 높은 소스 중 하나다. 읽을 게 별로 없어서가 아니라, 전체 mental model이 "Agent + handoff 함수" 한 줄로 정리되기 때문이다. 여기서 출발해 LangGraph의 그래프, Agents SDK의 session을 보면 그 프레임워크들이 무엇을 해결하고 추가된 복잡도가 무엇을换来는지 비로소 보인다.
소스 코드는 github.com/openai/swarm에 있다. clone해서 두 시간이면 통독 가능하며, "multi agent 입문" 블로그 열 편보다 낫다.