# Projeto Inicial de UI Generativa

> Um quadro kanban orientado por chat onde o utilizador e o agente trabalham na mesma lista de tarefas.

- Fonte: https://doutorai.pt/apps/generative-ui-starter-project
- Categoria: Interfaces Generativas
- Dificuldade: Avançado
- Modelos: OpenAI
- Frameworks: LangChain
- Corre local?: Precisa de APIs cloud
- Chaves necessárias: OPENAI_API_KEY
- Licença: Apache-2.0
- Site: Doutor AI (https://doutorai.pt) - ferramentas de IA para pequenos negócios em português

## Tutorial completo

# Projeto Inicial de UI Generativa

Um quadro kanban orientado por chat onde tu e o agente trabalham na mesma lista de tarefas. Construído com [CopilotKit](https://github.com/CopilotKit/CopilotKit), [AG-UI](https://github.com/ag-ui-protocol/ag-ui) e [LangGraph](https://www.langchain.com/langgraph) em cima do Next.js. Também serve como um ponto de partida para UI gen declarativa via [A2UI](https://a2ui.org/specification/) (exemplo de pesquisa de voos incluído).

**Conceito de UI Gen - estado partilhado do agente.** O quadro (colunas A Fazer / Feito) vive no agente e sincroniza bidirecionalmente com o React através de `useAgent()`. O agente move cartões através de chamadas de ferramentas; tu clicas, editas e reorganizas no UI. Ambos os lados observam e reagem ao mesmo estado - sem armazenamento frontend separado, sem sincronização manual.

https://github.com/user-attachments/assets/47761912-d46a-4fb3-b9bd-cb41ddd02e34

## Pré-requisitos

- Node.js 18+
- Python 3.8+
- [uv](https://docs.astral.sh/uv/) (gestor de pacotes Python)
- Qualquer um dos seguintes gestores de pacotes:
  - npm (padrão)
  - [pnpm](https://pnpm.io/installation)
  - [yarn](https://classic.yarnpkg.com/lang/en/docs/install/)
  - [bun](https://bun.sh/)
- Chave da API OpenAI (para o agente LangGraph)

## Começar

1. Instala as dependências (npm, ou pnpm/yarn/bun):

```bash
npm install
```

```markdown
# Instalação do Agente Python

## Pré-requisitos

Antes de começares, assegura-te de que tens os seguintes requisitos instalados:

- Python 3.6 ou superior
- pip

## Instalação

1. Instala o agente Python utilizando o seguinte comando:

   ```bash
   pip install python-agent
   ```

   Isto também instalará as dependências do agente Python através de `uv sync`.

2. Configura as tuas variáveis de ambiente:
```

```bash
cp .env.example .env
```

```markdown
# Configuração do Projeto

## Pré-requisitos

Antes de começares, certifica-te de que tens os seguintes requisitos instalados:

- [Node.js](https://nodejs.org/) (versão 14 ou superior)
- [npm](https://www.npmjs.com/) (geralmente instalado com o Node.js)

## Instalação

1. Clona o repositório:

   ```bash
   git clone https://github.com/usuario/projeto.git
   ```

2. Navega até à pasta do projeto:

   ```bash
   cd projeto
   ```

3. Instala as dependências:

   ```bash
   npm install
   ```

## Configuração do Ambiente

Depois, edita o ficheiro `.env` e adiciona a tua chave de API do OpenAI:

```plaintext
OPENAI_API_KEY=your_api_key_here
```

## Execução

Para iniciar o projeto, utiliza o seguinte comando:

```bash
npm start
```

## Contribuição

Se quiseres contribuir, por favor, cria um fork do repositório e envia um pull request com as tuas alterações.

## Licença

Este projeto está licenciado sob a Licença MIT. Consulta o ficheiro `LICENSE` para mais informações.
```

```bash
OPENAI_API_KEY=your-openai-api-key-here
```

```markdown
3. Inicia o servidor de desenvolvimento:
```

```bash
npm run dev
```

```markdown
Isto irá iniciar tanto os servidores de UI como de agente em simultâneo.

## Scripts Disponíveis

Os seguintes scripts também podem ser executados utilizando o teu gestor de pacotes preferido:

- `dev` - Inicia ambos os servidores de UI e de agente em modo de desenvolvimento
- `dev:debug` - Inicia os servidores de desenvolvimento com registo de depuração ativado
- `dev:ui` - Inicia apenas o servidor de UI do Next.js
- `dev:agent` - Inicia apenas o servidor do agente LangGraph
- `build` - Compila a aplicação Next.js para produção
- `start` - Inicia o servidor de produção
- `install:agent` - Instala as dependências Python para o agente

## Estrutura do Projeto
```

```
├── src/                         # Next.js frontend source
│   ├── app/
│   │   ├── page.tsx             # Main page
│   │   └── api/copilotkit/      # CopilotKit API route
│   ├── components/
│   │   ├── example-canvas/      # Todo list UI
│   │   ├── example-layout/      # Layout: chat + canvas side-by-side
│   │   └── generative-ui/       # Example generative UI components
│   └── hooks/
├── agent/                       # LangGraph Python agent
│   ├── main.py                  # Agent entry point
│   └── src/
│       ├── todos.py             # Todo tools and state schema
│       └── query.py             # Example data query tool
├── scripts/                     # Agent setup and run scripts
│   ├── setup-agent.sh / .bat
│   └── run-agent.sh / .bat
├── public/                      # Static assets
├── next.config.ts
├── tsconfig.json
└── package.json
```

## A2UI - Interface de Agente para Utilizador

Este starter inclui suporte para [A2UI](https://a2ui.org/specification/), permitindo que o agente gere superfícies de UI ricas e interativas de forma declarativa. Em vez de devolver texto simples, o agente envia uma descrição JSON da UI que deseja renderizar, e o frontend transforma-a em componentes reais.

### Como funciona

A2UI utiliza três conceitos:

1. **Catálogo** - um conjunto de definições de componentes (esquema) emparelhadas com renderizadores React. Registado uma vez em `layout.tsx` através de `<CopilotKitProvider a2ui={{ catalog: demonstrationCatalog }}>`.
2. **Superfície** - uma instância de UI renderizada. O agente cria uma superfície, define os seus componentes e liga dados a ela.
3. **Operações** - o agente devolve `a2ui.render(operations=[...])` de uma ferramenta, que o middleware transmite para o frontend.

### Dois padrões

| Padrão             | Descrição                                                                   | Ferramenta do agente | Frontend                                    |
| ------------------ | --------------------------------------------------------------------------- | --------------------- | ------------------------------------------- |
| **Esquema fixo**   | Layout de componente pré-definido. Apenas os dados mudam por invocação.   | `search_flights`      | Esquema em `a2ui/schemas/flight_schema.json` |
| **Esquema dinâmico** | Um LLM secundário gera tanto componentes como dados com base na conversa. | `generate_a2ui`       | Componentes decididos em tempo de execução  |

Ambos os padrões utilizam o mesmo catálogo no frontend - a diferença está na origem da árvore de componentes.

### Ficheiros chave

| Propósito                              | Caminho                                               |
| -------------------------------------- | ---------------------------------------------------- |
| Definições do catálogo (esquemas Zod) | `src/app/declarative-generative-ui/definitions.ts`  |
| Renderizadores do catálogo (componentes React) | `src/app/declarative-generative-ui/renderers.tsx`  |
| Registo do catálogo                    | `src/app/layout.tsx`                                 |
| Ferramenta do agente com esquema fixo  | `agent/src/a2ui_fixed_schema.py`                     |
| Ferramenta do agente com esquema dinâmico | `agent/src/a2ui_dynamic_schema.py`                   |
| JSON do esquema de voo                 | `agent/src/a2ui/schemas/flight_schema.json`          |
| Configuração da montra                 | `showcase.json`                                      |

### Adicionando um componente personalizado

1. **Define** o esquema do componente em `definitions.ts`:

```typescript
   MyWidget: {
     description: "A brief description for the agent.",
     props: z.object({ title: z.string(), value: z.number() }),
   },
   ```

```markdown
2. **Renderiza** em `renderers.tsx`:
```

```typescript
   MyWidget: ({ props }) => (
     <div>{props.title}: {props.value}</div>
   ),
   ```

Renderers são verificados quanto ao tipo em relação às definições - TypeScript irá gerar um erro se as props não corresponderem.

3. **Usa-o** a partir do agente. O componente está automaticamente disponível tanto para templates de esquema fixo como para o LLM de esquema dinâmico.

### Adicionar uma nova ferramenta de esquema fixo

1. Cria um ficheiro de esquema JSON em `agent/src/a2ui/schemas/` que descreva a árvore de componentes.
2. Cria uma ferramenta em Python que carrega o esquema com `a2ui.load_schema()` e retorna `a2ui.render(operations=[...])` com os teus dados. Consulta `a2ui_fixed_schema.py` para o padrão.

### Modo de apresentação

`showcase.json` controla quais as sugestões que são visualmente destacadas. Define `"showcase": "a2ui"` para destacar as demonstrações do A2UI, ou `"showcase": "default"` para não haver destaques. Isto é configurado automaticamente ao criar a estrutura via `npx copilotkit create --framework a2ui`.

### Leitura adicional

- [A2UI Specification](https://a2ui.org/specification/)
- [CopilotKit A2UI Documentation](https://docs.copilotkit.ai)

## Documentação

- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/) - Aprende mais sobre o LangGraph e as suas funcionalidades
- [CopilotKit Documentation](https://docs.copilotkit.ai) - Explora as capacidades do CopilotKit

## Poupe horas todas as semanas com IA, sem complicações

O **Doutor AI** dá-lhe 1859 prompts de IA prontos a copiar, por indústria e em português simples - mais uma biblioteca técnica completa para quem quer ir mais longe. [Ver planos →](https://doutorai.pt/precos)

---
Conteúdo de Doutor AI (https://doutorai.pt). Ao citar, indique a fonte: https://doutorai.pt/apps/generative-ui-starter-project