Como implantar o LangGraph AI Agent Boilerplate

O LangGraph AI Agent Boilerplate contém as configurações para criar agentes de IA em tempo real que podem consultar e interagir com dados armazenados em um banco de dados do SQL Database da Azion, entregando desempenho otimizado e latência reduzida para suas aplicações.

Este template foi projetado para aproveitar a robusta infraestrutura de edge computing da Azion, garantindo escalabilidade, segurança e integração eficiente com SQL Database.

A implantação deste template cria um banco de dados do SQL Database com duas tabelas: uma para o histórico de conversas e outra para documentos de referência. Além disso, cria uma aplicação backend desenvolvida com LangGraph para gerenciamento de documentos e funcionalidades do agente, e uma interface frontend baseada em Vue para interação do usuário.

Este template utiliza a versão 3.3.4 do Vue.

Pré-requisitos

• Uma conta no GitHub para conectar com a Azion e criar seu novo repositório.
  • Cada push será implantado automaticamente neste repositório para manter seu projeto atualizado.
• Uma chave da API da OpenAI.
• Este template usa Application Accelerator, Functions e SQL Database, e pode gerar custos relacionados ao uso. Verifique a página de preços para obter mais informações.

Implante o template

Você pode obter e configurar seu template pelo Azion Console. Para implantá-lo facilmente no edge, clique no botão abaixo.

Configure o template

No formulário de configuração, forneça as informações para configurar sua aplicação. Preencha os campos apresentados.

Os campos identificados com asterisco são obrigatórios.

1. Conecte a Azion com sua conta no GitHub.

• Uma janela pop-up será aberta para confirmar a instalação da Azion GitHub App, uma ferramenta que conecta sua conta do GitHub com a plataforma da Azion.
• Defina suas permissões e acesso ao repositório conforme desejado.

2. Selecione o Git Scope com o qual trabalhar.
3. Defina um nome para seu agente.
   • Por padrão, o nome do banco de dados segue o padão˜ <agent_name>-database.
   • Use um nome único e fácil de lembrar. Se o nome já tiver sido usado, a plataforma retornará uma mensagem de erro.
4. Insira sua chave da API da OpenAI.
5. Defina o método de autenticação para acessar o agente. Para cada método que você escolher, forneça as informações necessárias:
   • No Auth: nenhuma autenticação é necessária. Deixe os campos em branco.
   • Basic Auth: forneça o token ou senha para autenticação básica.
   • Clerk Auth: insira as chaves pública e privada do Clerk para autenticação pelo serviço. Você pode configurar as regras para o processo de autenticação no dashboard de sua conta Clerk.
6. Clique no botão Deploy para iniciar o processo de implantação.

Durante a implantação, você poderá acompanhar o processo através de uma janela mostrando os logs. Quando estiver concluída, a página mostra informações sobre a aplicação e algumas opções para continuar sua jornada.

Gerencie o template

Configure o banco de dados

Este template cria duas tabelas no banco de dados, uma para o histórico de conversas e outra para os documentos de referência. Para começar a usar seus próprios documentos, você deve configurar o banco de dados seguindo os passos abaixo:

1. Acesse o repositório do Github para a aplicação de backend criada durante a implantação. O nome dele será semelhante a <seu-nome-de-agente>-backend-agent.
2. Você precisa ter um arquivo .env com suas variáveis de ambiente. Se você quiser criar um novo, ele deve seguir a estrutura abaixo:

AZION_TOKEN="azion_token"
OPENAI_API_KEY="your_openai_key"
OPENAI_MODEL= 'gpt-4o'
EMBEDDING_MODEL= 'text-embedding-3-small'

# EdgeSQL database and table names. Usually, table names are not changed,
# and the database name is the name of your agent + database: agent_name_database
MESSAGE_STORE_DB_NAME="yourdb-database"
MESSAGE_STORE_TABLE_NAME='messages'
VECTOR_STORE_DB_NAME="yourdb-database"
VECTOR_STORE_TABLE_NAME='vectors'

# Optional: Langsmith to trace the requests and responses
LANGSMITH_API_KEY=
LANGCHAIN_PROJECT=
LANGCHAIN_TRACING_V2=false

# Optional: Clerk authentication with your frontend
CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=

Observe que nem todas as variáveis de ambiente são obrigatórias. Verifique os detalhes na tabela abaixo.

3. Vá até a pasta ‘migrations’ do projeto e execute o setup do banco de vetores com:

yarn setup

• O projeto utiliza dois arquivos principais para configurar e inicializar os bancos de dados:

  • Banco de Vetores (RAG)

    • O arquivo migrations/setupDatabase.ts é responsável por:
      • Configurar o banco de vetores usando AzionVectorStore.initialize()
      • Criar a tabela vectors com a coluna de embedding apropriada (por exemplo, F32_BLOB(1536) quando EMBEDDING_MODEL=text-embedding-3-small)

  • Banco de Mensagens (Tracing)

    • O arquivo src/services/edgeSqlTracerService.ts gerencia automaticamente:
      • A criação do banco de dados de mensagens (se não existir)
      • A criação da tabela messages usando o DDL gerado por createSetupTableStatement()
      • A configuração é feita sob demanda através do método handleErrors

Você pode editar estes arquivos para personalizar a configuração dos bancos de acordo com suas necessidades específicas.

• Métodos de Configuração Disponíveis

  • O projeto oferece duas abordagens para configurar o banco de vetores no arquivo migrations/setupDatabase.ts:

    • Método Ativo (em uso)

      AzionVectorStore.initialize(embeddingModel, { dbName, tableName }, { mode: "hybrid", columns: ["*"] })
      

    • Método Alternativo (comentado)

      // const vectorStore = new AzionVectorStore(...);
      // await vectorStore.setupDatabase({ mode: "hybrid", columns: ["*"] });
      

4. Para adicionar seus próprios documentos ao sistema de RAG:

   • Coloque seus arquivos de documentos na pasta migrations/files/. O sistema suporta os seguintes formatos: PDF, Markdown (.md), Texto (.txt), JSON.
   • Se a pasta ‘files’ não existir ainda, crie-a.

• Como Funciona:

  • O arquivo migrations/uploadDocs.ts processa os documentos através da função getDocsFromFolder("migrations/files"), que:

    • Lê todos os arquivos suportados da pasta especificada
    • Divide o conteúdo em chunks menores
    • Insere os chunks no vector store para busca semântica

  • Personalizando o Caminho

    • Se preferir usar uma pasta diferente para seus documentos, edite o arquivo migrations/uploadDocs.ts e altere o argumento da função getDocsFromFolder():

// Exemplo: mudando para uma pasta personalizada
const docs = await getDocsFromFolder("minha-pasta-personalizada");

• Upload dos Documentos
  • Após adicionar seus arquivos, execute:

yarn upload-docs

O banco de dados com os documentos de referência agora está pronto e disponível para sua aplicação acessá-lo. Leia a documentação do template para obter mais detalhes sobre como configurar o projeto.

Gerencie a application

Considerando que essa configuração inicial pode não ser ideal para sua aplicação, todas as configurações podem ser personalizadas sempre que você precisar usando o Azion Console.

Para gerenciar e editar as configurações da sua aplicação, siga estas etapas:

1. Acesse o Azion Console.
2. No canto superior esquerdo, selecione Products menu > Applications.

• Você será redirecionado para a página de Applications. Ela lista todas as applications que você criou.

3. Encontre a application relacionada ao template e selecione-a.

• A lista é organizada em ordem alfabética. Você também pode usar a barra de busca localizada no canto superior esquerdo da lista; atualmente, ela é filtrada apenas pelo Application Name, ou nome da application.

Depois de selecionar a aplicação em que você trabalhará, você será direcionado para uma página que contém todas as configurações que você pode ajustar.

Adicione um domínio personalizado

A application criada tem um Azion Workload Domain atribuído para torná-la acessível através do navegador. O domínio tem o seguinte formato: xxxxxxxxxx.map.azionedge.net/. No entanto, você pode adicionar um domínio personalizado para que os usuários acessem sua aplicação por meio dele.