Edição Markdown

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

# Verifique uma ação do Agent-Native no chat e numa página React

> Invoque a ação hello do modelo Chat através do chat do agente e de uma rota React, altere um valor de retorno e compare os resultados documentados, verificando a prova da invocação da ferramenta.

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.

O modelo Chat do Agent-Native inclui uma ação `hello` que o agente pode invocar. Um programador TypeScript pode acrescentar uma pequena rota React que invoque a mesma ação, alterar um valor de retorno e comparar os dois resultados. Este guia segue o [exemplo documentado do Agent-Native](https://www.agent-native.com/docs/); o BIG CHANGE examinou a documentação e o código do modelo, mas não executou a aplicação.

## A grande mudança

- **O que muda:** uma ação pode fornecer a mesma operação tipada a uma ferramenta do agente e a uma consulta React. Neste exemplo, o código da saudação encontra-se num único ficheiro.
- **Porque importa:** o programador pode verificar se os dois invocadores recebem o mesmo resultado após uma alteração do código. Isso reduz a possibilidade de manter lógicas de saudação separadas para o chat e a página; não demonstra que partilhem o estado guardado da aplicação.
- **O que verificar:** compare a invocação real da ação e o valor devolvido quando a interface do chat os apresentar. Uma frase plausível do modelo, por si só, não prova que invocou `hello`. Antes de aplicar este padrão a operações importantes, avalie separadamente autorização, validação e escritas de estado.

## Configure o modelo Chat documentado

Precisa de Node.js 22.22 ou posterior, `pnpm`, um editor de código e uma chave OpenAI API para a invocação no chat. Pode configurar a interface antes de ligar um modelo. O [pacote core examinado](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/packages/core/package.json) e o registo npm indicavam a versão `0.209.2` em 18 de outubro de 2026. O comando oficial de criação usa o variável `@latest`; confirme novamente a versão antes de seguir o guia.

1. Num diretório novo, crie e inicie uma aplicação Chat autónoma:

```bash
   npx --yes @agent-native/core@latest create my-app --standalone --template chat
   cd my-app
   corepack enable
   pnpm install
   pnpm dev
```

   Abra o URL local apresentado por `pnpm dev` e escolha **Continue as local dev**. O número da porta pode aumentar se a 8080 estiver ocupada. A aplicação gerada inclui `actions/hello.ts`.

2. Ligue o agente com **Custom keys** e a sua chave OpenAI API; depois selecione um modelo disponível em Settings. O [guia de variáveis de ambiente](https://www.agent-native.com/docs/environment-variables/) indica que Custom keys guarda credenciais com âmbito delimitado no armazenamento cifrado da aplicação, assente numa base de dados. Não coloque chaves no controlo de versões nem em variáveis `VITE_` expostas ao navegador. Os pedidos usam a conta do fornecedor do titular da chave; consulte os preços atuais e os [controlos de dados](https://developers.openai.com/api/docs/guides/your-data) antes de enviar material sensível. Não foram medidos o custo por tarefa nem o comportamento de retenção.
3. No chat Get started, peça: `Call the hello action for Alex.` O [guia inicial](https://www.agent-native.com/docs/) apresenta `Hello, Alex!` como resposta esperada. Se a interface mostrar detalhes das ferramentas, confirme a invocação de `hello` com `name: "Alex"` e a devolução dessa mensagem. Uma frase coincidente sem prova da invocação é inconclusiva.
4. Examine `actions/hello.ts`. O [modelo Chat fixado nesta revisão](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts) define uma entrada Zod `name`, uma ação GET e `mcpTool: true`. Preserve essas propriedades. Crie `app/routes/hello.tsx` com esta pequena página:

```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>
     );
   }
```

   Reinicie `pnpm dev` para detetar a rota e acrescente `/hello` ao URL local apresentado. Com `Alex` no campo, o resultado documentado é `Hello, Alex!`.

5. Na função `run` existente de `actions/hello.ts`, substitua apenas a instrução de retorno:

```typescript
   return { message: `Welcome, ${name}.` };
```

   Atualize `/hello` e peça ao chat que volte a invocar `hello` para Alex. A expectativa documentada é `Welcome, Alex.` em ambos os locais. Compare a mensagem da página com o resultado da ação no chat, incluindo os detalhes da ferramenta quando disponíveis. A página mantém a entrada no estado React; esta ação de saudação não lê nem escreve um registo partilhado.

| Verificação | Antes de editar o retorno | Depois de editar o retorno |
| --- | --- | --- |
| `/hello` com `Alex` | `Hello, Alex!` | `Welcome, Alex.` |
| Resultado da ação no chat para `name: "Alex"` | `Hello, Alex!` | `Welcome, Alex.` |

Estes são os valores esperados na documentação. Registe os valores que vê e os detalhes de invocação disponíveis antes de considerar a experiência concluída.

Se faltar `pnpm`, execute `corepack enable` na aplicação gerada. Para erros de dependências pares, o guia oficial sugere `npx clear-npx-cache` antes de voltar a tentar. Se o chat apresentar **Connect AI**, conclua a configuração do fornecedor antes de diagnosticar a ação. Se não existir `/hello`, reinicie o servidor de desenvolvimento depois de criar a rota. São passos de recuperação documentados, não resultados observados por nós.

## Fontes e leituras adicionais

- [O guia inicial do Agent-Native](https://www.agent-native.com/docs/) documenta a criação, a instrução ao agente, o hook React, as respostas esperadas e a recuperação. O seu excerto da ação omite uma propriedade presente no modelo fixado; edite a ação gerada no próprio ficheiro.
- [A ação Chat `hello` na revisão fixada](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts) estabelece as propriedades do código, incluindo `mcpTool: true`, no commit `8e8419361fb415682cdf0e0e68538671dbb6aed3`. Este retrato não prova o que uma criação posterior instalará.
- [Variáveis de ambiente](https://www.agent-native.com/docs/environment-variables/) explica o âmbito das chaves, a seleção de modelo e o limite público de `VITE_`. Consulte separadamente os termos do fornecedor; este guia não examinou um pedido real do chat.

## Sources

- [Guia inicial do Agent-Native](https://www.agent-native.com/docs/) — O [guia inicial do Agent-Native](https://www.agent-native.com/docs/) documenta a criação, a instrução ao agente, o hook React, as respostas esperadas e a recuperação. O seu excerto da ação omite uma propriedade presente no modelo fixado; edite a ação gerada no próprio ficheiro.
- [Ação Chat hello na revisão fixada](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts) — A [ação Chat `hello` na revisão fixada](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/templates/chat/actions/hello.ts) estabelece as propriedades do código, incluindo `mcpTool: true`, no commit `8e8419361fb415682cdf0e0e68538671dbb6aed3`. Este retrato não prova o que uma criação posterior instalará.
- [Pacote core na revisão fixada](https://github.com/BuilderIO/agent-native/blob/8e8419361fb415682cdf0e0e68538671dbb6aed3/packages/core/package.json) — Versão do pacote, requisito de Node e licença.
- [Variáveis de ambiente do Agent-Native](https://www.agent-native.com/docs/environment-variables/) — [Variáveis de ambiente](https://www.agent-native.com/docs/environment-variables/) explica o âmbito das chaves, a seleção de modelo e o limite público de `VITE_`. Consulte separadamente os termos do fornecedor; este guia não examinou um pedido real do chat.
- [Controlos de dados da OpenAI API](https://developers.openai.com/api/docs/guides/your-data) — Referência sobre o tratamento de dados pelo fornecedor; não foi observado tráfego específico da tarefa.