Agent-Native의 Chat 템플릿에는 에이전트가 호출할 수 있는 hello action이 있습니다. TypeScript 개발자는 같은 action을 호출하는 작은 React 라우트를 추가하고 반환값 하나를 바꾼 뒤 두 결과를 비교할 수 있습니다. 이 가이드는 Agent-Native의 문서 예제를 따릅니다. BIG CHANGE는 문서와 템플릿 소스를 확인했지만 앱을 실행하지 않았습니다.

핵심 변화

  • 달라지는 점: 하나의 action이 에이전트 도구와 React 쿼리에 같은 타입 지정 작업을 제공할 수 있습니다. 이 예제의 인사 코드는 한 파일에 있습니다.
  • 중요한 이유: 개발자는 코드를 바꾼 뒤 두 호출자가 같은 결과를 받는지 확인할 수 있습니다. 채팅과 페이지의 인사 로직을 따로 유지할 가능성을 줄이지만, 저장된 앱 상태를 공유한다는 증거는 아닙니다.
  • 확인할 점: 채팅 인터페이스가 실제 action 호출과 반환값을 보여 주면 이를 비교하세요. 모델이 그럴듯한 문장을 출력하는 것만으로 hello 호출을 입증할 수 없습니다. 중요한 작업에 이 패턴을 쓰기 전에 권한, 유효성 검사, 상태 쓰기를 각각 평가하세요.

문서의 Chat 템플릿 설정

Node.js 22.22 이상, pnpm , 코드 편집기, 채팅 호출용 OpenAI API 키가 필요합니다. 모델을 연결하기 전에도 UI를 설정할 수 있습니다. 확인한 core 패키지와 npm 레지스트리의 버전은 2026년 10월 18일 기준 0.209.2 였습니다. 공식 생성 명령은 변경되는 @latest 를 사용하므로 따라 하기 전에 버전을 다시 확인하세요.

  1. 새 디렉터리에서 독립형 Chat 앱을 만들고 시작하세요.
Terminal
   npx --yes @agent-native/core@latest create my-app --standalone --template chat
   cd my-app
   corepack enable
   pnpm install
   pnpm dev

명령 pnpm dev 가 출력한 로컬 URL을 열고 Continue as local dev를 선택하세요. 8080 포트가 사용 중이면 포트 번호가 증가할 수 있습니다. 생성된 앱에는 actions/hello.ts 가 포함됩니다.

  1. 연결하려면 Custom keys에 OpenAI API 키를 넣어 채팅 에이전트를 연결한 뒤 Settings에서 사용 가능한 모델을 선택하세요. 환경 변수 가이드에 따르면 Custom keys는 범위가 지정된 자격 증명을 앱의 암호화된 데이터베이스 기반 저장소에 보관합니다. 키를 소스 관리에 넣거나 브라우저에 공개되는 VITE_ 변수에 넣지 마세요. 모델 요청은 키 소유자의 공급자 계정을 사용합니다. 민감한 자료를 보내기 전에 현재 요금과 데이터 제어를 확인하세요. 이 가이드에서는 작업별 비용이나 보관 동작을 측정하지 않았습니다.
  2. Get started 채팅에서 Call the hello action for Alex. 라고 요청하세요. 시작 가이드의 예상 응답은 Hello, Alex! 입니다. 도구 세부 정보가 표시되면 hello 를 name: "Alex" 로 호출하고 해당 메시지를 반환했는지 확인하세요. 호출 증거 없이 문장만 일치하면 확정할 수 없습니다.
  3. 파일 actions/hello.ts 를 살펴보세요. 리비전이 고정된 Chat 템플릿은 Zod name 입력, GET action, mcpTool: true 를 정의합니다. 이 속성들은 유지하세요. 다음 작은 페이지로 app/routes/hello.tsx 를 만드세요.
TypeScript
   import { useActionQuery } from "@agent-native/core/client/hooks";
   import { useState } from "react";

   export default function HelloRoute() {
     const [name, setName] = useState("Alex");
     const { data } = useActionQuery("hello", { name });

     return (
       <main>
         <label htmlFor="greeting-name">Name</label>
         <input
           id="greeting-name"
           value={name}
           onChange={(event) => setName(event.target.value)}
         />
         <p>{data?.message}</p>
       </main>
     );
   }

새 라우트를 찾도록 pnpm dev 를 다시 시작하고, 출력된 로컬 URL 뒤에 /hello 를 붙여 여세요. 입력값이 Alex 이면 문서상 결과는 Hello, Alex! 입니다.

  1. 기존 run 함수가 있는 actions/hello.ts 에서 반환문만 바꾸세요.
TypeScript
   return { message: `Welcome, ${name}.` };

페이지 /hello 를 새로 고치고 채팅에도 Alex에 대해 hello 를 다시 호출하도록 요청하세요. 문서는 양쪽에서 Welcome, Alex. 가 나올 것으로 설명합니다. 페이지에 렌더링된 메시지와 채팅의 action 결과를 비교하고, 제공되면 도구 세부 정보도 확인하세요. 페이지는 입력을 React 상태에 보관하며, 이 인사 action은 공유 레코드를 읽거나 쓰지 않습니다.

확인 항목

반환문 수정 전

반환문 수정 후

/hello 에 입력한 값은 Alex

Hello, Alex!

Welcome, Alex.

채팅 action 결과, 입력은 name: "Alex"

Hello, Alex!

Welcome, Alex.

이 값들은 문서의 예상값입니다. 실험을 마쳤다고 판단하기 전에 실제 표시값과 확인 가능한 호출 세부 정보를 기록하세요.

명령 pnpm 이 없으면 생성된 앱에서 corepack enable 을 실행하세요. peer dependency 오류에는 공식 가이드가 재시도 전 npx clear-npx-cache 를 제안합니다. 채팅에 Connect AI가 나오면 action을 진단하기 전에 공급자 설정을 마치세요. /hello 가 없으면 라우트를 만든 뒤 개발 서버를 다시 시작하세요. 이는 문서에 있는 복구 단계이며, 우리가 관찰한 결과가 아닙니다.

출처 및 추가 자료

  • Agent-Native 시작 가이드는 생성 명령, 에이전트 프롬프트, React hook, 예상 응답과 복구 절차를 설명합니다. action 발췌문에는 고정 템플릿의 속성 하나가 빠져 있으므로 생성된 action을 제자리에서 수정하세요.
  • 고정 리비전의 Chat hello action은 mcpTool: true 를 비롯한 소스 속성을 commit 8e8419361fb415682cdf0e0e68538671dbb6aed3 에서 확인해 줍니다. 이 스냅샷은 나중의 생성 과정이 무엇을 설치할지 증명하지 않습니다.
  • 환경 변수는 키 범위, 모델 선택, VITE_ 의 공개 경계를 설명합니다. 공급자 약관은 별도로 확인하세요. 이 가이드는 실제 채팅 요청을 조사하지 않았습니다.