에이전트에게 화면 대신 액션을 준다는 것

내 앱을 에이전트가 쓰게 만들려고 화면 자동화를 붙이고 있다면, 계층을 잘못 고른 것이다. 남의 앱이면 화면밖에 없지만 내 코드면 액션 계층을 열면 된다.

Agent-Native의 README가 그 선택을 한 문장으로 적는다.

The agent does not click through the UI. It works through the same action layer as the UI.

이틀 전에 쓴 ARTEMIS가 정확히 반대편이다. 거긴 접근성 트리와 OCR로 화면을 읽어 누른다. 두 접근은 경쟁 관계가 아니라 소유권으로 갈린다.

출처: github.com/BuilderIO/agent-native

확인된 것

저장소·npm 레지스트리에서 직접 확인한 것만 적는다.

• 2026-03-12 생성, 마지막 푸시 2026-09-19. 별 4,862, 포크 462, 열린 이슈 78. TypeScript 모노레포이고 packages/ 아래 패키지 20개.
• 핵심 API는 defineAction 하나다. 설명·zod 스키마·run 구현을 한 곳에 쓰면, 같은 액션이 UI·에이전트 도구·HTTP·MCP·A2A·CLI에서 호출된다. React 쪽은 useActionQuery("hello", {...})로 같은 함수를 부른다.
• 두 경로가 공유하는 것을 README가 명시한다 — 같은 validation, 같은 permissions, 같은 implementation.
• 포함 기능: 에이전트 채팅, 인증·권한, 스킬·메모리, 스케줄/이벤트 자동화, 에이전트 팀(위임), PostgreSQL 백엔드(로컬은 PGlite), Nitro 호환 호스팅.
• npm 버전이 0.182.1이다. 같은 레지스트리에 게시된 버전이 1,530개, 첫 게시가 2026-03-12다. 6개월 동안이다. engines는 Node 22.22.0 이상.
• 저장소에 LICENSE 파일이 없다. 루트 파일 목록에도, packages/core에도 없고 GitHub 라이선스 API는 404를 반환한다. 반면 npm 패키지 메타데이터의 license 필드는 MIT로 선언돼 있다.

판단

1. 화면이냐 액션이냐는 성능 문제가 아니라 소유권 문제다

에이전트에게 앱을 시키는 방법은 둘이다. 화면을 읽고 누르게 하거나, 기능을 직접 부르게 하거나.

화면 자동화는 내가 못 고치는 앱을 위한 것이다. 남의 SaaS, 레거시 내부 시스템, API가 없는 도구. 거기선 접근성 트리와 OCR이 유일한 표면이고, 느리고 깨지기 쉬운 걸 감수하는 게 합리적이다.

그런데 내가 만드는 앱에 같은 방식을 쓰면, 있는 함수를 놔두고 그 함수를 호출하는 버튼을 찾아 누르게 하는 것이 된다. 렌더링·좌표·타이밍이라는 실패 지점을 스스로 만들어 넣는 셈이다.

→ 판단 기준은 하나다. 그 코드가 내 것인가. 내 것이면 액션 계층, 남의 것이면 화면. 이 프레임워크를 쓸지 말지와 별개로 이 구분은 지금 적용할 수 있다.

2. 진짜 이득은 중복 제거가 아니라 권한이 한 곳에 있다는 것

"한 번 정의하면 여섯 군데서 쓴다"는 문장은 DRY 얘기처럼 읽히고, 그러면 있어도 그만 없어도 그만인 편의로 들린다. 내가 보기에 중요한 건 다른 쪽이다.

인터페이스마다 구현이 갈리면 검증과 권한도 갈린다. 그리고 갈린 채로 오래 두면 UI에서는 막히는데 도구 경로로는 통과하는 조합이 반드시 생긴다. 사람만 쓰던 시절에는 그게 잠복해 있다가, 에이전트를 붙이는 순간 권한 상승 경로가 된다. 에이전트는 사람이 안 눌러본 조합을 눌러보는 존재다.

→ 프레임워크를 도입하지 않아도 오늘 쓸 수 있는 규칙: 에이전트 도구 핸들러에서 DB를 직접 건드리지 마라. 사람이 쓰는 경로와 같은 함수를 부르게 하고, 권한 검사는 그 함수 안에 둬라. 이 프레임워크가 파는 것의 핵심도 결국 그거다.

3. 0.182.1과 릴리스 1,530개를 같이 읽어야 한다

활발하다는 증거인 동시에 API가 아직 굳지 않았다는 증거다. 6개월에 182번째 마이너 버전이면, 굳은 인터페이스를 쓰는 게 아니라 움직이는 인터페이스를 따라가는 쪽에 가깝다.

주말 프로젝트나 내부 도구라면 문제될 게 없다. 깨지면 고치면 된다. 하지만 고객에게 파는 제품의 기반으로 삼는다면 업그레이드 비용을 상수가 아니라 변수로 잡아야 한다.

Litelm에 대해 쓰면서 세운 기준이 여기도 적용된다 — "내가 포크해서 유지할 수 있는 크기인가." 거기선 2,900줄이라 답이 '예'였다. 여긴 패키지 20개짜리 모노레포다. 답은 '아니오'에 가깝고, 그러면 업스트림의 속도가 곧 내 일정이 된다.

4. 라이선스 파일이 없다 — 포크할 생각이면 확인하고 시작해라

이건 사실 관계만 적는다. npm 메타데이터는 MIT라고 선언하고, 한국어 요약이 "MIT 라이선스"라고 쓴 근거도 그것으로 보인다. 그런데 저장소 루트에도 packages/core에도 LICENSE 파일이 없고, GitHub의 라이선스 엔드포인트는 404다.

의도가 MIT인 건 분명해 보인다. 그리고 이건 빠르게 움직이는 초기 프로젝트에서 흔한 누락이고, 이슈 하나면 정리될 일이다.

다만 포크하거나 코드를 벤더링할 계획이라면 확인하고 넘어갈 항목이다. 라이선스 텍스트가 없는 저장소의 기본값은 "권리 유보"이고, package.json의 한 줄이 그 자리를 대신한다고 단정할 수는 없다. 내가 말할 수 있는 건 지금 저장소 상태가 그렇다는 것까지다.

모르는 것

• 직접 설치해 돌려보지 않았다. 위 판단은 저장소와 레지스트리 메타데이터 독해에서 나온 것이다.
• 인증 없는 GitHub 코드 검색이 막혀 저장소 전체를 훑지 못했다. 루트와 packages/core만 확인했으므로, 다른 경로에 라이선스 텍스트가 있을 가능성은 남아 있다.
• 액션 계층을 거치는 데 따른 오버헤드 수치가 없다. HTTP·MCP·CLI로 같은 액션을 노출할 때의 비용 차이도 모른다.
• 프로덕션 사용 사례를 확인하지 못했다. 별 4,862개는 관심 지표이지 채택 지표가 아니다.
• 에이전트 팀·자동화 같은 기능이 실제로 어느 정도 완성도인지 모른다. 기능 목록만 읽었다.