# Como implantar o LangGraph AI Agent Boilerplate

import Tag from '~/components/webkit/Tag.vue';

<Tag severity="info">
Preview
</Tag>

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](https://github.com/signup) 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](https://platform.openai.com/).    
- Este template usa [Application Accelerator](/pt-br/documentacao/produtos/build/applications/application-accelerator/), [Functions](/pt-br/documentacao/produtos/build/applications/functions/) e [SQL Database](/pt-br/documentacao/produtos/store/sql-database/), e pode gerar custos relacionados ao uso. Verifique a [página de preços](https://www.azion.com/pt-br/precos/) 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.

<DocButton
    label="Implantar"
    href="https://console.azion.com/create/azion/langgraph-agent-boilerplate"
    icon="ai ai-azion"
    size="medium"
/>

---

## 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](/pt-br/documentacao/produtos/guias/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](https://clerk.com) 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.

:::note
O link para sua application permite que você veja como ela fica no navegador. No entanto, leva um certo tempo para propagar e configurá-la nas edge locations da Azion. Pode ser necessário aguardar alguns minutos para que a URL seja ativada e para que a página da aplicação seja efetivamente exibida no navegador.
:::


## 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.

| Variável de ambiente      | Descrição                                                                 | Obrigatória |
|---------------------------|-----------------------------------------------------------------------------|------------|
| AZION_TOKEN               | O token para autenticação na plataforma da Azion. | Sim |
| OPENAI_API_KEY            | Sua chave de API para acessar serviços da OpenAI. | Sim |
| OPENAI_MODEL              | O modelo da OpenAI a ser usado para processamento. Se não for definido, o valor padrão é `gpt-4o`. | Não |
| EMBEDDING_MODEL           | O modelo usado para gerar embeddings. Se não for definido, o valor padrão é `text-embedding-3-small`. Se quiser usar um modelo diferente, você precisa criar um banco de dados com colunas configuradas para o mesmo modelo.| Não |
| LANGSMITH_API_KEY         | Chave de API para acessar serviços da Langsmith. | Não |
| LANGCHAIN_PROJECT         | O identificador do projeto Langchain. | Não |
| LANGCHAIN_TRACING_V2      | Habilita ou desabilita o rastreamento do Langchain (defina como `true` ou `false`). | Não |
| MESSAGE_STORE_DB_NAME     | O nome do banco de dados para armazenar mensagens do histórico de conversas. Por padão, é o mesmo banco de dados usado para armazenar seus documentos. Nome padrão: `<nome-do-agente>-database`. | Sim |
| MESSAGE_STORE_TABLE_NAME  | O nome da tabela dentro do banco de dados de mensagens para armazenar o histórico de conversas. Nome padrão: `messages`. | Sim |
| VECTOR_STORE_DB_NAME      | O nome do banco de dados para armazenar seus documentos como embeddings de vetores. Por padão, é o mesmo banco de dados usado para armazenar suas mensagens. Nome padrão: `<nome-do-agente>-database`. | Sim |
| VECTOR_STORE_TABLE_NAME   | O nome da tabela dentro do banco de dados de documentos para armazenar embeddings. Nome padrão: `<vectors`. | Sim |

:::tip
Você pode usar o [Azion EdgeSQL Shell](/pt-br/documentacao/produtos/store/sql/edge-sql-shell-commands/) para interagir com seus bancos de dados. Este shell fornece uma interface de linha de comando que permite visualizar melhor seus bancos de dados e tabelas e executar comandos SQL diretamente do terminal.
É possível também interagir com seus bancos de dados através da [API da Azion](https://api.azion.com/v4#/operations/GetEdgeSqlDatabases).
:::

3. Vá até a pasta 'migrations' do projeto e execute o setup do banco de vetores com:
```bash
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`

:::note 
O arquivo `migrations/uploadDocs.ts` apenas insere documentos nos bancos já existentes, por isso é necessário executar o setup antes de fazer upload de documentos.
:::

  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)

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

        - Método Alternativo (comentado)

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


:::note
Certifique-se de executar `yarn setup` antes do primeiro upload para garantir que o banco de vetores esteja configurado corretamente.
::: 


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()`:

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

    - Upload dos Documentos
      - Após adicionar seus arquivos, execute:
```bash
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](https://github.com/aziontech/azion-samples/tree/3cf53a690ac7f40508bc020adcfc61ba553d0b2f/templates/typescript/azion-react-agent) para obter mais detalhes sobre como configurar o projeto.

:::note
O template também cria uma tabela para armazenar as mensagens trocadas com o agente. Por padrão, ela armazena mensagens por *14 dias*.
:::

### 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](https://console.azion.com).
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.

:::tip
Leia a documentação sobre o [gerenciamento de applications](/pt-br/documentacao/produtos/build/applications/primeiros-passos/) para obter mais detalhes.
:::

### 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.

import DocButton from '~/components/webkit/DocButton.vue';

<DocButton href="/pt-br/documentacao/produtos/guias/configurar-dominio/" label="Consulte o guia para configurar domínios" kind="secondary" size="medium" />