BuilderIO agent-native 시작하기: CLI 템플릿 프로젝트 생성과 defineAction 작성법 - Palette Path

BuilderIO의 Agent-Native는 자율 작업(Autonomous work)과 전용 UI를 결합할 수 있도록 설계된 오픈소스 TypeScript 프레임워크입니다. 애플리케이션의 핵심 기능을 액션(Action)이라는 단일 단위로 정의하면, LLM 에이전트는 이를 도구(Tool)로 주입받아 사용하고, UI는 프론트엔드 코드에서 동일한 로직을 직접 함수 형태로 호출할 수 있습니다. 공식 CLI 명령어를 사용해 독립 실행형(standalone) chat 템플릿 프로젝트를 생성하고, 공유 액션의 기본 구조인 defineAction을 구현하는 표준 개발 절차를 단계별로 살펴보겠습니다.

Agent-Native 프레임워크와 공유 액션 레이어의 핵심 개념

AI 에이전트와 UI 컴포넌트가 공유 액션 레이어를 통해 상호작용하는 아키텍처 개념도 — UI와 LLM 에이전트가 동일한 액션 레이어와 애플리케이션 상태를 공유하는 구조

Agent-Native 아키텍처의 중심에는 에이전트와 사용자 인터페이스가 동일한 계층을 통해 시스템과 소통한다는 철학이 있습니다. 지식 노동(Knowledge work)을 수행하는 에이전트에게는 문맥, 도구, 파일, 테스트, 미리보기를 가시화할 수 있는 작업 환경이 필요하며, 사용자는 전용 UI를 통해 에이전트가 수행 가능한 기능을 확인하고 작업 결과를 검토, 편집, 승인할 수 있어야 합니다. Agent-Native는 이를 세 가지 핵심 공유 요소로 구현합니다.

공유 액션(Shared actions): 애플리케이션의 각 기능을 액션으로 한 번 정의합니다. 에이전트는 이 액션을 도구(tool) 형태로 호출하고, UI는 TypeScript 코드에서 직접 함수로 호출합니다. 두 호출 경로는 동일한 입력 유효성 검증(Validation), 접근 권한 제어(Permissions), 실제 비즈니스 구현 코드를 그대로 공유합니다.
공유 데이터(Shared data): 에이전트가 수행한 작업 결과는 UI에 즉각적으로 나타나며, 사용자가 UI 화면을 통해 변경하거나 입력한 데이터 역시 에이전트가 곧바로 확인하고 활용할 수 있습니다.
공유 애플리케이션 상태(Shared application state): 현재 사용자가 머물고 있는 페이지, 선택된 레코드(Selected record), 활성화된 화면 뷰(Active view)와 같은 UI 상태가 에이전트에게 관련 문맥으로 실시간 전달됩니다.

여기서 중요한 설계적 특징은 에이전트가 브라우저 화면의 DOM 요소를 직접 클릭하거나 스크롤하는 방식으로 UI를 탐색하지 않는다는 점입니다. 에이전트는 사용자와 완전히 동일한 ‘액션 레이어(Action layer)’를 경유해 시스템과 상호작용합니다. 따라서 화면 UI의 배치나 스타일이 바뀌더라도 액션 레이어의 스키마와 설명이 유지되는 한 에이전트의 도구 실행 안정성이 지속적으로 보장됩니다.

공식 CLI로 standalone chat 템플릿 프로젝트 생성하기

Agent-Native 애플리케이션 구축을 시작하는 가장 공식적이고 표준적인 방법은 공식 CLI 명령어를 실행하여 독립형 chat 템플릿 환경을 생성하는 것입니다.

npx --yes @agent-native/core@latest create my-agent --standalone --template chat

프로젝트 초기화 및 첫 구동 준비는 다음 순서로 진행할 수 있습니다.

터미널 콘솔을 열고 프로젝트를 생성할 작업 디렉터리로 이동합니다.
위의 npx 명령어를 실행하여 --standalone 플래그와 --template chat 옵션을 적용한 my-agent 프로젝트 생성을 진행합니다.
프로젝트 내부의 설정을 점검하고 후속 개발을 진행합니다.

명령어 실행 후 오류가 발생하거나 프로젝트 생성이 비정상적으로 종료되는 경우, 로컬 터미널의 에러 로그와 네트워크 연결 상태를 확인하고 공식 GitHub 저장소의 안내 문서를 점검해야 합니다.

defineAction을 활용한 공용 액션 기본 구조와 작성법

defineAction과 Zod 스키마 코드가 표시된 모니터와 개발자 작업 공간 — Zod 스키마와 defineAction 함수를 기반으로 구현하는 단일 액션 구조

Agent-Native 프로젝트에서 비즈니스 로직을 개발하는 핵심 작업은 액션 파일을 정의하는 것입니다. 액션은 @agent-native/core/action 패키지에서 제공하는 defineAction 헬퍼 함수를 통해 작성하며, 입력 파라미터의 타입 정의와 런타임 유효성 검증에는 널리 쓰이는 Zod 라이브러리를 활용합니다.

다음은 이름을 입력받아 친근한 인사말 메시지를 반환하는 공식 기본 액션 파일인 actions/hello.ts의 전체 소스 코드입니다.

import { defineAction } from "@agent-native/core/action";
import { z } from "zod";

// One action powers every app surface: UI, agent, HTTP, MCP, A2A, and CLI.
export default defineAction({
  description: "Return a friendly greeting.",
  schema: z.object({
    name: z.string().default("world").describe("Name to greet"),
  }),
  http: { method: "GET" },
  run: async ({ name }) => {
    return { message: `Hello, ${name}!` };
  },
});

defineAction 내부 객체에 선언된 네 가지 핵심 속성은 각각 다음과 같은 역할을 수행합니다.

description (설명문): 액션이 수행하는 목적을 자연어로 기술합니다. 이 문자열은 단순한 소스코드 주석이 아니라, LLM 에이전트가 대화 문맥 속에서 어떤 도구를 호출해야 할지 판단하는 결정적인 근거 메타데이터로 사용됩니다. 따라서 명확하고 구체적인 문장으로 서술해야 합니다.
schema (입력 스키마): Zod 객체(z.object)를 통해 액션이 수신할 파라미터의 데이터 타입과 규칙을 정의합니다. 위 예제에서는 name 필드를 문자열로 정의하고 기본값을 "world"로 설정했으며, .describe("Name to greet")를 통해 에이전트가 인자값을 생성할 때 참조할 파라미터 설명을 추가했습니다. 이 스키마는 UI 호출과 에이전트 도구 호출 양쪽 모두에서 런타임 유효성 검증기로 동작합니다.
http (HTTP 엔드포인트 설정): 외부 시스템이나 브라우저에서 직접 접근할 수 있도록 HTTP 메서드(예: GET)를 매핑합니다.
run (실행 핸들러): 스키마를 통해 안전하게 검증된 입력 인자를 전달받아 실제 로직을 수행하는 비동기 함수입니다. 로직 처리 후 반환된 객체(예: { message: `Hello, ${name}!` })는 호출 주체에게 그대로 전달됩니다.

이렇게 정의된 단일 액션은 애플리케이션 내의 UI뿐만 아니라 에이전트 도구, HTTP, MCP(Model Context Protocol), A2A(Agent-to-Agent), CLI 콘솔 인터페이스까지 모든 인터페이스 표면(App surface)에 동일한 로직으로 노출되어 일관성을 유지합니다.

React UI 호출과 에이전트 도구 연동 방식 및 실행 환경 점검

정의된 공용 액션은 클라이언트 측 UI 코드와 LLM 에이전트 런타임에서 각자의 목적에 맞게 자연스럽게 사용됩니다. 프론트엔드 React 컴포넌트에서는 전용 데이터 조회 훅인 useActionQuery를 통해 액션을 호출합니다.

// React UI 컴포넌트 내에서의 액션 호출 예시
const { data } = useActionQuery("hello", { name: "Alex" });

// data 객체는 { message: "Hello, Alex!" } 구조로 반환될 것으로 예상됩니다.

React 컴포넌트는 위와 같이 액션 식별자 문자열("hello")과 스키마에 정의된 인자 객체({ name: "Alex" })를 전달하여 실행 결과를 비동기 쿼리로 받아옵니다. 이때 프레임워크 내부에서 스키마 유효성 검증과 run 함수가 순차적으로 처리됩니다.

동시에 백엔드 런타임에서 대화 세션을 관리하는 LLM 에이전트는 동일한 hello 액션을 자신이 사용할 수 있는 도구(tool) 목록 중 하나로 인식합니다. 사용자가 대화창에서 질문을 던지면, 에이전트는 actions/hello.ts에 명시된 description과 파라미터 describe 정보를 참조하여 도구 실행을 결정하고 해당 액션을 트리거합니다. 결과적으로 UI 개발자가 별도의 에이전트 툴 래퍼 함수를 작성하지 않아도 동일한 비즈니스 로직이 실행됩니다.

Agent-Native의 데이터 지속성과 개발 환경은 다음과 같은 인프라 구성을 지원합니다.

로컬 개발 데이터베이스 (PGlite): 로컬 환경에서는 개발자가 복잡한 PostgreSQL 도커 컨테이너나 외부 데이터베이스를 별도로 설치할 필요 없이 PGlite를 사용하여 개발을 진행할 수 있습니다.
프로덕션 데이터베이스 및 배포: 상용 서비스 배포 환경에서는 PostgreSQL 백엔드를 사용할 수 있으며, 모든 Nitro 호환 호스트 환경을 지원합니다.
LLM 연동 필수 요건: UI 렌더링 확인용 호출을 넘어 실제 대화(Agent chat) 및 자율 작업을 정상적으로 실행하려면 환경 변수 및 설정에 LLM API 연결이 올바르게 구성되어 있어야 합니다.

만약 컴포넌트 실행 시 액션 호출이 실패하거나 빈 결과가 반환된다면, 액션 파일이 올바르게 위치해 있는지, Zod 스키마에서 정의한 필수 필드 타입과 호출 시 전달한 인자 객체의 키 이름이 일치하는지 개발자 도구의 콘솔 및 터미널 로그를 통해 점검해야 합니다.