NVIDIA-labs OO Agents
네이티브 파이썬 객체지향 에이전트

문제의식은 명확하다. 기존 에이전트 개발 키트들은 도구·메모리·워크플로·핸드오프 같은 유용한 프리미티브를 제공하지만, 타입 인터페이스·변수 스코핑·제어 흐름·비동기 실행·객체 상태처럼 일반 프로그래밍 언어에 이미 성숙한 등가물이 있는 역량을 위해 새 프로그래밍 모델을 배우게 만든다. 이 추상화들은 개발자에게 익숙할 뿐 아니라 모델의 학습 데이터에도 광범위하게 존재한다 — NOOA는 이 사실을 활용해 "인간의 학습 곡선 제거"와 "즉각적 에이전트 준비성(agent readiness)"이라는 이중의 이득을 얻는다.

from nooa import Agent

TicketKind = Literal["refund", "damaged", "other"]

# 반환 타입: triage()가 반환하기 전에 런타임이 검증한다.
# 설명과 제약 조건은 모델에게 보인다.
class Ticket(BaseModel):
    kind: TicketKind
    priority: int = Field(ge=1, le=5, description="Urgency from 1 (low) to 5 (high).")
    summary: str = Field(description="Customer-visible summary of the issue.")

# Agent는 파이썬 객체다.
class SupportAgent(Agent):
    """You are a support agent for a customer service system."""

    # 객체 상태: 모델에게 보이고, 참조로 전달된다.
    order_db: OrderDB

    # 실제 본문: 평범한 파이썬. 결정론적, 테스트 가능, 모델이 호출 가능.
    def is_refund_eligible(self, order: Order) -> bool:
        """Return whether an order is eligible for a refund."""
        return order.delivered and order.days_since_delivery <= 30

    # "..." 본문: 에이전트 메서드. Predict는 단발 타입 지정 LLM 호출.
    @strategy(PredictStrategy())
    async def classify(self, message: str) -> TicketKind:
        """Classify the customer message into the best ticket kind."""
        ...

    # 기본 전략 CodeAct: 모델이 파이썬을 작성하는 루프를 돈다.
    # order를 조사하고 is_refund_eligible()·classify()를 호출하며 Ticket을 반환해야 한다.
    # 입력은 직렬화된 텍스트가 아니라 살아 있는 객체다.
    @strategy(CodeActStrategy())
    async def triage(self, message: str, photo: Image | None, order: Order | None) -> Ticket:
        """Triage a customer message and create a support ticket."""
        ...

메서드 선언이 곧 루프의 사양이다 — 시그니처는 구조화된 입력과 출력 검증 계약을 주고, 독스트링은 프롬프트가 되며, self의 메서드와 임포트된 라이브러리는 호출 가능한 도구가 된다. triage가 이미지와 살아 있는 Order 객체를 받는 것처럼 입력은 텍스트에 국한되지 않고, 프롬프트에 직렬화되는 대신 참조로 전달된다. 이로써 프롬프트 엔지니어링은 소프트웨어 엔지니어링의 영역으로 돌아온다 — 행동을 테스트하고, 추적하고, 리팩터링하고, 버전 관리하고, 최적화할 수 있다.

NOOA가 단일 표면에 처음 결합한 6대 모델 대면 아이디어

14개 프레임워크·하니스를 조사한 결과 커뮤니티는 이미 이 아이디어들 여럿에 — 종종 실험적·부분적 기능으로 — 수렴하고 있으나, 여섯 가지 모두를 하나의 표면에 노출한 시스템은 NOOA가 최초라고 논문은 주장한다(§ 07 비교표 참조).

1. 파이썬 추상화를 재사용한다

   성숙한 파이썬 추상화가 존재하면 DSL을 만들지 않고 그대로 채택한다. 클래스가 에이전트를, 메서드가 역량을, 필드가 명시적·모델 가시적 지속 상태를, 타입 어노테이션이 계약을 정의하고, asyncio가 동시성을, 예외가 실패를 표현하며, 제어 흐름은 개발자와 에이전트 모두가 쓰는 평범한 파이썬이다.

   Loop engineeringObject state

2. 에이전트 루프를 메서드 호출로 재구성한다

   애플리케이션은 에이전트 루프를 비구조화 텍스트 교환이 아니라 타입 지정 입출력을 가진 일반 메서드 호출로 본다. 인자는 살아 있는 객체로 참조 전달되고, 하니스는 경계 프리뷰와 컨텍스트를 렌더링하며 반환값을 호출자에게 돌려주기 전에 검증한다.

   Typed I/OPass by reference

3. 결정론적 작업을 에이전트 루프 밖으로 옮긴다

   LLM은 의미 판단·종합·개방형 과제에 유용하다. 정확한 규칙, 산술, 파싱, 상태 전이는 결정론적 메서드의 몫이다. 그 경계는 코드에서 국소적으로 보인다 — 실제 본문이면 결정론, ... 본문이면 에이전트 루프.

4. 모델의 기존 파이썬 지식을 해방한다

   LLM은 이미 파이썬과 인기 라이브러리 사용법을 안다. 도구 호출 대신 일반 파이썬을 작성하게 하면 그 지식이 그대로 활용된다 — 루프·조건문, asyncio 동시성, DB 클라이언트, 시각화 라이브러리, 일반 임포트를 별도 프롬프팅이나 문서 학습 없이 사용한다.

   Code as action

5. 하니스를 명시적 API로 노출한다

   구조화 컨텍스트, 컨텍스트 렌더링, 이벤트 이력 같은 에이전트 고유 개념을 개발자와 모델 모두에게 파이썬 API로 노출한다. 가능한 한 내장 타입이나 기존 라이브러리를 닮게 만들어 익숙하고 자명하게 한다. 에이전트는 자기 자신의 컨텍스트에 접근하고 파이썬 프리미티브로 이를 관리한다.

   Harness APIs

두 가지 내장 전략

PredictStrategy는 분류·추출용 단발 전략이다 — 컨텍스트를 렌더링해 모델에게 값을 요청하고, 파이썬 반환 타입에 대해 출력을 검증하며, 실패 시 로컬 재시도 루프를 돈다. CodeActStrategy(기본값)는 같은 계약을 반복적 파이썬 REPL로 일반화한다 — 모델은 execute_python(...)으로 계산하고 내부 상태를 조사하고 헬퍼를 부르고 다른 생성 메서드를 호출하며, 하니스가 관찰 결과를 기록하고 갱신된 상태를 재렌더링하기를, 모델이 타입 검증되는 값으로 return_result(...)를 부를 때까지 반복한다. 한 에이전트가 메서드별로 두 전략을 섞어 쓸 수 있고, 데코레이터의 메서드별 오버라이드로 분류 메서드에는 작고 빠른 모델을, 개방형 메서드에는 기본 모델을 배정할 수 있다. 같은 에이전트에 대한 외부 호출은 직렬화되고, 중첩 호출은 스택 규율을 따르며, 다른 에이전트는 async/await로 병렬 실행된다.

컨텍스트의 3영역 — KV-캐시를 위한 설계

NOOA는 컨텍스트를 세 영역으로 분리한다. 정적 컨텍스트 블록(호출 내내 불변 — 시스템 프롬프트 약 1k자, CodeAct 전략 지침 약 2.5k자, 실행 컨텍스트, doc(self) 렌더링), 이벤트 이력(하니스가 생성하는 타입 지정 이벤트의 추가 전용 시퀀스 — 도구 호출, 파이썬 출력, 반환값. 각 이벤트는 고유 태그를 가진 타입 객체라 에이전트 코드가 평평한 트랜스크립트를 훑는 대신 질의할 수 있고, 긴 이력은 MemGPT식으로 요약 이벤트로 접을 수 있다), 동적 컨텍스트 블록(매 호출 전 재평가 — TODO 목록이나 self의 선택 필드 등. 각 블록은 자기 표현식을 expr="self.todo.status()"처럼 모델에게 보여 살아 있는 상태임을 강조한다). 이 배치는 KV-캐시 재사용을 극대화한다 — 정적 접두부는 불변, 이벤트 이력은 뒤에만 자라며, 휘발성 동적 블록은 꼬리에 놓여 살아 있는 상태의 갱신이 캐시된 접두부를 무효화하지 않는다.

# 정적 컨텍스트 블록은 단순한 key/value 쌍이다.
self.context["notes"] = "The user wants concise responses."

# 동적 컨텍스트 블록은 매 턴 평가되는 파이썬 표현식을 받는다.
self.context.set_dynamic("todo", "self.todo.status()")

# 이벤트 이력: 실행 트레이스를 질의하거나 압축한다.
recent_python = self.events.query(type="PythonOutput", limit=3)
self.events.collapse(start_tag, end_tag, summary_text="Model generated summary.")

참조 전달 — 컨텍스트 윈도를 넘어 확장하는 방법

컨텍스트 렌더링은 전체 프로그램 상태의 직렬화가 아니다. CodeAct 메서드는 인자를 살아 있는 파이썬 객체로 받고, 큰 인자에 대해 모델은 전체 값을 결코 보지 않는다. 점진적 공개(progressive disclosure)의 정신에 따라 모델은 변수 이름과 경계 프리뷰 — 구체적 타입, 실제 길이, 짧은 머리/꼬리 샘플 — 를 본다. 100개 정수 리스트로 호출된 메서드는 프롬프트에 이렇게 렌더링된다:

변수 records 자체는 잘리지 않는다 — 실행 환경에 로컬로 바인딩된 온전한 100개 원소 리스트이므로, 컨텍스트 윈도에는 열 개만 나타나도 모델은 전체를 인덱싱·슬라이싱·순회할 수 있다. 에이전트가 처리할 수 있는 데이터의 양은 프롬프트가 아니라 실행 환경이 결정한다 — 수백만 행 테이블이나 수 메가바이트 문자열을 받아도 프롬프트에는 고정 크기 프리뷰만 실린다. 프리뷰 API는 모델 학습 데이터에 있는 Rich의 pprint()에서 이름과 표면을 빌리되, 개방·폐쇄 모델 실험을 거쳐 출력 형식을 조정했다. 도구 호출도 양방향 모두 강타입·참조 전달이므로, 거대한 입력으로 메서드를 부르고 거대한 타입 결과를 변수에 바인딩해 슬라이스·집계·후속 호출로 프로그래밍적으로 처리할 수 있다 — 모델들이 bash에서 파일로 결과를 흘려보내며 즉흥적으로 하던 패턴을, 셀 간에 지속되는 타입 지정 라이브 변수로 대체한 것이다.

파이썬 실행과 반환 검증

CodeAct 셀은 제한된 Jupyter형 세션에서 실행된다. 메서드 인자, self로서의 살아 있는 에이전트, 에이전트 소스 파일의 임포트·메서드·상수가 로컬로 주입되고 await를 직접 쓸 수 있다. 셀 안에서 doc(obj)로 조사하고, pprint()로 경계 프리뷰를 찍고, 결정론적 헬퍼를 부르고, 생성 메서드를 await하고, 서브에이전트를 생성할 수 있다 — @strategy 데코레이터를 단 새 함수를 셀 안에서 정의해 asyncio.gather로 배치 팬아웃하는 병렬 서브에이전트 호출까지 평범한 파이썬으로 가능하다. eval·exec·compile·input·블로킹 이벤트루프 호출 같은 위험 API는 구체적 오류와 함께 거부되고, 구문 오류와 트레이스백은 소스 위치와 캐럿 컨텍스트를 담은 IPython 형식으로 돌아와 다음 턴의 모델이 노트북 셀 고치듯 코드를 수리한다. REPL 로컬은 메서드 스코프(셀 간 지속, 메서드 반환 시 소멸)이고, self나 라이브러리를 통한 것은 일반 파이썬처럼 메서드 밖으로 살아남는 부수효과를 가진다. 모델이 결과를 반환하면 하니스가 반환 어노테이션에 대해 검증한다 — 무효면 실패를 설명하는 오류 메시지가 모델로 가고 루프가 계속되며, 유효하면 호출자에게 돌아가 일반 파이썬 실행이 재개된다.

효과는 통제 실험으로 측정되었다 — ARC-AGI-3에서 파일 기반 노트를 쓴 동일 에이전트 대비 +11.8 RHAE 포인트. 부록 C의 하니스 비교에 따르면, 현행 시스템의 메모리는 ① 항상 컨텍스트에 실리는 평면 마크다운(CLAUDE.md, AGENTS.md 계열), ② 유사도 검색 벡터 저장소, ③ 구조화된 자기 편집 컨텍스트(Letta 블록 등)의 세 계열로 나뉘는데, NOOA는 세 계열의 교차점 — 파일 기반이고 사람이 감사 가능하며, 자동으로 쓰이고, 타입·점수·그래프 연결에 인지과학적 검색을 갖춘 형태 — 에 자리한다.

역량 테스트 — 88개 테스트 × 10개 모델 × 5회

타입 메서드 호출, 구조화 반환, 상태 있는 객체 조작, 헬퍼 라우팅, 컨텍스트·절단 처리, REPL 실행, 배치 루프, 오류 복구, 과제 분해를 다루는 36개 패밀리의 통합 테스트다. 전체 4,400 레코드 중 4,309 통과(97.9%) — 소형/효율 모델 96.0%, 대형/프런티어 모델 99.2%, 전 모델 91% 초과. 추론(reasoning) 모드별 분석에서 프런티어 모델은 모드와 무관하게 포화하는 반면, 모델 역량이 낮아질수록 추론의 가치가 단조 증가했다 (Nemotron Nano 52.5 → 84.8) — 추론이 소형 모델의 역량 평형장치로 작동한다.

잔여 실패는 여섯 개 스트레스 패밀리에 집중된다 — 대형 배치의 항목별 부기, 오류 복구, REPL 반복, 중간 답 정제, 반복 변환의 헬퍼 분해. 스트레스 부분집합의 통과율은 84.7%로, 전체 대비 격차가 대형/소형 간 3.2pt에서 23pt로 벌어진다. 5회 반복 실행이 일관성도 측정한다 — 880개 (테스트, 모델) 쌍의 94%가 5/5 통과였고, 대형 모델의 스트레스 실패는 전부 간헐적(0/5 없음)이었다. 이는 self 이해나 메서드 호출의 실패가 아니라 규율 있는 다단계 하니스 사용의 실패다 — 기본 인터페이스 유창성은 이미 보편화되었고, 신뢰할 수 있는 장기 배치·복구·분해가 남은 역량 프런티어다.

부록 B의 현미경 — 같은 과제, 네 가지 운명 (sentiment_batch, 50건 감성 분류)

교훈은 정교함과 성공이 직교한다는 것이다 — 가장 진보한 하니스 사용(Opus의 팬아웃)이 가장 값싼 규율("변수를 반환하라, 다시 타이핑하지 마라")에서 무너졌고, 가장 수수한 접근이 부기의 신중함으로 통과했다. 두 실패 모두 명시적 지침을 무시했고 안전한 경로가 인터페이스에 이미 준비되어 있었다 — § 08에서 논할 궤적 수준 강화학습의 정확한 표적이다.

CyberGym L1 — 오픈소스 1위의 취약점 검증

코드베이스를 조사해 보안 버그를 식별하고 이를 신뢰성 있게 트리거하는 PoC로 검증하는 벤치마크다. NOOA 에이전트는 셸과 todo 도구를 가진 CodeAct 에이전트로 트라이얼 컨테이너에서 실행되며, 결정론적 계층이 채점 역학을 프롬프트 루프 밖에 둔다 — 제출 메서드, 모델 요약이 기술된 취약점과 일치하는지 확인하는 경량 판정기, 비결정적 크래시를 걸러내는 재제출. 도메인 지식 주입은 없다 — 성능은 사이버보안 스티어링이 아니라 에이전트 아키텍처에서 나온다. 또한 규칙 기반 궤적 분석의 엄격한 "치팅 검사"로, 공개된 취약점 정보를 온라인에서 찾아보는 것이 아니라 문제 설정 자체로부터 유도했음을 보증했다.

ARC-AGI-3 — 6개 에이전트 시스템을 에이전트 하나 + 50줄 스킬로 압축

미지의 그리드 게임에 던져져 행동만으로 역학·목표·조작법을 발견해야 하는 상호작용 추론 벤치마크다. 동반 연구 DreamTeam — 공유 실행 가능 월드모델을 중심으로 협조하는 6개 전문 에이전트, 약 15만 줄, 1,821줄의 역할 프롬프트, 4,690줄의 하니스 측 역추론(retrodiction) 엔진 — 이 종전 최고 기록이었다. NOOA는 이 방법론이 급진적 단순화를 견디는지 실험했다 — 에이전트 하나와 50줄 스킬(전체 약 6.1k줄)로, 역할·프로토콜·평가 엔진은 프레임워크 프리미티브가 흡수한다: CodeAct REPL이 시뮬레이터, 컨텍스트 블록이 공유 상태, 메모리 서브시스템이 팀의 이월 장부다. 스킬은 encode(grid)→z(게임을 구동하는 소수 필드의 잠재 표현), predict(z, action)→z'(동역학), 매 턴 예측-관측 불일치를 유일한 정제 신호로 삼는 역추론, 신뢰 확보 후 자기 predict에 대한 탐색, 레벨 간 메모리 규율을 지시하며, 모든 턴은 submit_actions(..., rationale="predict: ...")로 끝난다 — 각 행동 배치가 검증되는 실험이다.

메모리 사용의 세 인터페이스가 모두 가동되었다 — 3,262건 기록, 12,654건 자발적 주입(턴당 4.1건으로 유계), 27,115건 의도적 도구 읽기(적중률 99%). 읽기 채널일수록 에이전트 스스로 중요 표시한 기억에 집중한다(평균 중요도: 기록 6.1 → 주입 7.2 → 의도적 회상 7.5). 격리도 철저했다 — 셀별 커널 강제 OS 샌드박스(Landlock 파일시스템 기본 거부, seccomp 네트워크 차단, 메모리/CPU 상한, 하드 타임아웃), 실행별 권한 강하, 게임 정체성의 종단간 익명화. 라이브 플릿을 30분마다 재스캔한 18회 레드팀 감사에서 어느 규칙에서도 유출 없음 — 네트워크 호출 0건, 게임 소스 바이트 0건, 13,335개 로그에서 실제 게임 식별자 0건, 유일한 탈출 시도 1건(파일시스템 정찰 셸 명령)은 셀 가드가 실행 전 차단했다.

핵심 발견: 어떤 시스템도 여섯 아이디어를 모두 결합하지 못했지만, 대부분이 일부를 채택 중이다. 다수 시스템이 각 아이디어의 변형을 갖되 모델이 아닌 개발자에게 노출하거나, 성숙한 추상화가 있는 자리에 새 추상화로 감싼다. 가장 새롭고 강력한 역량들 — Microsoft의 하니스 프로바이더, Pydantic의 CodeMode 하니스, OpenAI의 샌드박스 에이전트, Codex의 코드 모드 — 이 평가 기간 중에 출시되었고 대부분 실험적·플래그 게이트(†) 표시였다. 논문은 이를 필드가 이 여섯 아이디어로 수렴하고 있다는 신호로 읽는다. 참고로 bash 도구 자체가 약한 형태의 code-as-action이다 — 셸 명령줄은 파이프와 루프, CLI 도구를 가진 작은 프로그램이며, 이것이 tool-as-MCP 대비 tool-as-CLI 패키징이 부상한 이유를 설명한다. 다만 셸은 타입 없는 텍스트만 다루고 파일 밖 변수 지속성이 없다는 한계가 남는다.

관련 연구의 좌표

Typed I/O는 DSPy의 선언적 시그니처, LMQL의 디코딩 시점 제약, Outlines의 FSM 기반 구조 강제, Instructor·TypeChat의 스키마 검증-재프롬프트 계보에 선다. Code as action은 PAL·Program of Thoughts의 계산 오프로딩에서 CodeAct의 "실행 가능한 코드가 행동 양식 자체여야 한다"는 논증(JSON·텍스트 행동을 능가), smolagents의 라이브러리화, OpenHands의 대규모 실증으로 이어진다. Pass by reference는 Nightjar의 공유 프로그램 상태, TaskWeaver의 라이브 변수 교차 단계 상태, 그리고 프롬프트 자체를 REPL의 변수로 만드는 Recursive Language Models까지 급진화된 계보가 있으며, 파일 기반 참조 전달(다수 프레임워크)은 타입 정보를 잃는다는 한계가 있다. Object state는 MemGPT의 "LLM을 OS로" 페이징 모델을, Harness APIs는 Letta의 모델 호출 가능 메모리 블록과 Memory-R1의 RL 학습형 메모리 관리를 참조한다. NOOA의 차별점은 이들을 새 DSL이 아니라 객체지향 파이썬 런타임으로 실현한 데 있다.

NOOA는 모델이 작성한 코드를 에이전트 자신의 프로세스에서 실행한다. 검증기는 에이전트 루프를 보호하는 것이지 호스트를 보호하는 것이 아니다. 이 격리 철학은 셸 도구를 가진 여느 하니스와 같다 — 샌드박싱(컨테이너·VM·권한 시스템)은 에이전트 프로세스를 감싸는 것이고, 셸 도구는 인프로세스 파이썬보다 안전하지 않다. 인프로세스 실행이 참조 전달을 보존하는 대가다 — 샌드박스형 코드 모드는 그것을 포기하고 경계에서 직렬화된 사본을 받는다. 선호 배포는 OpenShell이다.