From f2341b4d980b0b105869ec215f77a6e3858cc7a4 Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Mon, 8 Jun 2026 14:52:05 -0400 Subject: [PATCH 1/3] docs: refresh tools and image generation guides --- .../configuration/tools/azure_ai_search.mdx | 23 ++-- .../docs/configuration/tools/calculator.mdx | 34 ++++++ content/docs/configuration/tools/flux.mdx | 8 ++ .../configuration/tools/gemini_image_gen.mdx | 8 +- .../configuration/tools/google_search.mdx | 2 +- content/docs/configuration/tools/index.mdx | 108 ++++++++++++------ content/docs/configuration/tools/meta.json | 5 +- .../docs/configuration/tools/openweather.mdx | 21 ++-- .../configuration/tools/stable_diffusion.mdx | 17 ++- content/docs/configuration/tools/tavily.mdx | 70 ++++++++++++ .../docs/configuration/tools/traversaal.mdx | 65 +++++++++++ content/docs/configuration/tools/wolfram.mdx | 23 +++- content/docs/features/agents.mdx | 13 ++- content/docs/features/image_gen.mdx | 27 +++-- content/docs/meta.json | 2 +- 15 files changed, 348 insertions(+), 78 deletions(-) create mode 100644 content/docs/configuration/tools/calculator.mdx create mode 100644 content/docs/configuration/tools/tavily.mdx create mode 100644 content/docs/configuration/tools/traversaal.mdx diff --git a/content/docs/configuration/tools/azure_ai_search.mdx b/content/docs/configuration/tools/azure_ai_search.mdx index db1c4a97b..b96ac1681 100644 --- a/content/docs/configuration/tools/azure_ai_search.mdx +++ b/content/docs/configuration/tools/azure_ai_search.mdx @@ -3,20 +3,19 @@ title: Azure AI Search icon: Radar description: How to configure Azure AI Search for answers to your questions with assistance from GPT. --- -Through the plugins endpoint, you can use Azure AI Search for answers to your questions with assistance from GPT. +Azure AI Search is a built-in agent tool that lets an agent query your Azure AI Search index and use the returned documents in its answer. -## Configurations +## Configuration ### Required -To get started, you need to get a Azure AI Search endpoint URL, index name, and a API Key. You can then define these as follows in your `.env` file: +To get started, you need an Azure AI Search endpoint URL, index name, and API key. Define them in your `.env` file: ```env AZURE_AI_SEARCH_SERVICE_ENDPOINT="..." AZURE_AI_SEARCH_INDEX_NAME="..." AZURE_AI_SEARCH_API_KEY="..." ``` -Or you need to get an Azure AI Search endpoint URL, index name, and an API Key. You can define them during the installation of the plugin. ### AZURE_AI_SEARCH_SERVICE_ENDPOINT @@ -96,21 +95,23 @@ Now select the free option or select your preferred option (may incur charges). ![image](/images/azure-ai-search/azure_ai_search_keys.png) -# Configure in LibreChat: +## Add the Tool to an Agent -**1.** Access the Plugins and click to install Azure AI Search. +After adding the environment variables, restart LibreChat and add **Azure AI Search** to an agent. -![image](/images/azure-ai-search/librechat_settings.png) +| Deployment | Command | +|------------|---------| +| Docker | `docker compose down && docker compose up -d` | +| Local | Stop the server, then run `npm run backend` again | +In LibreChat, select **Agents**, create or edit an agent, open the agent's **Tools** list, select **Azure AI Search**, and save the agent. -**2.** Fill in the Endpoint, Index Name, and API Key, and click on `Save`. +## Test It -# Conclusion +Ask the agent a question that should be answered by your Azure AI Search index. If the tool returns too much content, tune `AZURE_AI_SEARCH_SEARCH_OPTION_TOP` and `AZURE_AI_SEARCH_SEARCH_OPTION_SELECT`. ![image](/images/azure-ai-search/chat_with_azure_ai_search.png) -Now, you will be able to conduct searches using Azure AI Search. Congratulations! 🎉🎉 - ## Optional The following are configuration values that are not required but can be specified as parameters during a search. diff --git a/content/docs/configuration/tools/calculator.mdx b/content/docs/configuration/tools/calculator.mdx new file mode 100644 index 000000000..35a058f6a --- /dev/null +++ b/content/docs/configuration/tools/calculator.mdx @@ -0,0 +1,34 @@ +--- +title: Calculator +icon: Calculator +description: Use the built-in Calculator tool in LibreChat agents +--- + +Calculator is a built-in agent tool for arithmetic and symbolic calculations. It does not require an API key or environment variable. + +## Setup + + + + +### Add Calculator to an Agent + +In LibreChat, select **Agents**, create or edit an agent, open the agent's **Tools** list, select **Calculator**, and save the agent. + + + + +### Test It + +Ask the agent to calculate something that benefits from a tool call: + +```text +Calculate 12345 * 6789 and show the result. +``` + + + + +## Troubleshooting + +If Calculator is not visible in the Agent Builder, check whether your `librechat.yaml` uses [`includedTools`](/docs/configuration/librechat_yaml/object_structure/config#includedtools) or [`filteredTools`](/docs/configuration/librechat_yaml/object_structure/config#filteredtools). diff --git a/content/docs/configuration/tools/flux.mdx b/content/docs/configuration/tools/flux.mdx index 9daee6b10..daafa17a1 100644 --- a/content/docs/configuration/tools/flux.mdx +++ b/content/docs/configuration/tools/flux.mdx @@ -10,10 +10,18 @@ Flux is a powerful image generation tool that can create high-quality images fro 1. Get your API key from [bfl.ml](https://bfl.ml) 2. Set the `FLUX_API_KEY` environment variable in your `.env` file: + ```bash FLUX_API_KEY=your_api_key_here ``` +3. Restart LibreChat and add **Flux** to an agent's **Tools** list. + +| Deployment | Command | +|------------|---------| +| Docker | `docker compose down && docker compose up -d` | +| Local | Stop the server, then run `npm run backend` again | + ## Features ### Core Capabilities diff --git a/content/docs/configuration/tools/gemini_image_gen.mdx b/content/docs/configuration/tools/gemini_image_gen.mdx index 577240e38..c0fc9884c 100644 --- a/content/docs/configuration/tools/gemini_image_gen.mdx +++ b/content/docs/configuration/tools/gemini_image_gen.mdx @@ -35,6 +35,13 @@ GOOGLE_CLOUD_LOCATION=us-central1 When no `GEMINI_API_KEY` or `GOOGLE_KEY` is configured, the tool automatically falls back to Vertex AI using the service account file. +After configuring credentials, restart LibreChat and add **Gemini Image Tools** to an agent's **Tools** list. + +| Deployment | Command | +|------------|---------| +| Docker | `docker compose down && docker compose up -d` | +| Local | Stop the server, then run `npm run backend` again | + ## Configuration Options ### Model Selection @@ -151,4 +158,3 @@ Rate limits depend on your API tier: - **Gemini API**: Check [Google AI Studio](https://aistudio.google.com/) for current limits - **Vertex AI**: Based on your Google Cloud project quotas - diff --git a/content/docs/configuration/tools/google_search.mdx b/content/docs/configuration/tools/google_search.mdx index a2694ca6a..7ac2c5fab 100644 --- a/content/docs/configuration/tools/google_search.mdx +++ b/content/docs/configuration/tools/google_search.mdx @@ -6,7 +6,7 @@ description: Set up Google Custom Search as an agent tool in LibreChat -This page covers the **Google Custom Search** tool (agent plugin). For LibreChat's built-in **Web Search** feature (Serper/SearXNG + Firecrawl + Jina), see [Web Search](/docs/features/web_search). +This page covers the **Google Custom Search** agent tool. For LibreChat's built-in **Web Search** feature (Serper/SearXNG + Firecrawl + Jina), see [Web Search](/docs/features/web_search). diff --git a/content/docs/configuration/tools/index.mdx b/content/docs/configuration/tools/index.mdx index 0f63e36a9..d81c4768f 100644 --- a/content/docs/configuration/tools/index.mdx +++ b/content/docs/configuration/tools/index.mdx @@ -1,50 +1,90 @@ --- -title: Tools and Plugins -icon: BookOpen -description: Tools and Plugins setup instructions +title: Tools +icon: Wrench +description: Configure built-in agent tools in LibreChat --- -**Note:** A new approach has been devised to revamp the handling of tools and plugins from scratch. The plan is to prioritize implementation for Assistants initially, followed by creating a new agent system that seamlessly integrates with various endpoints such as Anthropic, Google, and others. +LibreChat tools are selected from the **Agent Builder** and run when an agent decides they are useful. This section covers built-in agent tools such as image generation, search, weather, computation, and private index lookup. -## Setup Instructions: + -### Azure AI Search -- [Azure AI Search](/docs/configuration/tools/azure_ai_search) +The search tools on this page are tools you add to a specific agent. LibreChat's built-in [Web Search](/docs/features/web_search) feature is configured separately, and custom third-party tools are usually added through [MCP](/docs/features/mcp) or [Actions](/docs/features/agents#actions). -### Google Search -- [Google Search](/docs/configuration/tools/google_search) + -### OpenWeather -- [OpenWeather](/docs/configuration/tools/openweather) +## Quick Setup -### Stable Diffusion -- [Stable Diffusion](/docs/features/image_gen#3--stable-diffusion-local) + + -### Flux -- [Flux Image Generation](/docs/features/image_gen#4--flux) +### Pick the Tool -### Wolfram|Alpha -- [Wolfram|Alpha](/docs/configuration/tools/wolfram) +Choose a tool from the table below and collect any required API keys, service URLs, or index names. -### DALL-E -- You just need an OpenAI key, and it's made distinct from your main API key to make Chats but it can be the same one + + -### Zapier -- You need a Zapier account. Get your **[API key from here](https://nla.zapier.com/credentials/)** after you've made an account - - Create allowed actions - Follow step 3 in this **[Start Here guide](https://nla.zapier.com/start/)** from Zapier - - ⚠️ NOTE: zapier is known to be finicky with certain actions. I found that writing email drafts is probably the best use of it +### Add Credentials -### Browser/Scraper -- This is not to be confused with 'browsing' on chat.openai.com (which is technically a plugin suite or multiple plugins) - - This plugin uses OpenAI embeddings so an OpenAI key is necessary, similar to DALL-E, and it's made distinct from your main API key to make Chats but it can be the same one - - This plugin will simply scrape html, and will not work with dynamic Javascript pages as that would require a more involved solution - - A better solution for 'browsing' is planned but can't guarantuee when - - This plugin is best used in combination with google so it doesn't hallucinate webpages to visit +Add the required values to your `.env` file, or let users provide their own credentials from the LibreChat UI when the tool prompts for them. -### SerpAPI -- An alternative to Google search but not as performant in my opinion - - You can get an API key here: **[https://serpapi.com/dashboard](https://serpapi.com/dashboard)** - - For free tier, you are limited to 100 queries/month - - With google, you are limited to 100/day for free, which is a better deal, and any after may cost you a few pennies + + +### Restart LibreChat +Environment variable changes are loaded on restart. + +| Deployment | Command | +|------------|---------| +| Docker | `docker compose down && docker compose up -d` | +| Local | Stop the server, then run `npm run backend` again | + + + + +### Add the Tool to an Agent + +In LibreChat, select **Agents**, create or edit an agent, open the agent's **Tools** list, select the tool, and save the agent. + + + + +### Test in Chat + +Start a chat with that agent and ask for something that requires the tool, such as a search, calculation, weather report, or image. + + + + +## Current Built-In Tools + +| Tool | Use it for | Required configuration | Details | +|------|------------|------------------------|---------| +| OpenAI Image Tools | Generate and edit images with OpenAI image models | `IMAGE_GEN_OAI_API_KEY`; optional `IMAGE_GEN_OAI_MODEL` | [Image Generation](/docs/features/image_gen#1--openai-image-tools-recommended) | +| Gemini Image Tools | Generate images and edit with image context using Gemini | `GEMINI_API_KEY`, `GOOGLE_KEY`, or `GOOGLE_SERVICE_KEY_FILE`; optional `GEMINI_IMAGE_MODEL` | [Gemini Image Generation](/docs/configuration/tools/gemini_image_gen) | +| DALL-E-3 | Legacy OpenAI image generation | `DALLE3_API_KEY` or `DALLE_API_KEY` | [DALL-E](/docs/features/image_gen#3--dalle-legacy) | +| Flux | Cloud image generation and fine-tuned image models | `FLUX_API_KEY`; optional `FLUX_API_BASE_URL` | [Flux](/docs/configuration/tools/flux) | +| Stable Diffusion | Local or self-hosted image generation through Automatic1111 | `SD_WEBUI_URL` | [Stable Diffusion](/docs/configuration/tools/stable_diffusion) | +| Google Search | Google Custom Search results for an agent | `GOOGLE_SEARCH_API_KEY` and `GOOGLE_CSE_ID` | [Google Search](/docs/configuration/tools/google_search) | +| Tavily Search | Current web results optimized for agents | `TAVILY_API_KEY` | [Tavily Search](/docs/configuration/tools/tavily) | +| Traversaal | AI search results with sources | `TRAVERSAAL_API_KEY` | [Traversaal](/docs/configuration/tools/traversaal) | +| Azure AI Search | Search a private Azure AI Search index | `AZURE_AI_SEARCH_SERVICE_ENDPOINT`, `AZURE_AI_SEARCH_INDEX_NAME`, `AZURE_AI_SEARCH_API_KEY` | [Azure AI Search](/docs/configuration/tools/azure_ai_search) | +| OpenWeather | Current, forecast, historical, and daily weather data | `OPENWEATHER_API_KEY` | [OpenWeather](/docs/configuration/tools/openweather) | +| Wolfram\|Alpha | Math, computation, units, curated knowledge, and real-time data | `WOLFRAM_APP_ID` | [Wolfram\|Alpha](/docs/configuration/tools/wolfram) | +| Calculator | Basic and complex calculations | None | [Calculator](/docs/configuration/tools/calculator) | + +## Tool Availability + +Tools are identified internally by their `pluginKey` from LibreChat's `api/app/clients/tools/manifest.json`. + +Use [`filteredTools`](/docs/configuration/librechat_yaml/object_structure/config#filteredtools) to hide tools, or [`includedTools`](/docs/configuration/librechat_yaml/object_structure/config#includedtools) to allow only specific tools: + +```yaml filename="librechat.yaml" +includedTools: + - calculator + - image_gen_oai + - google +``` + +If a tool is not visible in the Agent Builder after restart, check the tool's environment variables, `includedTools`, `filteredTools`, and whether the agent's `tools` capability is enabled. diff --git a/content/docs/configuration/tools/meta.json b/content/docs/configuration/tools/meta.json index 339829a2e..6833f16c4 100644 --- a/content/docs/configuration/tools/meta.json +++ b/content/docs/configuration/tools/meta.json @@ -8,9 +8,12 @@ "stable_diffusion", "---Search---", "google_search", + "tavily", + "traversaal", "azure_ai_search", "---Other---", "openweather", - "wolfram" + "wolfram", + "calculator" ] } diff --git a/content/docs/configuration/tools/openweather.mdx b/content/docs/configuration/tools/openweather.mdx index b8c7da3fb..0ce1e125f 100644 --- a/content/docs/configuration/tools/openweather.mdx +++ b/content/docs/configuration/tools/openweather.mdx @@ -1,10 +1,10 @@ --- title: OpenWeather icon: CloudSun -description: Configure the OpenWeather plugin for LibreChat +description: Configure the OpenWeather tool for LibreChat --- -The OpenWeather plugin allows you to get weather data including current conditions, forecasts, historical data, and daily summaries using OpenWeather's One Call API 3.0. +The OpenWeather tool lets agents get weather data including current conditions, forecasts, historical data, and daily summaries using OpenWeather's One Call API 3.0. ## Prerequisites @@ -29,13 +29,20 @@ Add the following to your `.env` file: OPENWEATHER_API_KEY=your_api_key_here ``` -### Plugin Configuration +### Add the Tool to an Agent -Add the plugin to any [agent](https://www.librechat.ai/docs/features/agents) +Restart LibreChat after changing `.env`, then add **OpenWeather** to any [agent](/docs/features/agents). + +| Deployment | Command | +|------------|---------| +| Docker | `docker compose down && docker compose up -d` | +| Local | Stop the server, then run `npm run backend` again | + +In LibreChat, select **Agents**, create or edit an agent, open the agent's **Tools** list, select **OpenWeather**, and save the agent. ## Usage -The OpenWeather plugin supports the following actions: +The OpenWeather tool supports the following actions: - `current_forecast`: Get current weather and forecast data - `timestamp`: Get historical weather data for a specific date @@ -87,7 +94,7 @@ Common issues and solutions: ## Support -For issues with the plugin: +For issues with the tool: - You may open an issue at https://github.com/jmaddington/LibreChat/issues or - Check the [LibreChat Issues](https://github.com/danny-avila/LibreChat/issues) - Review OpenWeather's [API documentation](https://openweathermap.org/api/one-call-3) @@ -96,4 +103,4 @@ For issues with the plugin: ## Notes - Temperature values are automatically rounded to the nearest degree -- Default temperature unit is Celsius if not specified \ No newline at end of file +- Default temperature unit is Celsius if not specified diff --git a/content/docs/configuration/tools/stable_diffusion.mdx b/content/docs/configuration/tools/stable_diffusion.mdx index 241de2ae4..edd8a9611 100644 --- a/content/docs/configuration/tools/stable_diffusion.mdx +++ b/content/docs/configuration/tools/stable_diffusion.mdx @@ -1,10 +1,10 @@ --- title: Stable Diffusion icon: PenTool -description: How to set up and configure the Stable Diffusion plugin +description: How to set up and configure the Stable Diffusion tool --- -To use Stable Diffusion with this project, you will either need to download and install **[AUTOMATIC1111 - Stable Diffusion WebUI](https://github.com/AUTOMATIC1111/stable-diffusion-webui)** or, for a dockerized deployment, you can also use **[stable-diffusion-webui-docker](https://github.com/AbdBarho/stable-diffusion-webui-docker)** +Stable Diffusion is a built-in agent tool that connects LibreChat to an **[AUTOMATIC1111 Stable Diffusion WebUI](https://github.com/AUTOMATIC1111/stable-diffusion-webui)** API. For a dockerized Stable Diffusion deployment, you can also use **[stable-diffusion-webui-docker](https://github.com/AbdBarho/stable-diffusion-webui-docker)**. With the docker deployment you can skip step 2 and step 3, use the setup instructions from their repository instead. @@ -50,7 +50,8 @@ With the docker deployment you can skip step 2 and step 3, use the setup instruc ### 3. Run Stable Diffusion (either .sh or .bat file according to your operating system) -### 4. In the app, select the plugins endpoint, open the plugins store, and install Stable Diffusion +### 4. Set the Stable Diffusion URL in LibreChat + > **Note: The default port for Gradio is `7860`. If you changed it, please update the value accordingly.** #### Docker Install @@ -61,7 +62,13 @@ With the docker deployment you can skip step 2 and step 3, use the setup instruc - Use `SD_WEBUI_URL=http://127.0.0.1:7860` in the `.env` file - Or `http://127.0.0.1:7860` from the webui +Restart LibreChat after changing `.env`. + +| Deployment | Command | +|------------|---------| +| Docker | `docker compose down && docker compose up -d` | +| Local | Stop the server, then run `npm run backend` again | -#### Add the tool to an Agent +#### Add the Tool to an Agent -See the [Agents](/docs/features/agents#tools) section for more information on how to add the tool to an Agent. +In LibreChat, select **Agents**, create or edit an agent, open the agent's **Tools** list, select **Stable Diffusion**, and save the agent. See the [Agents](/docs/features/agents#tools) section for more information. diff --git a/content/docs/configuration/tools/tavily.mdx b/content/docs/configuration/tools/tavily.mdx new file mode 100644 index 000000000..e59c92e82 --- /dev/null +++ b/content/docs/configuration/tools/tavily.mdx @@ -0,0 +1,70 @@ +--- +title: Tavily Search +icon: Search +description: Configure Tavily Search as an agent tool in LibreChat +--- + +Tavily Search is a built-in agent tool for current web research. It returns structured search results and can optionally include answers, images, raw page content, domain filters, and recency filters. + +## Setup + + + + +### Get a Tavily API Key + +Create a Tavily account and copy your API key from [app.tavily.com](https://app.tavily.com/). + + + + +### Add the Environment Variable + +Add the key to your `.env` file: + +```bash filename=".env" +TAVILY_API_KEY=tvly-your-api-key +``` + + + + +### Restart LibreChat + +| Deployment | Command | +|------------|---------| +| Docker | `docker compose down && docker compose up -d` | +| Local | Stop the server, then run `npm run backend` again | + + + + +### Add Tavily to an Agent + +In LibreChat, select **Agents**, create or edit an agent, open the agent's **Tools** list, select **Tavily Search**, and save the agent. + + + + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `query` | Search query. Required. | +| `max_results` | Number of results to return, from 1 to 10. Defaults to 5. | +| `search_depth` | `basic` for faster results or `advanced` for higher quality results. Advanced searches count as 2 requests. | +| `include_answer` | Include Tavily's generated answer in the response. | +| `include_images` | Include image results. | +| `include_image_descriptions` | Include descriptions for returned images when images are enabled. | +| `include_raw_content` | Include raw page content in the result. | +| `include_domains` | Limit results to specific domains. | +| `exclude_domains` | Exclude specific domains. | +| `topic` | `general`, `news`, or `finance`. | +| `time_range` | Limit results to a recent period such as `day`, `week`, `month`, or `year`. | +| `days` | Number of days back to include for news searches. | + +## Notes + +- Tavily Search is an agent tool. LibreChat can also use Tavily as a [Web Search](/docs/features/web_search) provider or scraper, which is configured separately. +- Tavily requests use the global `PROXY` environment variable when it is configured. +- If the tool does not appear in the Agent Builder, confirm `TAVILY_API_KEY` is set and check [`includedTools`](/docs/configuration/librechat_yaml/object_structure/config#includedtools) or [`filteredTools`](/docs/configuration/librechat_yaml/object_structure/config#filteredtools). diff --git a/content/docs/configuration/tools/traversaal.mdx b/content/docs/configuration/tools/traversaal.mdx new file mode 100644 index 000000000..41d6db08e --- /dev/null +++ b/content/docs/configuration/tools/traversaal.mdx @@ -0,0 +1,65 @@ +--- +title: Traversaal +icon: Search +description: Configure Traversaal as an agent search tool in LibreChat +--- + +Traversaal is a built-in agent search tool that sends a natural-language query to Traversaal Ares and returns a response with source URLs when available. + +## Setup + + + + +### Get a Traversaal API Key + +Create an account and get an API key from [api.traversaal.ai](https://api.traversaal.ai/). + + + + +### Add the Environment Variable + +Add the key to your `.env` file: + +```bash filename=".env" +TRAVERSAAL_API_KEY=your-api-key +``` + + + + +### Restart LibreChat + +| Deployment | Command | +|------------|---------| +| Docker | `docker compose down && docker compose up -d` | +| Local | Stop the server, then run `npm run backend` again | + + + + +### Add Traversaal to an Agent + +In LibreChat, select **Agents**, create or edit an agent, open the agent's **Tools** list, select **Traversaal**, and save the agent. + + + + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `query` | A complete sentence describing what the agent should search for. Required. | + +## Example Prompts + +```text +Find recent reporting about open source AI coding agents. +Search for sources comparing renewable energy adoption in Europe and North America. +``` + +## Troubleshooting + +- If Traversaal returns an authentication error, confirm `TRAVERSAAL_API_KEY` is set and restart LibreChat. +- If the tool is not visible in the Agent Builder, check [`includedTools`](/docs/configuration/librechat_yaml/object_structure/config#includedtools), [`filteredTools`](/docs/configuration/librechat_yaml/object_structure/config#filteredtools), and the agent's `tools` capability. diff --git a/content/docs/configuration/tools/wolfram.mdx b/content/docs/configuration/tools/wolfram.mdx index cb25725e7..f5f013158 100644 --- a/content/docs/configuration/tools/wolfram.mdx +++ b/content/docs/configuration/tools/wolfram.mdx @@ -1,10 +1,10 @@ --- title: Wolfram|Alpha icon: Sigma -description: How to set up and configure the Wolfram Alpha plugin +description: How to set up and configure the Wolfram Alpha tool --- -An AppID must be supplied in all calls to the Wolfram|Alpha API. +The Wolfram|Alpha tool gives agents access to computation, math, curated knowledge, unit conversion, scientific data, and real-time data. An AppID must be supplied in all calls to the Wolfram|Alpha API. - Note: Wolfram API calls are limited to 100 calls/day and 2000/month for regular users. @@ -15,6 +15,21 @@ An AppID must be supplied in all calls to the Wolfram|Alpha API. - Visit the **[Developer Portal](https://developer.wolframalpha.com/portal/myapps/)** and click on `Get an AppID` - Select `LLM API` as the `API` and copy the key -#### Add the tool to an Agent +### Configure LibreChat -See the [Agents](/docs/features/agents#tools) section for more information on how to add the tool to an Agent. +Add your AppID to `.env`: + +```bash filename=".env" +WOLFRAM_APP_ID=your-app-id +``` + +Restart LibreChat after changing `.env`. + +| Deployment | Command | +|------------|---------| +| Docker | `docker compose down && docker compose up -d` | +| Local | Stop the server, then run `npm run backend` again | + +#### Add the Tool to an Agent + +In LibreChat, select **Agents**, create or edit an agent, open the agent's **Tools** list, select **Wolfram**, and save the agent. See the [Agents](/docs/features/agents#tools) section for more information. diff --git a/content/docs/features/agents.mdx b/content/docs/features/agents.mdx index 0c4ebc46c..567206d7b 100644 --- a/content/docs/features/agents.mdx +++ b/content/docs/features/agents.mdx @@ -205,15 +205,16 @@ For the type attribute, use one of: Agents can also be enhanced with various built-in tools: - **[OpenAI Image Tools](/docs/features/image_gen#1--openai-image-tools-recommended)**: Image generation & editing using **[GPT-Image-1](https://platform.openai.com/docs/models/gpt-image-1)** -- **[DALL-E-3](/docs/features/image_gen#2--dalle-legacy)**: Image generation from text descriptions -- **[Stable Diffusion](/docs/features/image_gen#3--stable-diffusion-local)** / **[Flux](/docs/features/image_gen#4--flux)**: Text-to-image generation +- **[Gemini Image Tools](/docs/configuration/tools/gemini_image_gen)**: Image generation and image-context editing using Gemini image models +- **[DALL-E-3](/docs/features/image_gen#3--dalle-legacy)**: Image generation from text descriptions +- **[Stable Diffusion](/docs/features/image_gen#4--stable-diffusion-local)** / **[Flux](/docs/features/image_gen#5--flux)**: Text-to-image generation - **[Wolfram](/docs/configuration/tools/wolfram)**: Computational and mathematical capabilities - **[OpenWeather](/docs/configuration/tools/openweather)**: Weather data retrieval - **[Google Search](/docs/configuration/tools/google_search)**: Access to web search functionality -- **Calculator**: Mathematical calculations -- **Tavily Search**: Advanced search API with diverse data source integration -- **Azure AI Search**: Information retrieval -- **Traversaal**: A robust search API for LLM Agents +- **[Calculator](/docs/configuration/tools/calculator)**: Mathematical calculations +- **[Tavily Search](/docs/configuration/tools/tavily)**: Advanced search API with diverse data source integration +- **[Azure AI Search](/docs/configuration/tools/azure_ai_search)**: Information retrieval from Azure AI Search indexes +- **[Traversaal](/docs/configuration/tools/traversaal)**: A robust search API for LLM Agents - Tools can be disabled using the [`librechat.yaml`](/docs/configuration/librechat_yaml) configuration file: - [More info](/docs/configuration/librechat_yaml/object_structure/agents#capabilities) diff --git a/content/docs/features/image_gen.mdx b/content/docs/features/image_gen.mdx index e6f02d5bc..7710e296b 100644 --- a/content/docs/features/image_gen.mdx +++ b/content/docs/features/image_gen.mdx @@ -11,16 +11,16 @@ Get image generation working in under 5 minutes with OpenAI Image Tools (recomme -### Create an Agent +### Open the Agent Builder -Go to the **Agents** panel in LibreChat and create a new agent. Give it a name like "Image Creator". +Select **Agents** from the endpoint menu, open the Agent Builder from the side panel, and create a new agent. Give it a name like "Image Creator". ### Add OpenAI Image Tools -In the agent's **Tools** list, select **OpenAI Image Tools**. This adds both image generation and image editing capabilities. +Open the agent's **Tools** list, select **OpenAI Image Tools**, and save the agent. This adds both image generation and image editing capabilities. @@ -31,6 +31,8 @@ Add the following to your `.env` file: ```bash filename=".env" IMAGE_GEN_OAI_API_KEY=sk-your-openai-api-key +# Optional; defaults to gpt-image-1 +IMAGE_GEN_OAI_MODEL=gpt-image-1 ``` @@ -48,6 +50,12 @@ Send a message like "Generate an image of a sunset over mountains" to your agent + + +Image generation is not a separate page in LibreChat. You generate or edit images by chatting with an **Agent** that has an image tool enabled. For OpenAI Image Tools, upload an image when you want an edit, or send a plain text prompt when you want a new image. + + + --- LibreChat comes with **built-in image tools** that you can add to an **[Agent](/docs/features/agents).** @@ -58,7 +66,7 @@ Each has its own look, price-point, and setup step (usually just an API key or U |------|----------|-------| | **OpenAI Image Tools** | Cutting-edge results (GPT-Image-1).
Can also ***edit*** the images you upload. | OpenAI API | | **Gemini Image Tools** | Google's latest image models with context-aware generation. | Gemini API or Vertex AI | -| **DALL·E (3 / 2)** | Legacy OpenAI Image models. | OpenAI API | +| **DALL-E-3** | Legacy OpenAI image generation. | OpenAI API | | **Stable Diffusion** | Local or self-hosted generation, endless community models. | Automatic1111 API | | **Flux** | Fast cloud renders, optional fine-tunes. | Flux API | | **MCP** | Bring-your-own-Image-Generators | MCP server with image output support | @@ -69,7 +77,7 @@ Each has its own look, price-point, and setup step (usually just an API key or U - The LLM will only get vision context from images attached to user messages, and not from generations/edits, except for immediately after generation. - See [Image Storage and Handling](#image-storage-and-handling) for more details. - MCP Server tool image outputs are supported, which may output images similarly to LC's built-in tools. - - Note: MCP servers may or may not use the correct format when outputting images. See details in the [MCP section below](#5--model-context-protocol-mcp). + - Note: MCP servers may or may not use the correct format when outputting images. See details in the [MCP section below](#6--model-context-protocol-mcp). --- @@ -83,7 +91,7 @@ Each has its own look, price-point, and setup step (usually just an API key or U - **Create** brand-new images from text prompts (no upload required). - **Image Editing**: - **Edit** or **remix** the images you just uploaded—change colours, add objects, extend the canvas, etc. -- Both use OpenAI's latest image generation model, **GPT-Image-1**, for superior instruction following, text rendering, detailed editing, real-world knowledge +- Both default to **GPT-Image-1** for instruction following, text rendering, detailed editing, and real-world knowledge. Use `IMAGE_GEN_OAI_MODEL` to choose a different OpenAI image model when your deployment supports it. - See OpenAI's [Image Generation documentation](https://platform.openai.com/docs/guides/image-generation?image-generation-model=gpt-image-1) for more details. #### Generation vs. Editing @@ -131,6 +139,7 @@ Create or reuse an OpenAI key and add to `.env`: ```bash IMAGE_GEN_OAI_API_KEY=sk-... # optional extras +IMAGE_GEN_OAI_MODEL=gpt-image-1 IMAGE_GEN_OAI_BASEURL=https://... ``` @@ -141,6 +150,7 @@ Then, add your corresponding credentials to your `.env` file: ```bash IMAGE_GEN_OAI_API_KEY=your-api-key # optional extras +IMAGE_GEN_OAI_MODEL=gpt-image-1 IMAGE_GEN_OAI_BASEURL=https://deploymentname.openai.azure.com/openai/deployments/gpt-image-1/ IMAGE_GEN_OAI_AZURE_API_VERSION=2025-04-01-preview ``` @@ -152,6 +162,9 @@ Then add "OpenAI Image Tools" to your Agent's *Tools* list. You can customize the tool descriptions and prompt guidance by setting these environment variables: ```bash +# Image Model +IMAGE_GEN_OAI_MODEL=gpt-image-1 + # Image Generation Tool Descriptions IMAGE_GEN_OAI_DESCRIPTION=... IMAGE_GEN_OAI_PROMPT_DESCRIPTION=... @@ -228,7 +241,7 @@ More details can be found in the dedicated [Gemini Image Gen guide](/docs/config ## 3 · DALL·E (legacy) -DALL·E provides high-quality image generation using OpenAI's legacy image models. +DALL·E provides legacy image generation using OpenAI's `dall-e-3` image model. ### Parameters • **prompt** – Text description of the desired image (required, up to 4000 characters) diff --git a/content/docs/meta.json b/content/docs/meta.json index e46102fc2..af15900b7 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -1,12 +1,12 @@ { "pages": [ "index", + "features", "---Deploy---", "local", "remote", "configuration", "---Learn---", - "features", "mcp_servers", "user_guides", "---Tools---", From 11186b1ce3603d5dfb3e47fa278930e318b6c5ce Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Mon, 8 Jun 2026 15:05:13 -0400 Subject: [PATCH 2/3] docs: address user feedback on setup guidance --- content/docs/configuration/index.mdx | 12 ++++++++++ .../ai_endpoints/openrouter.mdx | 22 ++++++++++++++++++ .../configuration/librechat_yaml/index.mdx | 18 +++++++++++++++ content/docs/features/agents.mdx | 11 +++++++++ content/docs/features/artifacts.mdx | 6 +++++ content/docs/index.mdx | 6 +++++ content/docs/quick_start/custom_endpoints.mdx | 16 +++++++++++++ content/docs/user_guides/index.mdx | 23 +++++++++++++++++++ 8 files changed, 114 insertions(+) diff --git a/content/docs/configuration/index.mdx b/content/docs/configuration/index.mdx index 0fbda2eca..e4c9657d4 100644 --- a/content/docs/configuration/index.mdx +++ b/content/docs/configuration/index.mdx @@ -6,6 +6,18 @@ description: How LibreChat's configuration files work together and how to apply LibreChat uses four main configuration files. Each controls a different aspect of the application -- from environment variables to custom AI endpoints to Docker service overrides. +## Common Change Workflow + +Most configuration changes follow the same pattern: + +1. Edit `.env` for secrets, API keys, and server-level feature flags. +2. Edit `librechat.yaml` for custom endpoints, model specs, interface settings, MCP servers, agents, and advanced app behavior. +3. For Docker, make sure `librechat.yaml` is mounted through `docker-compose.override.yml` before expecting LibreChat to read it. +4. Restart LibreChat after every configuration change. +5. Check the API logs if the change does not appear in the UI. + +For example, to enable OpenRouter you add `OPENROUTER_KEY` to `.env`, add an OpenRouter endpoint in `librechat.yaml`, make sure Docker mounts `librechat.yaml`, restart, then select OpenRouter from the endpoint selector. + ## Configuration Files diff --git a/content/docs/configuration/librechat_yaml/ai_endpoints/openrouter.mdx b/content/docs/configuration/librechat_yaml/ai_endpoints/openrouter.mdx index 6dfd2d700..57519b812 100644 --- a/content/docs/configuration/librechat_yaml/ai_endpoints/openrouter.mdx +++ b/content/docs/configuration/librechat_yaml/ai_endpoints/openrouter.mdx @@ -115,6 +115,28 @@ docker compose logs api | grep -i "error\|openrouter" +## Troubleshooting + +### OpenRouter Does Not Appear in the Model Selector + +Check these items in order: + +1. `OPENROUTER_KEY` is set in `.env`. +2. `librechat.yaml` contains the OpenRouter entry under `endpoints.custom`. +3. Docker users have mounted `librechat.yaml` in `docker-compose.override.yml`. +4. LibreChat was restarted after editing both files. +5. The API logs do not show YAML validation errors. + +```bash +docker compose logs api +``` + +If the logs mention a missing environment variable, check that the variable name in `.env` matches the variable referenced in `librechat.yaml`. For this guide, that means `apiKey: "${OPENROUTER_KEY}"` in `librechat.yaml` and `OPENROUTER_KEY=...` in `.env`. + +### OpenRouter Returns 402 Payment Required + +A `402 Payment Required` response comes from OpenRouter, not LibreChat. Add credits or choose a free/available model in OpenRouter, then retry the same endpoint in LibreChat. + ## Customization ### Using user_provided API Key diff --git a/content/docs/configuration/librechat_yaml/index.mdx b/content/docs/configuration/librechat_yaml/index.mdx index 09273c713..17315a7fa 100644 --- a/content/docs/configuration/librechat_yaml/index.mdx +++ b/content/docs/configuration/librechat_yaml/index.mdx @@ -10,6 +10,12 @@ The `librechat.yaml` file is LibreChat's main configuration file for custom AI e Follow the steps below to create the file, mount it for your deployment type, and verify it works. + + +For Docker installs, editing `librechat.yaml` is not enough. The file must exist in the project root, be mounted into the API container, and LibreChat must be restarted before changes appear in the UI. + + + ## Setup @@ -172,6 +178,18 @@ For detailed field-level documentation, see the reference pages below. ## Troubleshooting +### Change Does Not Show in LibreChat + +If you edited `librechat.yaml` and nothing changed in the UI: + +1. Confirm the file is in the LibreChat project root unless you set `CONFIG_PATH`. +2. For Docker, confirm the file is mounted in `docker-compose.override.yml`. +3. Restart LibreChat with `docker compose down && docker compose up -d`. +4. Check the API logs with `docker compose logs api`. +5. Validate the file with the [YAML Validator](/toolkit/yaml_checker). + +Custom endpoints such as OpenRouter only appear after all three pieces are correct: `.env` contains the key, `librechat.yaml` defines the endpoint, and Docker can read the mounted config file. + ### Configuration Validation diff --git a/content/docs/features/agents.mdx b/content/docs/features/agents.mdx index 567206d7b..fb937d92f 100644 --- a/content/docs/features/agents.mdx +++ b/content/docs/features/agents.mdx @@ -216,6 +216,17 @@ Agents can also be enhanced with various built-in tools: - **[Azure AI Search](/docs/configuration/tools/azure_ai_search)**: Information retrieval from Azure AI Search indexes - **[Traversaal](/docs/configuration/tools/traversaal)**: A robust search API for LLM Agents +#### Create an Agent with Image Tools + +1. Add the image tool credentials to `.env`, such as `IMAGE_GEN_OAI_API_KEY` for OpenAI Image Tools. +2. Restart LibreChat so the new environment variables are loaded. +3. Select **Agents** from the endpoint menu. +4. Open the Agent Builder from the side panel and create or edit an agent. +5. Open the agent's **Tools** list, select **OpenAI Image Tools**, **Gemini Image Tools**, **DALL-E-3**, **Stable Diffusion**, or **Flux**, then save the agent. +6. Start a chat with that agent and ask it to generate or edit an image. + +For the full image setup guide, including model variables such as `IMAGE_GEN_OAI_MODEL`, see [Image Generation & Editing](/docs/features/image_gen). + - Tools can be disabled using the [`librechat.yaml`](/docs/configuration/librechat_yaml) configuration file: - [More info](/docs/configuration/librechat_yaml/object_structure/agents#capabilities) diff --git a/content/docs/features/artifacts.mdx b/content/docs/features/artifacts.mdx index e3d3b059f..48dcf8581 100644 --- a/content/docs/features/artifacts.mdx +++ b/content/docs/features/artifacts.mdx @@ -11,6 +11,12 @@ description: Discover LibreChat's revolutionary Artifacts feature for instant cr > **Note:** The preferred way to use artifacts is now through the [Agents feature](/docs/features/agents#artifacts), which allows for more granular control by enabling/disabling artifacts at the agent level rather than app-wide. + + +Artifacts are LibreChat's canvas-like workspace for generated HTML, React components, Mermaid diagrams, and other interactive outputs. To use it, create or edit an [Agent](/docs/features/agents), enable the **Artifacts** capability, save the agent, then ask it to create an app, diagram, or UI. The generated artifact opens in the artifact panel beside the chat. + + +
diff --git a/content/docs/index.mdx b/content/docs/index.mdx index 038c8847c..74a9d7954 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -5,3 +5,9 @@ description: Choose your setup method and get LibreChat running in minutes. --- + + + +LibreChat is a self-hosted web application, not a native Windows app or Linux AppImage. On Windows, use [Docker Desktop](/docs/local/docker) for the simplest local setup. For Linux desktops or servers, use [Docker](/docs/local/docker), [npm](/docs/local/npm), or a [remote hosting guide](/docs/remote). + + diff --git a/content/docs/quick_start/custom_endpoints.mdx b/content/docs/quick_start/custom_endpoints.mdx index 18b5bb5a8..0898024fc 100644 --- a/content/docs/quick_start/custom_endpoints.mdx +++ b/content/docs/quick_start/custom_endpoints.mdx @@ -135,6 +135,22 @@ Common issues: YAML syntax errors, missing env vars, or `librechat.yaml` not mou +### OpenRouter Still Does Not Show Up + +For OpenRouter specifically, verify the three-file chain: + +1. `.env` has `OPENROUTER_KEY=...` +2. `librechat.yaml` has `apiKey: "${OPENROUTER_KEY}"` under the OpenRouter custom endpoint +3. Docker users mounted `librechat.yaml` in `docker-compose.override.yml` + +Then restart with: + +```bash +docker compose down && docker compose up -d +``` + +If the endpoint appears but returns `402 Payment Required`, the request reached OpenRouter successfully and the issue is usually account credits, billing, or model availability on OpenRouter. + ## Next Steps diff --git a/content/docs/user_guides/index.mdx b/content/docs/user_guides/index.mdx index 58bf8ba18..42b88ab66 100644 --- a/content/docs/user_guides/index.mdx +++ b/content/docs/user_guides/index.mdx @@ -6,6 +6,29 @@ description: Guides and tutorials for LibreChat features Whether you are a new user or exploring advanced features, these guides help you get the most out of LibreChat. +## Common Tasks + + + + Learn what endpoints, models, presets, and providers mean in the chat UI + + + Build a custom assistant with instructions, files, tools, and capabilities + + + Create an agent with image tools and generate or edit images from chat + + + Enable web search for current information and source-backed answers + + + Use RAG and file search to ask questions about uploaded documents + + + Add external services through MCP servers and agent tools + + + ## Guides From 745bbaddfca180198bb314ebae4978457e46f145 Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Mon, 8 Jun 2026 15:07:41 -0400 Subject: [PATCH 3/3] docs: remove misleading artifacts canvas wording --- content/docs/features/artifacts.mdx | 6 ------ 1 file changed, 6 deletions(-) diff --git a/content/docs/features/artifacts.mdx b/content/docs/features/artifacts.mdx index 48dcf8581..e3d3b059f 100644 --- a/content/docs/features/artifacts.mdx +++ b/content/docs/features/artifacts.mdx @@ -11,12 +11,6 @@ description: Discover LibreChat's revolutionary Artifacts feature for instant cr > **Note:** The preferred way to use artifacts is now through the [Agents feature](/docs/features/agents#artifacts), which allows for more granular control by enabling/disabling artifacts at the agent level rather than app-wide. - - -Artifacts are LibreChat's canvas-like workspace for generated HTML, React components, Mermaid diagrams, and other interactive outputs. To use it, create or edit an [Agent](/docs/features/agents), enable the **Artifacts** capability, save the agent, then ask it to create an app, diagram, or UI. The generated artifact opens in the artifact panel beside the chat. - - -