처음부터 이해하는 Antigravity Orchestrator: 3계층 아키텍처, 3가지 오케스트레이션 모드와 스웜 메커니즘 상세 해설

처음부터 이해하는 Antigravity Orchestrator: 3계층 아키텍처, 3가지 오케스트레이션 모드와 스웜 메커니즘 상세 해설

필자 노트: 이 글 한 편으로 Antigravity Orchestrator가 무엇인지, /swarm으로 서브 에이전트를 어떻게 파견하는지, 그리고 LangGraph·CrewAI와의 포지셔닝 차이까지 한 번에 정리해 보려고 해요.

요약: Antigravity Orchestrator는 Google Antigravity 플랫폼에 내장된 멀티 에이전트 오케스트레이션 엔진이지, pip으로 단독 설치하는 경량 프레임워크가 아니에요. 이 글에서는 제품 매트릭스, 3계층 추상화, 3가지 오케스트레이션 패턴, 그리고 /swarm 스웜 메커니즘, 이 네 가지 측면에서 작동 방식과 활용 범위를 확실히 정리해 드릴게요.

결론부터: Antigravity Orchestrator는 “Antigravity 플랫폼 안에 숨어 있는 작업 스케줄링 두뇌”라고 이해하면 돼요. IDE, 웹 앱, CLI에서 /swarm, /teamwork 같은 슬래시 명령어를 입력하면, 내부적으로 SDK의 Task API와 Workflow Runtime을 호출해서 큰 작업을 여러 하위 작업으로 나누고, 병렬로 일하는 서브 에이전트들에게 맡긴 뒤, 마지막에 산출물로 취합해 줘요. 2026년 11월, Orchestrator는 Gemini 4 Neon과 함께 Antigravity에 정식으로 들어왔어요. 11월 10일 Gemini 4 Carbon이 전면 공개되던 날 Sundar Pichai가 /swarm 기능을 라이브로 시연했고, 이 기능은 그때부터 대중에게 알려지게 되었죠.

배울 가치가 있는지는 두 가지 조건에 달려 있어요. 첫째, 내 작업을 서로 독립적이고 병렬로 처리할 수 있는 부분으로 나눌 수 있는가. 둘째, Gemini를 최적화 대상으로 삼고 핵심 엔진이 클로즈드 소스인 플랫폼을 받아들일 수 있는가. 두 조건이 모두 충족되면 Orchestrator가 멀티 에이전트 협업 구축 비용을 확실히 낮춰 줘요. 반대로 모델에 얽매이지 않는 완전 오픈 소스 방안이 필요하다면, LangGraph나 CrewAI 같은 Python 라이브러리가 여전히 더 적합해요.

antigravity-orchestrator-explained-from-zero-ko-image-0


Antigravity Orchestrator 지식 맵과 읽기 가이드

아래 표에는 글 전체의 지식 구조, 절 사이의 의존 관계, 그리고 각 절에서 다루는 문제가 정리되어 있어요. 전체 흐름은 ‘어떤 체계에 속한 기술인지’에서 시작해 ‘어떻게 작동하는지’를 거쳐 ‘써야 할지, 어떻게 시작할지’ 순으로 이어집니다.

번호 주제 해결하는 문제 앞뒤 절과의 관계
1 Antigravity 플랫폼 배경 Orchestrator가 어떤 제품 체계 위에서 구동되는지 2절에 플랫폼 맥락 제공
2 Orchestrator 3계층 추상화 기술적으로 정확히 무엇인지 3절과 4절의 메커니즘이 모두 이 세 계층 위에 성립
3 세 가지 오케스트레이션 모드 /swarm, /teamwork, /run-workflow는 어떻게 다른지 세 모드 가운데 /swarm을 골라 4절에서 심층 다룸
4 /swarm 스웜(군집) 메커니즘 메인 에이전트가 작업을 나누고 서브 에이전트를 배치하는 방식 실제 사례와 결합해 5절 비교의 근거 제공
5 LangGraph 등 프레임워크와 비교 어떤 조건에서 선택하고 어떤 조건에서 피해야 하는지 기술 선택 판단 기준을 제시하고 6절의 시작 경로로 연결
6 시작 경로와 코드 제로베이스에서 어떻게 시작하는지 앞선 개념을 코드 수준으로 구체화
7 모범 사례와 실무 시사점 모델 선택, 권한, 비용을 어떻게 관리하는지 실행 가능한 조언으로 마무리

단순히 이게 뭔지만 알고 싶다면 1~3절까지만 읽어도 충분해요. 기술 선택을 앞두고 있다면 4절과 5절을 집중해서 읽어보시길 권해요. 직접 실습해 볼 계획이라면 바로 6절과 7절로 넘어가도 괜찮아요.

🎯 기술 팁: 멀티 에이전트 오케스트레이션을 가장 빨리 이해하는 방법은 ‘분할—병렬—취합’ 흐름을 직접 한 번 돌려보는 거예요. 6.3절에는 OpenAI 호환 인터페이스 기반의 시뮬레이션 구현이 소개되어 있는데, APIYI apiyi.com을 통해 API 키 하나만으로 서로 다른 모델을 호출해 메인 에이전트와 서브 에이전트 역할을 맡길 수 있어요.

To Know: Antigravity Orchestrator 이해에 꼭 필요한 용어

용어 간단한 설명
에이전트(Agent) 도구를 호출하고 여러 단계의 작업을 스스로 완수하는 모델 인스턴스
메인 에이전트(Orchestrator Agent) 작업을 분석·분해하고 서브 에이전트를 배치한 뒤 결과를 취합하는 총 조율자
서브 에이전트(Subagent) 개별 하위 작업을 맡는 에이전트로, 런타임에 동적으로 만들 수도 있고 미리 정의해 둘 수도 있음
Fan-out / Fan-in Fan-out은 하나의 작업을 여러 실행자에게 나눠 주는 것, Fan-in은 여러 결과를 하나로 모으는 것
Artifacts 에이전트가 최종 산출하는 결과물로, 코드·파일·실행 가능한 애플리케이션 등이 있음
Workflow Runtime Antigravity SDK의 그래프 기반 실행 엔진으로, 상태 관리와 노드 스케줄링을 담당

1 Antigravity Orchestrator가 속한 플랫폼: Antigravity란 무엇일까

1.1 Antigravity라는 이름은 어디서 왔을까

“Antigravity”를 직역하면 “반중력”이에요. 전통적인 혼자 하는 코딩의 틀에서 벗어나, 무중력처럼 “날아오르자”는 의미를 담고 있죠. 많은 개발자들은 이 이름이 Python의 import antigravity 이스터에그에서 따온 게 아닐까 추측해요. 이 이스터에그는 xkcd 만화 한 편에서 유래했는데, 이 코드를 실행하면 브라우저에서 해당 만화가 열려요. Google은 Antigravity를 “agent-first era”(에이전트 우선 시대)의 개발자 플랫폼으로 내세우고 있어요. 다시 말해, 에이전트가 작업의 주체이고 사람은 목표를 설명하고 결과를 검토하는 역할을 맡는 거죠.

1.2 Antigravity는 하나의 제품군

많은 분들이 Antigravity를 처음 들으면 IDE라고 생각하시곤 해요. 하지만 실제로는 다양한 상황에 맞춰진 여러 제품으로 이루어져 있고, Orchestrator 기능은 이 제품 형태들에 걸쳐 분포해 있어요:

제품 형태 주요 용도
Antigravity App 웹 애플리케이션 브라우저에서 모든 기능을 갖춘 에이전트 코딩
Antigravity IDE 데스크톱 앱 VS Code 포크 기반, 에이전트 기능을 깊이 통합
Antigravity CLI 명령줄 도구 Go로 작성된 터미널 에이전트
Antigravity SDK Python 라이브러리 커스텀 에이전트 개발
Antigravity Extensions IDE 플러그인 기존 에디터에 에이전트 기능 내장

이 표는 핵심적인 사실 하나를 보여줘요. 슬래시 명령어는 App, IDE, CLI 같은 인터랙티브 인터페이스에서 쓰이고, SDK가 담당하는 건 프로그래밍으로 접근하는 인터페이스라는 점이죠. 2절에서 세 가지 추상화 계층을 다룰 때, 이 둘이 위아래로 어떻게 맞물리는지 확인하게 될 거예요.

1.3 Antigravity Orchestrator의 출시 타임라인

Orchestrator가 갑자기 나타난 건 아니에요. Antigravity 플랫폼이 지난 1년간 차근차근 진화해 온 결과물이죠. 시간 순서대로 주요 이정표를 정리하면 다음과 같아요:

  • 2025년 11월 18일: Antigravity IDE와 Gemini 3 Pro가 같은 날 처음 공개되었어요.
  • 2026년 5월(Google I/O): Gemini 3.5 Flash가 발표되고, Antigravity 런타임 기반의 Gemini Spark도 공개되었어요.
  • 2026년 6월 18일: 오픈소스였던 Gemini CLI가 서비스를 종료하고, 클로즈드소스인 Antigravity CLI로 완전히 전환되었어요.
  • 2026년 11월: Gemini 4 Neon과 Orchestrator가 Antigravity에 정식으로 들어왔어요.
  • 2026년 11월 10일: Gemini 4 Carbon이 전면 공개되었고, Sundar Pichai가 /swarm을 시연했어요.

이 타임라인에서 뚜렷한 추세 하나를 읽을 수 있어요. Google은 터미널, IDE, 브라우저의 에이전트 기능을 Antigravity 런타임 아래로 하나로 모으고 있고, Orchestrator는 그 런타임 위에 얹힌 조율 계층인 거죠.


2 Antigravity Orchestrator란? 3계층 추상화로 뜯어보기

2.1 Antigravity Orchestrator의 정확한 정체

일부 글에서는 Antigravity Orchestrator를 ‘경량 스웜(swarm) 프레임워크’라고 부르는데요, 이 표현은 독립된 라이브러리라고 오해하기 쉬워요. 더 정확한 설명은 이렇습니다. Antigravity 플랫폼에 내장된 멀티 에이전트 오케스트레이션 엔진이라는 것. 하위 계층은 SDK의 Workflow Runtime과 Task API에 대응하고, 상위에서는 슬래시 명령어나 SDK API로 실행을 트리거해요. ‘경량’이라는 말은 사용 경험에서 나온 겁니다. 사용자는 명령어 한 줄만 입력하면 되고, 그래프 구조나 상태 머신을 직접 작성할 필요가 없거든요.

2.2 Antigravity Orchestrator의 3계층 구조

Orchestrator의 기능은 위에서 아래로 세 계층으로 나뉘어요. 상위 계층이 하위 계층을 호출하고, 내려갈수록 실행 디테일에 가까워집니다:

Layer 1: 슬래시 명령어       /swarm, /teamwork, /plan
    ↓  사용자 대상 — 명령어 한 줄로 오케스트레이션 트리거
Layer 2: SDK API            Agent, Subagent, Task API
    ↓  개발자 대상 — 코드로 에이전트와 태스크 정의
Layer 3: Workflow Runtime   그래프 실행 엔진, Fan-out/Fan-in, 상태 관리
       런타임 대상 — 스케줄링, 병렬 처리, 상태 담당

이런 계층화가 주는 직접적인 이점은 ‘하나의 엔진, 여러 개의 진입점’이라는 점이에요. 프로덕트 매니저는 IDE에서 /swarm을 바로 입력할 수 있고, 백엔드 엔지니어는 SDK로 동일한 오케스트레이션 로직을 작성할 수 있죠. 두 방식 모두 최종적으로는 Workflow Runtime이 실행합니다. 이 점만 이해하면 뒤에서 다룰 세 가지 모드의 차이도 훨씬 쉽게 보여요. 세 모드는 Layer 1에서는 서로 다른 진입점으로 나타날 뿐이고, Layer 3에서는 각각 다른 그래프 형태에 대응할 뿐이거든요.

antigravity-orchestrator-explained-from-zero-ko-image-1


3 Antigravity Orchestrator의 세 가지 오케스트레이션 모드

Orchestrator는 세 가지 오케스트레이션 모드를 제공해요. 차이는 서브에이전트끼리 지속적인 상호작용이 필요한지, 그리고 흐름이 미리 정해져 있는지에 있죠. 모드를 잘못 고르는 건 초보자가 가장 자주 겪는 문제라서, 먼저 비교부터 살펴볼게요:

모드 트리거 방식 협업 방식 적합한 작업
Swarm(스웜) 모드 /swarm 여러 서브에이전트를 한 번에 파견해 병렬로 작업하고, 마지막에 취합 독립적인 부분으로 나눌 수 있는 대규모 작업
Teamwork(팀워크) 모드 /teamwork 에이전트 팀이 지속적으로 협업하며 여러 차례 상호작용 반복적인 논의와 상호 의존이 필요한 복잡한 프로젝트
Workflow(워크플로) 모드 /run-workflow 사전 정의된 유향 그래프, 분기·루프·조건 라우팅 지원 흐름이 고정되어 있고 안정적인 재현이 필요한 작업

고를 때는 아래 순서대로 스스로에게 물어보세요. 흐름이 매번 똑같다면 Workflow를 고르세요. 흐름이 고정되어 있지는 않은데 서브 작업끼리 소통이 거의 필요 없다면 Swarm을 고르세요. 서브 작업끼리 왔다 갔다 하며 맞춰가야 한다면, 예를 들어 프런트엔드가 인터페이스를 바꿨을 때 백엔드도 따라 수정해야 하는 상황이라면 Teamwork을 고르세요. Swarm이 병렬성은 가장 높고 대기 시간도 가장 짧지만, 그만큼 작업을 독립적으로 나눌 수 있어야 한다는 요구도 가장 까다로워요.


4 Antigravity Orchestrator의 /swarm 스웜 메커니즘

4.1 /swarm의 5단계 작업 흐름

/swarm은 Orchestrator의 가장 대표적인 기능으로, 전체 과정은 다음 5단계로 진행됩니다.

  1. 사용자가 /swarm 명령어를 입력하고 작업 설명을 함께 전달합니다.
  2. 메인 에이전트(Orchestrator Agent)가 작업을 분석해 여러 하위 작업으로 자동 분해합니다.
  3. 하위 작업마다 서브 에이전트를 동적으로 생성합니다. 이른바 ‘동적 자가 복제 서브 에이전트’입니다.
  4. 서브 에이전트들이 병렬로 실행되고, 결과는 메인 에이전트로 모입니다.
  5. 메인 에이전트가 출력을 통합해 최종 Artifacts를 생성합니다.

여기서 2단계와 5단계가 최종 품질을 좌우합니다. 분해가 깔끔하지 않으면 서브 에이전트끼리 작업이 겹치거나 빠지는 부분이 생기고, 통합 능력이 부족하면 각 부분이 제대로 동작하는 하나의 완성물로 조립되지 못합니다. 그래서 메인 에이전트에는 보통 추론 능력이 더 뛰어난 모델을 사용하는 것이 좋습니다.

4.2 동적 서브 에이전트와 정적 서브 에이전트

Antigravity Orchestrator는 두 가지 유형의 서브 에이전트를 지원하며, 하나의 작업 안에서 함께 섞어 쓸 수도 있습니다.

  • 동적 자가 복제 서브 에이전트: 실행 중에 필요할 때 생성되며, 메인 에이전트의 컨텍스트 일부를 물려받습니다. 임시로 쪼개낸 하위 작업에 적합합니다.
  • 정적 커스텀 서브 에이전트: 미리 정의해 둔 전용 에이전트로, 고정된 시스템 지시문과 도구 세트를 갖습니다. 코드 리뷰, 테스트 생성처럼 반복적으로 등장하는 전문 작업에 적합합니다.

눈여겨볼 설계가 하나 더 있는데, 바로 서브 에이전트마다 서로 다른 모델을 사용할 수 있다는 점이에요. 예를 들어 깊은 추론이 필요한 부분은 Carbon으로 처리하고, 빠르고 단순한 작업은 Hydrogen으로 처리하는 식입니다. 이렇게 ‘작업 난이도에 따라 모델을 배분하는’ 방식은 멀티 에이전트 시스템에서 비용을 관리하는 핵심 수단인데, 자세한 내용은 7절에서 다룹니다.

4.3 사례: Pelican Campus Quest는 어떻게 분해되었나

Sundar Pichai가 시연한 /swarm 사례는 학습용 샘플로 아주 좋습니다. 메인 에이전트가 받은 작업은 ‘Google Mountain View 캠퍼스를 GBike로 탐험하는 오픈 월드 3D 게임 만들기’였고, 이를 세 개의 병렬 작업선으로 쪼갰습니다.

  • 3D 에셋 모델링: 서브 에이전트가 Blender를 사용하고, Omni / Nano Banana가 생성한 소스를 참조합니다.
  • 게임 엔진 구축: 서브 에이전트가 Three.js와 WebGL 셰이더를 사용합니다.
  • 오디오 시스템: 서브 에이전트가 Web Audio API와 Lyria 음악을 함께 사용합니다.

최종적으로 세 부분이 자동으로 통합되어 브라우저에서 바로 플레이할 수 있는 게임이 완성됩니다. 이 사례가 Swarm에 적합했던 이유는, 모델·엔진·오디오 세 영역이 인터페이스 수준에서 포맷만 맞춰두면 개발 과정에서 서로 기다릴 필요가 거의 없기 때문입니다. 3절에서 말한 ‘분해 가능성’이 바로 이것입니다.


5 Antigravity Orchestrator vs LangGraph, CrewAI, AutoGen

5.1 비교 기준

아래 비교는 포지셔닝 차이만 살펴보고 성능은 비교하지 않아요. 각 도구의 형태 자체가 완전히 다르기 때문인데요, 하나는 완전한 플랫폼이고 나머지는 Python 라이브러리예요. 비교 항목은 제품 포지셔닝, 에이전트 추상화, 브라우저 통합, 모델 바인딩, 배포 방식, 오픈소스 정도입니다.

antigravity-orchestrator-explained-from-zero-ko-image-2

비교 항목 Antigravity LangGraph CrewAI AutoGen
포지셔닝 완전한 IDE + 플랫폼 Python 라이브러리 Python 라이브러리 Python 라이브러리
에이전트 모델 동적 자가 복제 + 정적 그래프 노드 역할 정의 대화형 에이전트
브라우저 통합 네이티브 Chrome 확장 없음 없음 없음
모델 바인딩 Gemini에 최적화 모델 독립적 모델 독립적 모델 독립적
배포 Cloud Run / Docker 직접 배포 직접 배포 직접 배포
오픈소스 SDK는 오픈소스, 코어는 클로즈드 소스 완전 오픈소스 오픈소스 오픈소스
멀티 모델 연동 가이드 Gemini 생태계 내 APIYI(apiyi.com)로 통합 연동 가능 좌측과 동일 좌측과 동일

5.2 선택 가이드

그래프 구조의 제어력과 완전한 오픈소스라는 점에서는 LangGraph가 여전히 앞서지만, IDE 통합, 브라우저 조작, 배포 파이프라인을 직접 구축해야 해요. Antigravity Orchestrator는 별도 세팅 없이 바로 쓸 수 있다는 점이 강점인데요, /swarm 한 줄이면 작업 분해, 병렬 실행, 결과 통합까지 끝나고 브라우저도 기본으로 조작할 수 있어요. CrewAI의 역할 정의 방식은 직관적이고, AutoGen은 대화 중심으로 협업을 이끄는 데 강점이 있죠. 다만 두 라이브러리 모두 배포와 도구 체인은 직접 처리해야 해요.

여기서 간단한 선택 규칙을 뽑을 수 있어요. 팀이 이미 Gemini를 깊게 사용 중이고 IDE 안에서 바로 멀티 에이전트 기능을 원한다면 Antigravity를 고르면 됩니다. 반대로 여러 모델을 오가며 써야 하거나 코어 엔진의 감사 가능성이 중요하다면 오픈소스 라이브러리 쪽이 답이에요.

💡 선택 팁: 오픈소스 라이브러리로 간다면 모델 연동 계층은 OpenAI 호환 인터페이스로 통일하는 걸 추천해요. APIYI(apiyi.com)를 이용하면 API 키 하나만으로 LangGraph나 CrewAI에서 GPT, Claude, Gemini 같은 모델을 자유롭게 전환할 수 있고, 하나의 오케스트레이션 그래프 안에서 노드마다 다른 모델을 배정하기도 쉬워져요.


6. Antigravity Orchestrator, 처음부터 시작하는 방법

6.1 권장 학습 순서

“먼저 써 보고, 그다음엔 직접 작성해 보고, 마지막으로 다듬는다”는 흐름을 따라 입문 경로를 7단계로 나눌 수 있어요.

  1. 개념: Antigravity가 무엇이고 왜 필요한지 이해하기 (이 글의 1~2절).
  2. 설치: Web App, IDE 다운로드, 명령줄 설치 세 가지 방법 중 하나 고르기.
  3. 첫 번째 에이전트: SDK로 Hello World 에이전트 작성하기.
  4. Orchestrator 이해: Workflow Runtime과 Task API의 관계 파악하기.
  5. 첫 번째 Swarm: IDE나 CLI에서 /swarm을 직접 실행해 보기.
  6. 서브 에이전트 심화: 동적 서브 에이전트와 정적 서브 에이전트의 효과 비교하기.
  7. 베스트 프랙티스: 모델 선택, 권한 관리, 비용 관리.

6.2 Antigravity SDK로 첫 에이전트 만들기

SDK로 만드는 최소한의 에이전트는 설정 객체 하나와 한 번의 대화 호출만 있으면 됩니다:

from google.antigravity import Agent, LocalAgentConfig

config = LocalAgentConfig(
    system_instructions="You are an expert assistant.",
)
async with Agent(config) as agent:
    response = await agent.chat("Hello!")
    print(await response.text())

스트리밍 출력이 필요하면 response를 그대로 순회하면 돼요. 에이전트에 도구를 추가하는 것도 간단합니다. 일반 Python 함수를 tools에 전달하기만 하면 됩니다:

import sys

# 스트리밍 응답
async for token in response:
    sys.stdout.write(token)
    sys.stdout.flush()

# 커스텀 도구
def get_weather(city: str) -> str:
    return f"It's sunny in {city}."

config = LocalAgentConfig(tools=[get_weather])

함수 시그니처의 타입 어노테이션은 에이전트가 매개변수의 의미를 파악하는 데 도움이 돼요. 실제 프로젝트에서는 도구 함수에 docstring을 꼼꼼하게 작성하는 걸 추천합니다. 그래야 메인 에이전트가 작업을 분해할 때 어떤 도구를 어떤 서브 에이전트에게 넘길지 더 쉽게 판단할 수 있거든요.

6.3 OpenAI 호환 인터페이스로 스웜의 팬아웃과 팬인 시뮬레이션하기

Orchestrator의 핵심 엔진은 클로즈드 소스지만, “분할—병렬—취합”이라는 발상 자체는 어떤 모델로도 재현할 수 있어요. 아래 코드는 최소 형태의 /swarm을 시뮬레이션한 것으로, 메인 에이전트가 분해와 통합을 담당하고 서브 에이전트가 병렬로 실행되는 구조입니다. Antigravity의 실제 구현이 아니라, 4.1절의 5단계 흐름을 이해하도록 돕는 교육용 예제예요.

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # APIYI OpenAI 호환 인터페이스
)

PLANNER_MODEL = "your-reasoning-model"  # 메인 에이전트: 추론 성능이 좋은 모델, 플랫폼 모델 목록 기준
WORKER_MODEL = "your-fast-model"        # 서브 에이전트: 속도가 빠르고 비용이 낮은 모델

async def ask(model: str, system: str, prompt: str) -> str:
    resp = await client.chat.completions.create(
        model=model,
        messages=[{"role": "system", "content": system},
                  {"role": "user", "content": prompt}],
    )
    return resp.choices[0].message.content
전체 스웜 시뮬레이션 코드 보기
import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # 하나의 키로 여러 모델 호출
)

PLANNER_MODEL = "your-reasoning-model"
WORKER_MODEL = "your-fast-model"

async def ask(model: str, system: str, prompt: str) -> str:
    resp = await client.chat.completions.create(
        model=model,
        messages=[{"role": "system", "content": system},
                  {"role": "user", "content": prompt}],
    )
    return resp.choices[0].message.content

async def swarm(task: str, max_workers: int = 3) -> str:
    # Step 2: 메인 에이전트가 작업을 분해 (Fan-out 이전)
    plan = await ask(
        PLANNER_MODEL,
        "你是主代理。把任务拆成互相独立、可并行的子任务,每行一个,不要编号。",
        task,
    )
    subtasks = [s.strip("- ").strip() for s in plan.splitlines() if s.strip()]
    subtasks = subtasks[:max_workers]

    # Step 3-4: 각 서브태스크마다 서브 에이전트를 만들어 병렬 실행 (Fan-out)
    results = await asyncio.gather(*[
        ask(WORKER_MODEL, "你是只负责单一子任务的子代理,输出简洁可交付的结果。", s)
        for s in subtasks
    ])

    # Step 5: 메인 에이전트가 결과를 통합 (Fan-in)
    merged = "\n\n".join(f"【{s}】\n{r}" for s, r in zip(subtasks, results))
    return await ask(
        PLANNER_MODEL,
        "你是主代理。整合子代理的产出,消除重复与冲突,输出最终方案。",
        f"原始任务:{task}\n\n子代理产出:\n{merged}",
    )

if __name__ == "__main__":
    print(asyncio.run(swarm("为一个浏览器小游戏设计美术、玩法和音效三部分方案")))

이 코드는 두 가지 핵심 포인트를 보여줍니다. 메인 에이전트와 서브 에이전트가 서로 다른 모델을 사용한다는 점, 그리고 서브태스크가 asyncio.gather로 병렬 실행된다는 점이에요. 이 코드를 4절과 나란히 놓고 비교해 보면, Orchestrator가 Layer 3에서 상태 관리, 실패 재시도, 산출물 통합 같은 작업을 자동으로 얼마나 많이 대신 처리해 주는지 이해할 수 있습니다.

🚀 빠른 시작: 위 예제는 그대로 실행할 수 있어요. APIYI apiyi.com에서 API 키를 발급받고, 두 모델 이름을 플랫폼에서 사용 가능한 모델로 바꾸기만 하면 됩니다. 신규 사용자에게 무료 테스트 크레딧이 제공되니, 분할과 통합 실험을 몇 차례 해보기에 충분해요.


7 Antigravity Orchestrator의 모범 사례와 영향

7.1 모델 선택: 작업 난이도에 따른 계층화

멀티 에이전트 시스템의 비용은 하위 에이전트 수에 비례해 배로 불어나기 때문에, 모델 계층화가 첫 번째 원칙이에요. 분해와 통합처럼 전체 품질을 좌우하는 단계는 강력한 추론 모델, 예를 들어 Antigravity의 Carbon에 맡기고, 포맷 변환, 보일러플레이트 코드, 단순 조회 같은 작업은 Hydrogen 같은 빠른 모델에 맡기는 거죠. Antigravity 밖에서 비슷한 아키텍처를 재현할 때도 이 계층화 발상을 그대로 가져올 수 있어요. APIYI(apiyi.com)를 쓰면 같은 코드 안에서 역할별로 다른 모델을 지정할 수 있으니, 품질과 비용을 비교해 본 다음에 설정을 확정하면 됩니다.

7.2 권한 관리: 하위 에이전트의 도구 범위 제한

동적 하위 에이전트는 메인 에이전트의 컨텍스트 일부를 물려받아요. 이때 도구 권한을 좁혀두지 않으면 하위 에이전트 하나가 맡은 역할을 벗어난 작업을 해버릴 수 있죠. 더 안전한 방법은 이래요. 파일 쓰기, 명령어 실행, 브라우저 조작 같은 기능이 필요하면 정적 커스텀 하위 에이전트에 넣고 시스템 지침과 도구 집합을 명확히 지정하세요. 동적 하위 에이전트는 읽기 전용이나 생성형 작업만 맡기는 거예요. 프로덕션 환경에 손대는 작업이라면 사람이 확인하는 단계를 꼭 남겨두고요.

7.3 비용 관리: 먼저 추정하고 병렬도 넓히기

/swarm은 병렬도가 높을수록 대기 시간이 짧아지지만, 그만큼 토큰 소모도 커져요. 작은 작업으로 먼저 메인 에이전트가 보통 하위 작업을 몇 개로 나누는지, 하위 작업 하나가 얼마나 드는지 관찰한 뒤에 더 큰 작업으로 범위를 넓힐지 결정하는 걸 권해요. 예산에 민감한 팀이라면 오픈소스 오케스트레이션 라이브러리에서 저가 모델로 분할 전략을 먼저 검증해 보세요. 사용량 기반 과금인 APIYI(apiyi.com)는 실험 비용 관리에 편리하고, 흐름이 잘 돌아가는 걸 확인한 다음 Antigravity로 옮겨서 완전한 플랫폼 기능을 갖추면 됩니다.

7.4 Antigravity Orchestrator가 개발자에게 주는 영향

Orchestrator의 등장은 멀티 에이전트 오케스트레이션이 ‘엔지니어가 그래프 구조를 직접 작성하던 방식’에서 ‘사용자가 명령 한 줄로 실행하는 방식’으로 옮아가고 있음을 보여줘요. 진입 장벽은 낮아지지만, 동시에 플랫폼 종속이라는 대가도 따라옵니다. 오픈소스였던 Gemini CLI는 이미 서비스가 중단됐고, 핵심 엔진은 클로즈드소스이며 주로 Gemini에 맞춰 최적화돼 있죠. 개인 개발자나 Gemini 중심 팀에게는 효율이 눈에 띄게 좋아지는 선택이에요. 반면 여러 모델 지원, 감사 가능성, 프라이빗 배포가 필요한 팀에게는 오픈소스 프레임워크에 통합 모델 접속 레이어를 얹는 조합이 여전히 더 유연합니다.

최종 판단 방법은 아주 간단해요. 지금 손에 있는 실제 작업 하나를 골라 서로 의존하지 않는 세 개의 하위 작업으로 나눠 보세요. 나눠진다면 /swarm이 상당한 시간을 아껴줄 가능성이 크고, 나눠지지 않는다면 Teamwork나 Workflow 모드, 혹은 단일 에이전트가 더 적합한 출발점이에요.

antigravity-orchestrator-explained-from-zero-ko-image-3


참고 자료

  1. xkcd 353 – Python: import antigravity 이스터에그의 출처

    • 링크: xkcd.com/353
    • 설명: Antigravity라는 이름의 문화적 기원을 이해하는 데 도움이 돼요
  2. Google Antigravity 입문 영상: 공식 시작하기 데모

    • 링크: youtube.com/watch?v=nTOVIGsqCuY
    • 설명: Antigravity를 처음 접하는 개발자에게 딱 좋아요
  3. Sundar Pichai 트윗: /swarm 기능 데모

    • 링크: twitter.com/sundarpichai/status/2120198811297694192
    • 설명: Gemini 4 Carbon 공개 당시의 공식 데모예요
  4. Pelican Campus Quest 플레이 가능 버전: /swarm으로 생성된 브라우저 게임

    • 링크: aistudio.google.com/apps/bundled/pelican-campus-quest
    • 설명: 스웜 모드의 최종 결과물을 직접 체험할 수 있어요

작성자: APIYI 기술 팀
기술 교류: APIYI apiyi.com 홈페이지에서 언제든 문의해 주세요. 더 많은 자료는 docs.apiyi.com 문서 센터에서 확인하실 수 있습니다

관련 글

Similar Posts