Introdução

O Step 01 do workshop é o ponto de partida: você sobe uma aplicação Quarkus que conversa com um LLM via OpenAI e testa um chatbot funcional no navegador. Ao final deste capítulo, você terá passado pelo fluxo completo de ambiente, credencial e execução, o mesmo tipo de passo que repetirá em projetos reais.

O que você vai aprender

  • O que são Quarkus, LLM e LangChain4j e como se encaixam
  • Como declarar um AI Service como interface Java (@RegisterAiService)
  • A anatomia mínima do projeto Step 01 (duas classes Java + configuração)
  • Por que LLMs são stateless e quem mantém o histórico da conversa
  • Como executar ./mvnw quarkus:dev e testar o chatbot

Conceitos-chave

Quarkus + LangChain4j

Quarkus é um framework Java otimizado para cloud-native: inicia rápido, consome pouca memória e oferece live reload no modo dev. LangChain4j é a biblioteca Java que abstrai chamadas a LLMs. Em vez de montar JSON de requisição manualmente, você declara uma interface e a biblioteca cuida do resto.

A extensão Quarkus LangChain4j integra tudo ao CDI: lê application.properties, gera a implementação do AI Service em build time e injeta beans com @Inject.

AI Service

Um AI Service é uma interface Java anotada com @RegisterAiService. Não há implementação manual; o Quarkus gera o código em tempo de compilação:

@SessionScoped
@RegisterAiService
public interface CustomerSupportAgent {

    String chat(String userMessage);
}

O método chat recebe a mensagem do usuário e retorna a resposta do LLM. A anotação @SessionScoped garante que cada sessão WebSocket tenha sua própria instância do agente (e, portanto, seu próprio histórico de conversa).

Memória e statelessness

LLMs são stateless: cada chamada à API é independente. Para o chatbot “lembrar” do contexto, a aplicação reenvia o histórico completo da conversa a cada interação. No Step 01, o Quarkus LangChain4j gerencia isso automaticamente por sessão.

Anatomia do projeto

O Step 01 tem apenas duas classes Java no backend:

section-1/step-01/
├── pom.xml
├── src/main/java/.../
│   ├── CustomerSupportAgent.java          ← interface AI Service
│   └── CustomerSupportAgentWebSocket.java ← endpoint WebSocket
└── src/main/resources/
    ├── application.properties             ← config (API key, modelo)
    └── META-INF/resources/                ← UI do chat

A configuração essencial fica em application.properties:

quarkus.langchain4j.openai.api-key=${OPENAI_API_KEY}
quarkus.langchain4j.openai.chat-model.model-name=gpt-4o

O WebSocket em /customer-support-agent recebe mensagens do navegador e delega ao AI Service:

@WebSocket(path = "/customer-support-agent")
public class CustomerSupportAgentWebSocket {

    private final CustomerSupportAgent customerSupportAgent;

    @OnTextMessage
    public String onTextMessage(String message) {
        return customerSupportAgent.chat(message);
    }
}

Fluxo da aplicação 

sequenceDiagram
    participant User as Usuário
    participant WS as WebSocket
    participant Agent as CustomerSupportAgent
    participant LLM as OpenAI

    User->>WS: mensagem via chat
    WS->>Agent: chat(mensagem)
    Agent->>LLM: system + histórico + mensagem
    LLM-->>Agent: resposta
    Agent-->>WS: resposta
    WS-->>User: exibe no chat

Tarefa para casa

Objetivo: executar localmente o Step 01 do workshop oficial: subir o projeto Quarkus + LangChain4j e conversar com o chatbot.

Referência: Quarkus LangChain4j Workshop, Section 1, Step 01.

Pré-requisitos

  • Java 17+ instalado (java -version)
  • Git instalado
  • Conta OpenAI com créditos disponíveis

O que fazer

  1. Clonar o repositório do workshop e abrir o projeto section-1/step-01 na sua IDE.
  2. Obter uma API key da OpenAI: criar conta em OpenAI se necessário, gerar uma chave em API keys e exportá-la no terminal: 
    export OPENAI_API_KEY=sk-...

    Não commite a chave nem coloque em arquivo versionado.

  3. Verificar que application.properties referencia ${OPENAI_API_KEY}.
  4. Subir a aplicação: 
    cd section-1/step-01
./mvnw quarkus:dev
  5. Abrir http://localhost:8080 no navegador e enviar pelo menos uma mensagem ao chatbot.

Critério de sucesso

Você envia uma mensagem (por exemplo, “Olá, quero alugar um carro”) e recebe uma resposta coerente do bot no chat.

Troubleshooting

Problema Solução
OPENAI_API_KEY not set Exporte a variável no mesmo terminal onde roda ./mvnw quarkus:dev e reinicie
Erro 401 da OpenAI Verifique se a chave é válida e tem créditos
Porta 8080 ocupada Pare outra aplicação na porta ou configure quarkus.http.port

Próximo passo

Com o chatbot funcionando, avance para o trilho AI Services. Comece por Configuration and Streaming, onde você aprende a ajustar parâmetros do modelo, fazer streaming de respostas e definir system messages.

Referência

Quarkus LangChain4j Workshop

Rodrigo Prestes Machado
CC BY 4.0 DEED