세상은 멈춰 있지 않습니다.RSS
BIG CHANGE.

Markdown 버전

AI-translated from English; not yet reviewed by a fluent editor.

# 채팅과 React 페이지에서 같은 Agent-Native action 확인하기

> Chat 템플릿의 hello action을 에이전트 채팅과 React 라우트에서 호출하고 반환값 하나를 바꾼 뒤, 도구 호출 증거와 함께 문서상 결과를 비교합니다.

By BIG CHANGE Editorial

Published: 2026-10-19T10:08:15.758Z
Updated: 2026-10-19T10:08:15.758Z
Canonical: https://bigchange.ai/blog/agent-native-chat-react-action-parity-guide

![Conceptual charcoal illustration of one laptop showing two blank side-by-side work areas: conversation shapes on the left and a plain input and output area on the right.](https://bigchange.ai/api/media/file/agent-native-chat-react-comparison-hero-v1.png)
AI-generated conceptual illustration by BIG CHANGE; no actual product interface, action invocation or test result is depicted.

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

## 핵심 변화

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

## 문서의 Chat 템플릿 설정

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

1. 새 디렉터리에서 독립형 Chat 앱을 만들고 시작하세요.

```bash
   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` 가 포함됩니다.

2. 연결하려면 **Custom keys**에 OpenAI API 키를 넣어 채팅 에이전트를 연결한 뒤 Settings에서 사용 가능한 모델을 선택하세요. [환경 변수 가이드](https://www.agent-native.com/docs/environment-variables/)에 따르면 Custom keys는 범위가 지정된 자격 증명을 앱의 암호화된 데이터베이스 기반 저장소에 보관합니다. 키를 소스 관리에 넣거나 브라우저에 공개되는 `VITE_` 변수에 넣지 마세요. 모델 요청은 키 소유자의 공급자 계정을 사용합니다. 민감한 자료를 보내기 전에 현재 요금과 [데이터 제어](https://developers.openai.com/api/docs/guides/your-data)를 확인하세요. 이 가이드에서는 작업별 비용이나 보관 동작을 측정하지 않았습니다.
3. Get started 채팅에서 `Call the hello action for Alex.` 라고 요청하세요. [시작 가이드](https://www.agent-native.com/docs/)의 예상 응답은 `Hello, Alex!` 입니다. 도구 세부 정보가 표시되면 `hello` 를 `name: "Alex"` 로 호출하고 해당 메시지를 반환했는지 확인하세요. 호출 증거 없이 문장만 일치하면 확정할 수 없습니다.
4. 파일 `actions/hello.ts` 를 살펴보세요. [리비전이 고정된 Chat 템플릿](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts)은 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!` 입니다.

5. 기존 `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 시작 가이드](https://www.agent-native.com/docs/)는 생성 명령, 에이전트 프롬프트, React hook, 예상 응답과 복구 절차를 설명합니다. action 발췌문에는 고정 템플릿의 속성 하나가 빠져 있으므로 생성된 action을 제자리에서 수정하세요.
- [고정 리비전의 Chat `hello` action](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts)은 `mcpTool: true` 를 비롯한 소스 속성을 commit `8e8419361fb415682cdf0e0e68538671dbb6aed3` 에서 확인해 줍니다. 이 스냅샷은 나중의 생성 과정이 무엇을 설치할지 증명하지 않습니다.
- [환경 변수](https://www.agent-native.com/docs/environment-variables/)는 키 범위, 모델 선택, `VITE_` 의 공개 경계를 설명합니다. 공급자 약관은 별도로 확인하세요. 이 가이드는 실제 채팅 요청을 조사하지 않았습니다.

## Sources

- [Agent-Native 시작 가이드](https://www.agent-native.com/docs/) — [Agent-Native 시작 가이드](https://www.agent-native.com/docs/) 는 생성 명령, 에이전트 프롬프트, React hook, 예상 응답과 복구 절차를 설명합니다. action 발췌문에는 고정 템플릿의 속성 하나가 빠져 있으므로 생성된 action을 제자리에서 수정하세요.
- [고정 리비전의 Chat hello action](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts) — [고정 리비전의 Chat `hello` action](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts) 은 commit `8e8419361fb415682cdf0e0e68538671dbb6aed3`에서 `mcpTool: true`를 비롯한 소스 속성을 확인해 줍니다. 이 스냅샷은 나중의 생성 과정이 무엇을 설치할지 증명하지 않습니다.
- [고정 리비전의 core 패키지](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/packages/core/package.json) — 패키지 버전, Node 요구 사항 및 라이선스.
- [Agent-Native 환경 변수](https://www.agent-native.com/docs/environment-variables/) — [환경 변수](https://www.agent-native.com/docs/environment-variables/) 는 키 범위, 모델 선택, `VITE_`의 공개 경계를 설명합니다. 공급자 약관은 별도로 확인하세요. 이 가이드는 실제 채팅 요청을 조사하지 않았습니다.
- [OpenAI API 데이터 제어](https://developers.openai.com/api/docs/guides/your-data) — 공급자의 데이터 처리 참고 자료이며, 이 작업의 실제 트래픽은 관찰하지 않았습니다.