Skip to content

Update langgraph template guide on docs #1974

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
GabrielAzion wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update langgraph template guide on docs #1974

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
245 changes: 142 additions & 103 deletions src/content/docs/en/pages/guides/marketplace/templates/langgraph-template.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,60 +14,60 @@ Preview

The **LangGraph AI Agent Boilerplate** contains the configurations for creating intelligent, real-time agents that can query and interact with data stored in an Azion SQL Database, delivering optimized performance and reduced latency for your applications.

This template is built to leverage Azion's robust edge computing infrastructure, ensuring scalability, security, and seamless integration with SQL Database.
This template is built to leverage Azion's robust edge computing infrastructure, ensuring scalability, security, and seamless integration with SQL Database.

The deployment of this template will create an SQL Database with two tables: one for conversation history and another for reference documents. It also creates a backend application developed with LangGraph for document management and agent functionality, and a Vue-based frontend for user interaction.

This template uses Vue version `3.3.4`.
This template uses **Vue version `3.3.4`**.

---

## Requirements

- A [GitHub account](https://github.com/signup) to connect with Azion and create your new repository.
- Every push will be deployed automatically to this repository to keep your project updated.
- An [OpenAI](https://platform.openai.com/) API Key.
- This template uses [Application Accelerator](/en/documentation/products/build/applications/application-accelerator/), [Functions](/en/documentation/products/build/applications/functions/), and [SQL Database](/en/documentation/products/store/edge-sql/), and it may generate usage-related costs. Check the [pricing page](https://www.azion.com/en/pricing/) for more information.
- A [**GitHub account**](https://github.com/signup) to connect with Azion and create your new repository.
- Every push will be automatically deployed to this repository to keep your project updated.
- An [**OpenAI**](https://platform.openai.com/) **API Key**.
- This template uses [Application Accelerator](/en/documentation/products/build/applications/application-accelerator/), [Functions](/en/documentation/products/build/applications/functions/), and [SQL Database](/en/documentation/products/store/sql-database/), and it may generate usage-related costs. Check the [pricing page](https://www.azion.com/en/pricing/) for more information.

---

## Deploying the template

You can obtain and configure your template through the Azion Console. To easily deploy it at the edge, click the button below.
You can obtain and configure your template through the **Azion Console**. To easily deploy it at the edge, click the button below.

<LinkButton
label="Deploy"
link="https://console.azion.com/create/langgraph-ai-agent-boilerplate"
link="https://console.azion.com/create/azion/langgraph-agent-boilerplate"
icon="ai ai-azion"
icon-pos="left"
/>
/>

---

## Setting up the template

In the configuration form, you must provide the information to configure your application. Fill in the presented fields.
In the configuration form, you must provide the information to configure your application. Fill in the presented fields.

Fields identified with an asterisk are mandatory.
Fields identified with an asterisk are **mandatory**.

1. Connect Azion with your GitHub account.
1. Connect **Azion** with your **GitHub** account.
- A pop-up window will open to confirm the installation of the [Azion GitHub App](/en/documentation/products/guides/azion-github-app/), a tool that connects your GitHub account with Azion's platform.
- Define your permissions and repository access as desired.
2. Select the **Git Scope** to work with.
3. Define a name for your agent.
2. Select the **Git Scope** to work with.
3. Define a **name** for your agent.
- By default, the name of the database follows the pattern `<agent_name>-database`.
- Use a unique and easy-to-remember name. If the name has already been used, the platform returns an error message.
4. Insert your **OpenAI** API key.
5. Define the authentication method for accessing the agent. For each method you can choose, provide the necessary information:
- **No auth**: no authentication is required. Leave the fields blank.
4. Insert your **OpenAI API key**.
5. Define the **authentication method** for accessing the agent. For each method you can choose, provide the necessary information:
- **No Auth**: no authentication is required. Leave the fields blank.
- **Basic Auth**: provide the token/password for basic authentication.
- **Clerk Auth**: insert the [Clerk](https://clerk.com) public and private keys for authentication through this service. You can configure the rules for the authentication process in the dashboard of your Clerk account.
6. Click the **Deploy** button to start the deployment process.
6. Click the **Deploy** button to start the deployment process.

During the deployment, you'll be able to follow the process through a window showing the logs. When it's complete, the page shows information about the application and some options to continue your journey.

:::note
The link to the application allows you to see it on the browser. However, it takes a certain time to propagate and configure the application in Azion's data center. It may be necessary to wait a few minutes for the URL to be activated and for the application page to be effectively displayed in the browser.
The link to the application allows you to see it on the browser. However, it takes a certain time to propagate and configure the application in Azion's edge locations. It may be necessary to wait a few minutes for the URL to be activated and for the application page to be effectively displayed in the browser.
:::

---
Expand All @@ -78,101 +78,140 @@ The link to the application allows you to see it on the browser. However, it tak

This template creates two tables in the database, one for conversation history and another for reference documents. To start using your own documents, you must set up the database by following these steps:

1. Access the Github repository for the **backend application** created during the deployment. Its name will be similar to `<your-agent-name>-backend-agent`.
2. You must have a `.env` file with your environment variables in it. If you want to create a new one, it must follow the structure below:

```
AZION_TOKEN=
OPENAI_API_KEY=
OPENAI_MODEL=
EMBEDDING_MODEL=

LANGSMITH_API_KEY=
LANGCHAIN_PROJECT=
LANGCHAIN_TRACING_V2=false

MESSAGE_STORE_DB_NAME=
MESSAGE_STORE_TABLE_NAME=

VECTOR_STORE_DB_NAME=
VECTOR_STORE_TABLE_NAME=
```
Note that not all environment variables are required. Check details on the table below.

| Environment variable | Description | Required |
|---------------------------|-----------------------------------------------------------------------------|----------|
| AZION_TOKEN | The token for authenticating with Azion's platform. | Yes |
| OPENAI_API_KEY | Your API key for accessing OpenAI services. | Yes |
| OPENAI_MODEL | The OpenAI model to be used for processing. If not set, defaults to `gpt-4o`. | No |
| EMBEDDING_MODEL | The model used for generating embeddings. If not set, defaults to `text-embedding-3-small`. To use a different model, you must create a database with columns configured for the same model. | No |
| LANGSMITH_API_KEY | API key for accessing Langsmith services. | No |
| LANGCHAIN_PROJECT | The Langchain project identifier. | No |
| LANGCHAIN_TRACING_V2 | Enables or disables Langchain tracing (set to true or false). | No |
| MESSAGE_STORE_DB_NAME | The database name for storing conversation history messages. By default, it is the same as the database for the documents. Default name: `<agent-name>-database`. | Yes |
| MESSAGE_STORE_TABLE_NAME | The table name within the messages database for storing the conversation history. Default name: `messages`. | Yes |
| VECTOR_STORE_DB_NAME | The database name for storing your documents as vector embeddings. By default, it is the same as the database for the messages. Default name: `<agent-name>-database`. | Yes |
| VECTOR_STORE_TABLE_NAME | The table name within the documents database for storing embeddings. Default name: `<vectors`. | Yes |
1. Access the Github repository for the **backend application** created during the deployment. Its name will be similar to `<your-agent-name>-backend-agent`.
2. You must have a **`.env` file** with your environment variables in it. If you want to create a new one, it must follow the structure below:

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

:::tip
You can use the [Azion EdgeSQL Shell](/en/documentation/products/store/sql/edge-sql-shell-commands/) to interact with your databases. This shell provides a command-line interface that allows you to better visualize your databases and tables and execute SQL commands directly from the terminal.
:::
# 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=
```

Note that not all environment variables are required. Check details on the table below.

| Environment variable | Description | Required |
|---|---|---|
| **AZION_TOKEN** | The token for authenticating with Azion's platform. | Yes |
| **OPENAI_API_KEY** | Your API key for accessing OpenAI services. | Yes |
| **OPENAI_MODEL** | The OpenAI model to be used for processing. If not set, defaults to `gpt-4o`. | No |
| **EMBEDDING_MODEL** | The model used for generating embeddings. If not set, defaults to `text-embedding-3-small`. To use a different model, you must create a database with columns configured for the same model. | No |
| **LANGSMITH_API_KEY** | API key for accessing Langsmith services. | No |
| **LANGCHAIN_PROJECT** | The Langchain project identifier. | No |
| **LANGCHAIN_TRACING_V2** | Enables or disables Langchain tracing (set to `true` or `false`). | No |
| **MESSAGE_STORE_DB_NAME** | The database name for storing conversation history messages. By default, it is the same as the database for the documents. Default name: `<agent-name>-database`. | Yes |
| **MESSAGE_STORE_TABLE_NAME** | The table name within the messages database for storing the conversation history. Default name: `messages`. | Yes |
| **VECTOR_STORE_DB_NAME** | The database name for storing your documents as vector embeddings. By default, it is the same as the database for the messages. Default name: `<agent-name>-database`. | Yes |
| **VECTOR_STORE_TABLE_NAME** | The table name within the documents database for storing embeddings. Default name: `vectors`. | Yes |

:::tip
You can use the [Azion EdgeSQL Shell](/en/documentation/products/store/sql/sql-database-shell-commands/) to interact with your databases. This shell provides a command-line interface that allows you to better visualize your databases and tables and execute SQL commands directly from the terminal.
It's also possible to interact with your databases through the [Azion API](https://api.azion.com/v4#/operations/GetEdgeSqlDatabases).
:::

3. Go to the project's **`migrations`** folder and run the vector database setup with:

```bash
yarn setup
```

- The project uses two main files to configure and initialize the databases:

- **Vector Database (RAG)**
- The file **`migrations/setupDatabase.ts`** is responsible for:
- Configuring the vector database using `AzionVectorStore.initialize()`
- Creating the `vectors` table with the appropriate embedding column (e.g., `F32_BLOB(1536)` when `EMBEDDING_MODEL=text-embedding-3-small`)

- **Message Database (Tracing)**
- The file **`src/services/edgeSqlTracerService.ts`** automatically manages:
- The creation of the message database (if it doesn't exist)
- The creation of the `messages` table using the DDL generated by `createSetupTableStatement()`
- Configuration is done on demand through the `handleErrors` method

:::note
The file `migrations/uploadDocs.ts` only inserts documents into existing databases, so it's necessary to run the setup before uploading documents.
:::

You can edit these files to customize the database configuration according to your specific needs.

- Available Configuration Methods

- The project offers two approaches to configure the vector database in the `migrations/setupDatabase.ts` file:

- Active Method (in use)

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

- Alternative Method (commented)

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

:::note
Make sure to run `yarn setup` before the first upload to ensure the vector database is correctly configured.
:::

4. To add your own documents to the **RAG system**:

- Place your document files in the folder **`migrations/files/`**. The system supports the following formats: **PDF, Markdown (`.md`), Text (`.txt`), JSON**.
- If the 'files' folder does not exist yet, create it.

- **How It Works:**
- The file **`migrations/uploadDocs.ts`** processes documents through the function `getDocsFromFolder("migrations/files")`, which:
- Reads all supported files from the specified folder
- Splits the content into smaller chunks
- Inserts the chunks into the vector store for semantic search

- Customizing the Path
- If you prefer to use a different folder for your documents, edit the file `migrations/uploadDocs.ts` and change the argument of the `getDocsFromFolder()` function:

```typescript
// Example: changing to a custom folder
const docs = await getDocsFromFolder("my-custom-folder");
```

- Uploading Documents
- After adding your files, execute:
```bash
yarn upload-docs
```

3. Open the file `setup/setup.ts`. This file contains the function that sets up the database, and you can edit it to match your requirements:
- You can change the names of environment variables to match your `.env` file if needed, or even pass some of them directly in the code.
- Edit the value of the constant `productDocs`. It uses by default the return of the function `getDocs`, which is configured in the boilerplate to process data from an example file. You can add your own documents file in the `setup` folder.
- The template automatically creates the database during the deployment, but you can configure the function to create your database according to the environment variables. There are two options available in the code for doing this. They are written as comments, and you can uncomment the one you prefer.

The first option uses a static factory method:

```ts
const vectorStore = await AzionVectorStore.createVectorStore(
embeddingModel,
{
dbName: VECTOR_STORE_DB_NAME,
tableName: VECTOR_STORE_TABLE_NAME
},
{
columns,
mode: "hybrid"
}
);
```

Alternatively, you can choose to create the instance and setup the database separately:

```ts
const vectorStore = new AzionVectorStore(embeddingModel, {
dbName: VECTOR_STORE_DB_NAME,
tableName: VECTOR_STORE_TABLE_NAME
});
await vectorStore.setupDatabase({
columns,
mode: "hybrid"
});
```

4. Run the following command in the project`s root directory to execute the function that sets up the database:

```bash
yarn setup
```

The database is now set with your documents and ready for your application to access it. Read the [template documentation](https://github.com/aziontech/azion-samples/tree/3cf53a690ac7f40508bc020adcfc61ba553d0b2f/templates/typescript/azion-react-agent) to see more details about configuring the project.
The database with reference documents is now ready and available for your application to access it. Read the [template documentation](https://github.com/aziontech/azion-samples/tree/3cf53a690ac7f40508bc020adcfc61ba553d0b2f/templates/typescript/azion-react-agent) for more details on how to configure the project.

:::note
The template also creates a table for storing the messages exchanged with the agent. By default, it'll store messages for *14 days*.
:::

### Managing the application

Considering that this initial setup may not be optimal for your specific application, all settings can be customized any time you need by using Azion's platform.
Considering that this initial setup may not be optimal for your specific application, all settings can be customized any time you need by using the **Azion Console**.

To manage and edit your application's settings, follow these steps:

1. [Access Azion Console](https://console.azion.com).
2. On the upper-left corner, select **Products menu**, the icon with three horizontal lines, > **Applications**.
1. [Access Azion Console](https://console.azion.com).
2. On the upper-left corner, select **Products menu** > **Applications**.
- You'll be redirected to the **Applications** page. It lists all the applications you've created.
3. Find the application related to your template and select it.
3. Find the application related to your template and select it.
- The list is organized alphabetically. You can also use the **search bar** located in the upper-left corner of the list; currently, it filters only by **Application Name**.

After selecting the application you'll work on, you'll be directed to a page containing all the settings you can configure.
Expand All @@ -183,8 +222,8 @@ Read the documentation about [managing applications](/en/documentation/products/

### Adding a custom domain

The application created during the deployment has an assigned Azion Workload domain to make it accessible through the browser. The domain has the following format: `xxxxxxxxxx.map.azionedge.net/`. However, you can add a custom domain for users to access your application through it.
The application created during the deployment has an assigned Azion Workload domain to make it accessible through the browser. The domain has the following format: `xxxxxxxxxx.map.azionedge.net/`. However, you can add a **custom domain** for users to access your application through it.

import LinkButton from 'azion-webkit/linkbutton';

<LinkButton link="/en/documentation/products/guides/configure-a-domain/" label="Go to Configuring a Domain Guide" severity="secondary" />
<LinkButton link="/en/documentation/products/guides/configure-a-domain/" label="Go to Configuring a Domain Guide" severity="secondary" />
Loading