AG2 1.0 Beta: AutoGen classic 이후 에이전트 런타임을 ACP·Tool Search·NLIP로 재구성하는 법

왜 지금 봐야 하나

AG2 v1.0.0b0은 2026년 7월 3일에 공개됐다. 이 릴리스가 중요한 이유는 새 모델 하나를 붙이거나 툴을 조금 늘린 정도가 아니라, 에이전트 런타임의 경계 자체를 다시 그었기 때문이다.

• 패키지 기준이 autogen에서 ag2로 넘어간다.
• ConversableAgent, GroupChat 같은 classic 표면은 더 이상 소스 트리의 중심이 아니다.
• 외부 CLI 코딩 에이전트는 ACP(Agent Client Protocol)로 붙인다.
• 많은 수의 툴은 Tool Search로 필요할 때만 서버 사이드에서 펼친다.
• 원격 에이전트는 NLIP(ECMA-430) HTTP 경계 밖으로 뺄 수 있다.

즉, 이 릴리스는 "에이전트를 하나 더 만든다"가 아니라 에이전트 프로세스·도구·원격 통신을 어떤 경계로 나눌지를 새로 결정하게 만든다. 기존 AutoGen 계열 코드베이스를 운영 중이거나, Codex/Claude Code 같은 외부 코딩 에이전트를 오케스트레이션하려는 팀이라면 이 변화는 API 취향 문제가 아니라 배포 구조 문제다.

핵심 변화 한눈에 보기

AG2 1.0 Beta의 새 경계

1. classic 제거는 import rename이 아니다

AG2의 README는 분명하게 말한다. protocol-driven framework가 이제 top-level package이고 import는 ag2를 써야 하며, classic framework(ConversableAgent, GroupChat 등)는 제거됐다.

그런데 운영자 관점에서 더 중요한 신호는 두 번째다.

• 소스 트리에는 더 이상 ConversableAgent, GroupChat 구현이 중심 표면으로 존재하지 않는다.
• 대신 migration 문서는 GroupChat을 ag2.network의 WorkflowAdapter와 TransitionGraph로 옮기는 법을 설명한다.
• TransitionGraph는 JSON 직렬화가 가능하고 Hub.hydrate()를 거쳐도 살아남는 데이터 구조다.

이 말은 예전처럼 "파이썬 객체를 서로 연결해 두고 인프로세스 turn manager가 굴린다"는 사고방식에서, 채널 + 그래프 + 허브가 권한을 갖는 구조로 넘어간다는 뜻이다.

왜 이게 중요한가

기존 classic 코드는 handoff와 종료 조건이 에이전트 객체와 콜백에 섞여 있을 가능성이 높다. AG2 1.0 beta의 방향은 그 규칙을 채널 레벨의 데이터로 끄집어내는 것이다. 그래서 migration은 다음 순서로 생각하는 편이 맞다.

1. GroupChat을 복제하려 하지 말고, 어떤 전이 규칙이 필요한지 먼저 적는다.
2. 그 규칙을 TransitionGraph로 표현한다.
3. 에이전트는 점점 얇아지고, 허브와 채널이 turn-taking과 audit를 맡는다.

문서 드리프트도 함께 봐야 한다

재미있는 점은 같은 tag의 README 아래쪽에는 아직 ConversableAgent, GroupChat 예제가 남아 있다는 것이다. 즉, 릴리스 방향은 이미 classic 이후를 가리키지만, 문서 표면은 완전히 정리되지 않았다.

운영자가 이 신호를 어떻게 읽어야 하냐면 간단하다.

• 이 버전은 새 경계를 실제 코드에 심어 둔 beta다.
• 따라서 latest 문서만 보고 migration을 설계하면 안 된다.
• release note, tag-pinned source, migration doc를 함께 봐야 한다.

2. ACP는 "외부 CLI 에이전트"를 AG2의 모델 슬롯으로 끌어들인다

이번 릴리스에서 가장 실무적인 변화는 ACP다. ACPConfig는 ModelConfig를 구현하고, create()는 ACPClient를 반환한다. 즉 AG2 입장에서는 외부 CLI 코딩 에이전트도 결국 하나의 LLM client처럼 보인다.

구조적으로 어떻게 동작하나

ACPClient의 주석은 핵심을 명확하게 설명한다.

• AG2의 한 model turn = ACP의 한 session/prompt 다.
• 세션은 context.stream.id 기준으로 run 동안 재사용된다.
• 에이전트 쪽 tool loop는 그 한 번의 ACP prompt 내부에서 돌고, AG2는 session/update 스트림을 이벤트로 받는다.
• turn_timeout이 나면 즉시 coroutine을 죽이지 않고 먼저 session/cancel을 보내고, cancel_timeout만큼 협조적 취소를 기다린다. 그래도 안 끝나면 subprocess를 hard-stop 한다.

이건 단순한 래퍼가 아니다. 외부 CLI 에이전트의 프로세스 수명주기와 권한 정책을 AG2가 중재하는 브리지다.

ACP에서 바로 보이는 운영 포인트

preset이 주는 의미와 함정

AG2는 세 가지 preset을 넣었다.

• ClaudeCodeConfig
• CodexConfig
• OpenCodeConfig

좋은 점은 launch command와 기본 정책을 바로 제공한다는 것이다. 하지만 운영자가 놓치기 쉬운 함정도 있다.

1. model 필드는 실제 launch flag가 아닐 수 있다.

- CodexConfig는 실제 모델 선택을 adapter의 MODEL_PROVIDER 환경변수에 둔다. - OpenCodeConfig는 아예 opencode.json 쪽 설정을 따르며, model 필드는 response metadata에만 남는다. - ClaudeCodeConfig도 실제 선택은 ANTHROPIC_MODEL 환경변수 쪽이다.

1. ACP adapter binary는 별도 설치 대상이다.

- Python 패키지 ag2[acp]만으로 끝나는 구조가 아니다. - Claude/Codex는 ACP adapter executable 또는 npx 경로를 준비해야 한다.

1. 권한 정책을 자동화하기 전에 파일/터미널 경계를 먼저 줄여야 한다.

- permission_policy="auto"가 편한 건 맞지만, fs_root를 느슨하게 두면 에이전트에 너무 넓은 작업면을 주게 된다.

최소 예시

from ag2 import Agent
from ag2.acp import CodexConfig

agent = Agent(
    "repo_coder",
    config=CodexConfig(
        cwd="/srv/work/repo",
        permission_policy="ask",
        turn_timeout=120,
        cancel_timeout=5,
    ),
)

이 예시의 진짜 의미는 "Codex를 붙였다"가 아니라, Codex 프로세스를 AG2가 승인·취소·파일 경계와 함께 관리한다는 데 있다.

3. Tool Search는 "툴을 어떻게 context에 싣는가"를 바꾼다

ToolSearchTool의 docstring은 의도를 직설적으로 설명한다.

• 많은 툴 정의를 upfront로 전부 프롬프트에 넣지 않는다.
• 이름과 설명만 searchable reference로 제공한다.
• 모델이 필요할 때 search tool을 호출하면 provider가 server-side에서 일치하는 툴 정의를 확장한다.
• 결과적으로 fixed context가 작아지고 prompt cache를 보존할 수 있다.

이건 RAG처럼 문서를 검색하는 기능이 아니다. 툴 정의 자체를 지연 로딩하는 메커니즘이다.

중요한 세부 동작

1. wrapper는 원본 툴을 변형하지 않는다.

- 테스트는 원본 get_weather.schema.defer_loading이 계속 False로 남는다는 점을 확인한다. - 즉, deferred는 emitted copy에만 붙는다.

1. Anthropic과 OpenAI의 표면이 다르다.

- Anthropic은 regex와 bm25 두 variant를 구분한다. - OpenAI는 단일 tool_search 타입으로 노출된다.

1. OpenAI Chat Completions API에는 이 기능이 없다.

- mapper는 deferred tool을 Chat Completions에 보내려 하면 fast-fail 한다. - Responses API를 써야만 deferred loading이 성립한다.

언제 유용한가

• 사내 운영툴이 수십 개라서 툴 schema가 프롬프트를 잡아먹을 때
• prompt cache 적중률을 지키고 싶을 때
• LLM이 자주 쓰는 툴은 몇 개뿐인데, 롱테일 툴 때문에 context가 비대해질 때

언제 아직 조심해야 하나

• provider별 search 품질과 ranking이 동일하다고 가정하면 안 된다.
• tool 설명이 모호하면 검색이 아니라 오탐을 부른다.
• OpenAI 쪽은 Responses API 전환이 같이 필요하므로, 기존 Chat Completions 기반 애플리케이션이라면 영향 범위가 생각보다 크다.

최소 예시

from ag2.tools import tool
from ag2.tools.builtin import ToolSearchTool

@tool
def get_weather(location: str) -> str:
    """Return current weather for a location."""
    return "sunny"

@tool
def echo(text: str) -> str:
    """Echo text."""
    return text

# get_weather는 필요할 때만 provider가 확장하고,
# echo는 즉시 로딩된다.
tools = [ToolSearchTool(get_weather), echo]

운영 관점에서는 이 기능을 켜기 전에 먼저 provider별 도구 호출 로그, 캐시 적중률, 잘못 검색된 툴 비율을 보아야 한다.

4. NLIP는 원격 에이전트를 HTTP 경계 밖으로 뺀다

NLIP 문서는 이 기능을 두 문장으로 정리한다.

1. NlipServer로 AG2 Agent를 표준 NLIP endpoint로 노출할 수 있다.
2. NlipConfig로 원격 NLIP endpoint를 로컬 Agent의 ModelConfig처럼 붙일 수 있다.

즉, ACP가 "외부 CLI 에이전트를 로컬 프로세스 안으로 감싼다"라면, NLIP는 반대로 에이전트를 HTTP 경계 밖으로 뺀 다음 다시 provider처럼 연결하는 방식이다.

이 표면이 실무에서 중요한 이유

문서에 따르면 NLIP 서버는 요청마다 독립 세션을 만든다.

• 요청이 들어오면 agent가 한 번 돌고 응답 후 세션이 정리된다.
• 서버가 대화 상태를 오래 들고 있지 않는다.
• 전체 AG2 conversation history는 wire 위 JSON submessage로 함께 실린다.

이 구조는 다음처럼 해석해야 한다.

• 장점: 프로세스 격리와 배포 독립성이 좋다. 언어/호스트가 달라도 붙이기 쉽다.
• 단점: 장기 대화 상태를 서버가 캐시해 주지 않는다. history가 길어질수록 payload 비용과 레이턴시가 커진다.

설치도 별도로 봐야 한다

NLIP는 ag2 extra로 묶여 있지 않다. 문서가 권장하는 설치는 다음과 같다.

pip install "ag2[openai]" "nlip-sdk>=0.1.0,<1" "nlip-server>=0.1.3,<1"
pip install uvicorn

즉 ACP와 마찬가지로, 패키지 extra 하나로 모든 실행면이 해결되는 구조가 아니다. 프로토콜 계층의 런타임 의존성을 분리해서 들고 가야 한다.

5. 이 릴리스를 운영자가 해석하는 방법

AG2 1.0 beta를 "AutoGen의 다음 버전" 정도로 보면 실수를 한다. 이 릴리스는 더 가깝게 말하면 에이전트 운영체제의 표면을 재배치한 것이다.

1) classic 코드베이스는 먼저 분리 보관한다

기존 autogen/GroupChat 흐름이 있다면, 바로 같은 브랜치에서 import를 바꾸지 말고 다음을 분리한다.

• classic 유지 브랜치
• AG2 network 마이그레이션 브랜치
• ACP / Tool Search / NLIP를 붙인 새 런타임 실험 브랜치

이번 변화는 단일 diff로 다루기엔 경계가 너무 넓다.

2) ACP는 승인 정책부터 보수적으로 시작한다

초기에는 다음이 안전하다.

• permission_policy="ask"
• fs_root를 repo 루트보다 더 좁게 설정 가능한지 검토
• allow_terminal=True가 정말 필요한지 확인
• turn_timeout과 cancel_timeout을 명시해 hung subprocess를 방치하지 않기

3) Tool Search는 "툴이 많을 때만" 켠다

툴이 5개인 환경에서는 의미가 작다. 반대로 30개, 50개 이상이 되면 fixed context와 prompt cache 손실이 커지므로 가치가 커진다. 즉 이 기능은 범용 default라기보다 툴 수가 많은 환경을 위한 scaling knob로 보는 편이 맞다.

4) NLIP는 stateful chat보다 service boundary에 더 잘 맞는다

요청마다 세션을 만들고 full history를 보내는 구조라서, 긴 대화 메모리를 서버 쪽에 두는 패턴과는 결이 다르다. 대신 사내 검색 에이전트, 날씨/사내 운영 API 에이전트, 규정 검증 에이전트처럼 도메인 기능을 HTTP 서비스로 분리하는 용도엔 잘 맞는다.

6. 가장 먼저 돌려볼 검증 체크리스트

ACP 검증

• [ ] adapter binary가 실제로 실행되는가 (codex-acp, claude-agent-acp, opencode acp)
• [ ] permission_policy="ask"에서 승인 이벤트가 기대대로 노출되는가
• [ ] fs_root 밖 경로 접근이 실제로 차단되는가
• [ ] 장기 실행 turn에서 turn_timeout → session/cancel → hard-stop 순서가 의도대로 동작하는가
• [ ] 모델 선택이 model= 인자가 아니라 env/config 쪽에서 결정된다는 점을 운영 문서에 적어 두었는가

Tool Search 검증

• [ ] Anthropic이면 regex/bm25 중 어느 모드를 쓰는지 명시했는가
• [ ] OpenAI면 Chat Completions가 아니라 Responses API 경로를 쓰는가
• [ ] deferred tool이 없을 때 대비해 prompt token, cache hit, latency baseline을 저장했는가
• [ ] tool description 품질 때문에 오탐이 나지 않는가

NLIP 검증

• [ ] /nlip/ endpoint를 reverse proxy / auth layer 뒤에 둘지 결정했는가
• [ ] full history 전달로 payload가 얼마나 커지는지 측정했는가
• [ ] stateful memory를 server process가 보관하지 않는다는 점을 애플리케이션 설계에 반영했는가

문서 드리프트 검증

• [ ] README 예제가 아직 classic을 가리키는지 확인했는가
• [ ] roadmap가 ACP/NLIP/Deferred tools를 어느 성숙도로 분류하는지 확인했는가
• [ ] 설계 문서는 latest가 아니라 tag-pinned source URL 기준으로 남겼는가

결론

AG2 1.0 beta의 핵심은 기능 수가 아니라 경계의 재배치다.

• classic 대화 관리 표면은 뒤로 물러난다.
• 오케스트레이션은 TransitionGraph와 허브가 가져간다.
• 외부 CLI 에이전트는 ACP로 편입된다.
• 툴 수가 많아지면 Tool Search로 컨텍스트 적재 방식을 바꾼다.
• 원격 에이전트는 NLIP로 HTTP 경계 밖에 둔다.

이런 구조 변화는 데모에서는 잘 안 보이지만, 운영에서는 바로 드러난다. import 변경, subprocess 수명주기, 승인 정책, provider 호환성, state 전달 방식이 한 번에 바뀌기 때문이다. 그래서 이 릴리스를 도입할 때는 성능 수치보다 먼저 런타임 경계가 의도대로 통제되는지를 확인하는 편이 맞다.

References

• AG2 v1.0.0b0 release notes
• AG2 README at v1.0.0b0
• AG2 roadmap at v1.0.0b0
• Migration from GroupChat to ag2.network
• ACP config source (ag2/acp/config.py)
• ACP client source (ag2/acp/client.py)
• Tool Search implementation (ag2/tools/builtin/tool_search.py)
• OpenAI mapper note on deferred tools / Responses API
• Anthropic mapper note on tool-search variants
• NLIP integration docs