Agent-Native는 어떻게 사용하나요? TypeScript AI Agent 프레임워크 설치 및 개발 튜토리얼

UI에는 업무 기능이 있지만 Agent가 같은 기능을 안전하게 실행할 방법이 없어 연결 지점부터 막히기 쉽습니다.
이 경우 Agent-Native가 적합합니다. 공식 CLI로 최소 프로젝트를 만든 뒤 공유 action의 입력 검증과 권한, UI와 Agent의 상태 일치를 확인하고 데이터베이스와 배포 환경이 맞을 때 기능을 넓히는 편이 안전합니다.

이 글은 TypeScript로 Agent 앱을 만드는 개발자가 첫 프로젝트와 공유 action을 구현할 때 참고할 수 있습니다.
제품 UI와 Agent가 같은 데이터와 권한 경계를 사용해야 하는 팀에도 맞습니다.
원격 환경에서 개발하거나 실행하려는 담당자는 데이터베이스와 지속 실행 요구를 기준으로 환경을 검토할 수 있습니다.

마지막 검토: 2026년 9월 25일. 명령과 지원 범위는 공식 저장소, Quickstart와 문서 및 배포 안내를 기준으로 확인해야 합니다. CLI와 API는 바뀔 수 있으므로 실제 작업 시 현재 문서의 명령을 다시 확인하세요.

Agent-Native가 맞는 앱인지 먼저 판별합니다

Agent-Native는 채팅 창을 기존 화면에 얹는 용도의 UI 부품이라기보다, 애플리케이션의 action과 데이터, 상태를 UI와 Agent가 함께 다루도록 설계된 TypeScript AI Agent 프레임워크입니다. 공식 개념 설명은 이 공유 구조를 중심으로 설명합니다. 즉, 화면에서 수행하던 업무 동작을 Agent에도 노출하되, 해당 동작을 누가 어떤 입력으로 실행할 수 있는지는 애플리케이션이 설계해야 합니다. 공식 핵심 개념 설명

업무 항목을 사용자가 화면에서 수정하고 Agent가 같은 항목을 조회하거나 갱신해야 하는 제품이라면 검토할 가치가 있습니다. 반대로 기존 앱에 간단한 질의 응답 창만 추가하려는 경우, 자체 애플리케이션 구조나 데이터 흐름을 마련하고 싶지 않은 경우에는 프레임워크 도입이 불필요한 부담이 될 수 있습니다.

선택지	적합한 경우	도입 전 확인할 점
Agent-Native로 새 프로젝트 시작	UI와 Agent가 업무 action 및 애플리케이션 상태를 함께 사용해야 할 때	공식 Quickstart의 템플릿과 현재 CLI 절차가 팀의 기술 구성에 맞는지 확인합니다.
기존 앱에 Agent 기능 연결	화면과 데이터 구조가 이미 있고, 공통 업무 로직을 분리할 수 있을 때	기존 인증, 데이터 접근, 오류 처리 방식과 프레임워크 연결부의 경계를 확인합니다.
별도 채팅 UI만 추가	Agent가 애플리케이션 내부 상태를 변경하지 않아도 될 때	공유 action이 필요하지 않다면 프레임워크가 제공하는 구조가 과도하지 않은지 비교합니다.

Agent-Native 설치 안내를 찾는 팀도 첫 선택은 설치 명령 자체가 아니라 앱 형태입니다. 사용자가 승인하거나 수정해야 하는 업무 동작이 있고, Agent도 이를 수행해야 한다면 다음 단계로 진행하세요. 단순한 대화형 안내만 필요하다면 현재 제품 구조에 최소한의 연동을 추가하는 편이 더 단순할 수 있습니다.

프로젝트를 만들기 전에 도구와 템플릿을 맞춥니다

Quickstart를 따라 새 프로젝트를 시작하되, Node와 패키지 관리 도구의 최소 버전을 임의로 정하지 마세요. 문서에 표시된 현재 요구 사항을 확인하고, 선택한 템플릿이 설치 명령 및 실행 절차와 일치하는지 점검합니다. 공식 문서에 명시되지 않은 버전 번호를 팀의 기본값처럼 복사하면 설치 오류를 재현하기 어려워집니다.

진행 방식	실행 전 확인	적합한 선택
공식 CLI로 새 앱 생성	Quickstart에 나온 CLI 명령, 템플릿, 패키지 설치 절차를 현재 문서에서 확인합니다.	프레임워크 기본 구조를 익히고 작은 검증 앱을 만들 때
기존 저장소에 통합	현재 저장소의 패키지 관리자, 서버 실행 방식, 인증과 데이터 계층을 확인합니다.	기존 제품의 업무 로직을 재사용할 때
원격 개발 환경에서 생성	프로젝트 파일 저장 위치, 런타임, 포트 접근, 프로세스 유지 조건을 확인합니다.	로컬 장비를 바꾸거나 팀이 같은 개발 환경을 공유해야 할 때

작업 순서는 간단하게 유지합니다.

• [ ] 공식 Quickstart에서 CLI 설치와 프로젝트 생성 명령을 확인합니다.
• [ ] 문서에 적힌 Node 및 패키지 관리자 요구 사항을 설치 환경과 대조합니다.
• [ ] 문서의 템플릿 이름과 생성 결과의 디렉터리 구성이 맞는지 확인합니다.
• [ ] 의존성 설치가 끝난 뒤 공식 실행 명령으로 기본 화면과 서버가 열리는지 확인합니다.
• [ ] 생성된 예제에서 프레임워크 API와 애플리케이션 코드를 구분해 기록합니다.

주의: 현재 문서에서 확인하지 않은 CLI 옵션이나 패키지 버전을 블로그 예제에 고정하지 마세요. 명령이 바뀌면 복사한 설치 절차가 실패할 수 있으므로, 실행 시점의 Quickstart를 기준으로 삼아야 합니다.

공유 action을 만들고 UI와 Agent의 호출 경로를 연결합니다

공유 actions는 UI 버튼과 Agent 도구가 각자 다른 업무 규칙을 갖게 하지 않고, 하나의 애플리케이션 동작을 함께 호출하도록 구성하는 방식입니다. 공식 action 정의 문서의 등록 방식과 인자 형식에 맞추되, 핵심 업무 함수와 프레임워크 연결 코드를 분리하면 테스트 경계가 분명해집니다.

예를 들어 업무 항목의 상태를 변경하는 기능을 만든다고 가정합니다. 다음 코드는 TypeScript로 업무 로직을 분리하는 구조를 보여 주는 개념 예시이며, Agent-Native의 등록 API 문법을 대신하지 않습니다.

type ChangeInput = {
  itemId: string;
  nextState: "open" | "done";
};

async function changeItem(input: ChangeInput, actorId: string) {
  if (!input.itemId || !["open", "done"].includes(input.nextState)) {
    throw new Error("Invalid input");
  }

  const item = await loadItem(input.itemId);
  await assertCanEdit(actorId, item);
  return saveItemState(item.id, input.nextState);
}

실제 프로젝트에서는 loadItem, assertCanEdit, saveItemState를 애플리케이션의 저장소와 권한 체계에 연결합니다. 그런 다음 프레임워크의 공식 action 정의 절차에 따라 이 동작을 Agent가 호출할 수 있도록 등록하고, UI 이벤트도 같은 업무 로직을 호출하도록 연결합니다. UI에서 별도의 상태 변경 코드를 복제하면 규칙이 갈라질 수 있습니다.

입력 스키마 검증은 호출자가 UI인지 Agent인지에 상관없이 수행해야 합니다. 권한도 action이 실행되는 시점에 실제 사용자나 서비스 주체를 기준으로 검사해야 합니다. 공유 action이라고 해서 Agent에 UI와 같은 권한이 자동으로 부여되거나, 권한 검사가 자동 완성되는 것은 아닙니다. 공식 접근 제어 안내를 확인하고 인증 주체를 action 실행 경로까지 전달하는 방법을 맞추세요.

같은 상태와 권한을 검증한 뒤 데이터 연결을 확장합니다

공식 개념 설명에서 공유 대상으로 다루는 범위는 actions, 데이터, 애플리케이션 상태의 세 축입니다. 이를 구현 확인 항목으로 바꾸면 UI와 Agent가 같은 action을 호출하는지, 같은 업무 객체를 읽는지, 변경 결과가 양쪽에 반영되는지 확인해야 합니다. 이 공유 설계는 개별 앱의 인증이나 데이터 격리를 보장한다는 뜻은 아닙니다.

검증은 성공 사례 한 번으로 끝내지 말고 다음 순서로 진행합니다.

• UI에서 테스트 업무 항목을 수정하고 저장된 값이 화면에 표시되는지 확인합니다.
• Agent에 같은 항목의 현재 상태를 질의해 저장 데이터와 일치하는지 대조합니다.
• Agent가 공식 action 경로를 통해 상태를 변경하도록 하고, UI 새로고침이나 동기화 뒤 결과가 일치하는지 봅니다.
• 권한이 없는 주체와 잘못된 입력을 각각 시도해 거부되는지 확인합니다.
• 저장소 오류나 권한 거부가 발생했을 때 UI와 대화 흐름에 원인을 구분할 수 있는 실패 응답이 나타나는지 점검합니다.

검증 영역	확인할 동작	통과 기준
입력 검증	필수 식별자 누락, 허용되지 않은 상태값	저장 전에 요청이 거부되고 원인을 확인할 수 있습니다.
권한	읽기만 가능한 주체의 변경 시도	서버 측 권한 검사에서 차단되며 데이터가 바뀌지 않습니다.
공유 상태	UI 변경 후 Agent 조회, Agent 변경 후 UI 확인	양쪽에서 같은 저장 결과를 읽습니다.
실패 처리	저장소 오류, 접근 거부	오류가 성공으로 표시되지 않고 후속 동작이 분명합니다.

데이터베이스가 프레임워크 상태와 어떤 관계를 갖는지도 확인해야 합니다. 공식 서버 데이터베이스 안내에서 데이터 저장과 동기화 구조를 검토하고, 애플리케이션 데이터가 영속 저장되는 위치와 프레임워크가 관리하는 상태를 구분하세요. 특정 모델 공급자나 외부 도구가 지원된다고 단정하지 말고, 공식 문서에 명시된 연결 절차가 있는지 확인한 뒤 별도 시험 환경에서 검증합니다.

배포 전에는 호스트와 지속성 조건을 대조합니다

개발 서버가 실행된다는 사실만으로 배포 적합성을 판단할 수 없습니다. 공식 배포 안내에서 지원하는 실행 방식과 필요한 데이터베이스 조건을 살피고, 환경 변수 문서에 나온 항목을 실제 배포 구성과 대조하세요. 단일 앱 배포 절차는 공식 안내를 기준으로 확인할 수 있으며, 배포 범위와 데이터베이스 요구 사항은 배포 문서에서 다시 검토해야 합니다.

• [ ] 공식 문서의 호스트 요구 사항이 선택한 실행 환경과 일치합니다.
• [ ] 환경 변수는 개발용 값과 분리되어 있으며 비밀 값이 코드에 들어 있지 않습니다.
• [ ] 데이터베이스 연결, 데이터 지속성, 백업 및 복구 책임이 정해져 있습니다.
• [ ] 로그에서 action 실행 결과와 거부 사유를 구분할 수 있습니다.
• [ ] 로컬에서 확인한 권한 및 상태 시나리오를 시험 배포 환경에서도 다시 실행합니다.
• [ ] 시험 배포에서 중단 후 재시작, 설정 변경, 로그 확인 절차를 담당자가 수행할 수 있습니다.

배포 단계에서는 프레임워크가 지원하는 범위와 운영팀이 책임질 범위를 나누세요. 실행 호스트가 문서에 나온다고 해서 모든 데이터베이스 구성이나 지속 실행 방식이 자동으로 적합해지는 것은 아닙니다.

공식 저장소의 개발 안내도 프로젝트 생성 이후 함께 확인하면 저장소의 개발 절차와 문서가 가리키는 실행 방법을 비교하는 데 도움이 됩니다. 이 글에는 Zutcloud 원격 환경에서의 프로젝트 시작 기록이나 성능 실측값을 포함하지 않았습니다. 해당 값이 제공되지 않았으므로 특정 설정에서의 실행 성공률이나 비용을 추정하지 않습니다.

로컬 개발은 장비에 직접 접근하기 쉽지만 개발 환경이 개인별로 달라지고, 장시간 실행 프로세스를 유지하기 어렵거나 프로젝트 의존성을 팀에서 맞추기 번거로울 수 있습니다. 반면 공유 클라우드 환경도 데이터베이스 연결, 비밀 값 관리, 지속 실행 여부를 확인하지 않으면 배포 전 검증을 대신하지 못합니다. TypeScript 프로젝트를 원격에서 개발해야 한다면 한국용 맥 미니 대여 환경을 현재 저장소의 의존성, 데이터베이스, 실행 유지 요구와 대조해 보세요. 원격 개발 환경과 장비 조건을 먼저 확인하려는 팀은 도움말 안내에서 이용 전 확인 사항을 살펴볼 수 있습니다. 맥이 필요한 빌드나 테스트가 일시적이라면 Zutcloud의 맥 환경을 임대해 시험하는 선택이 장비 구매보다 부담을 줄일 수 있지만, 장기간 지속되는 무거운 작업이나 물리 인터페이스가 필요한 업무라면 자체 장비가 더 적합할 수 있습니다.

더 읽기

• 도구 호출과 실행 경계를 안전하게 설계하는 방법
• 에이전트 작업 공간과 파일 접근 권한을 설계하는 방법
• 요구 사항부터 검증까지 잇는 에이전트 개발 흐름