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, AG-UI e LangGraph em cima do Next.js. Também serve como um ponto de partida para UI gen declarativa via A2UI (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 (gestor de pacotes Python)
• Qualquer um dos seguintes gestores de pacotes:
• npm (padrão)
• pnpm
• yarn
• bun
• Chave da API OpenAI (para o agente LangGraph)

Começar

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

npm install

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:

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:

cp .env.example .env

Configuração do Projeto

Pré-requisitos

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

• Node.js (versão 14 ou superior)
• npm (geralmente instalado com o Node.js)

Instalação

1. Clona o repositório:

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

2. Navega até à pasta do projeto:

cd projeto

3. Instala as dependências:

npm install

Configuração do Ambiente

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

OPENAI_API_KEY=your_api_key_here

Execução

Para iniciar o projeto, utiliza o seguinte comando:

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.

OPENAI_API_KEY=your-openai-api-key-here

3. Inicia o servidor de desenvolvimento:

npm run dev

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, 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

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

Ficheiros chave

Adicionando um componente personalizado

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

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

2. Renderiza em renderers.tsx:

   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
• CopilotKit A2UI Documentation

Documentação

• LangGraph Documentation - Aprende mais sobre o LangGraph e as suas funcionalidades
• CopilotKit Documentation - Explora as capacidades do CopilotKit