Guide: How to Run Gemini in OpenBB Workspace (Local Setup)

Prerequisites

• Python 3.10 or 3.11 (Strictly required; 3.12+ is incompatible).
• Google AI Studio API Key (Free tier works).
• Conda or a virtual environment manager.

1. Architecture Overview

Because OpenBB Agents are hardcoded for OpenAI’s SDK, we cannot connect Gemini directly. We use a “Bridge” architecture:

OpenBB Workspace → Local Agent Server (Port 8095) → LiteLLM Bridge (Port 4000) → Google Gemini API

2. Environment Setup (The “Bridge”)

First, we set up LiteLLM, a tool that translates OpenAI HTTP requests into Google Gemini requests.

1. Install LiteLLM:
   Bash
   pip install litellm
   
2. Run the Bridge:
   Open a dedicated terminal window (keep this running) and start the proxy. We use the Flash model because it supports the large context windows required for analyzing financial datasets.
   Bash
   # Replace with your actual model name if different
   export GEMINI_API_KEY=your_google_key_here
   litellm –model gemini/gemini-latest-flash –port 4000
   
   Result: You now have an “OpenAI-compatible” server running at http://127.0.0.1:4000.

3. Agent Installation (The “Brain”)

The official openbb-agents package on PyPI is often outdated. We must install the agent server from the source to avoid dependency conflicts.

1. Create a Clean Environment:
   Bash
   conda create -n bb-agents python=3.11 -y
   conda activate bb-agents
   
2. Install the Core Library (Editable Mode):
   Clone the library repository and install it so Python can find the base modules.
   Bash
   git clone https://github.com/OpenBB-finance/openbb-agents.git
   cd openbb-agents
   pip install -e . (there are some dependencies to be fixed, it will want pydantic = “==2.7.1” and you need to update it under [home_dir]/OpenBB/openbb-agents/pyproject.toml to pydantic = “>=2.7.1”)
   
3. Get the Runnable Examples:
   Clone the secondary repository that contains the actual server implementations.
   Bash
   cd .. # Go back to your root folder
   git clone https://github.com/OpenBB-finance/agents-for-openbb.git
   cd agents-for-openbb
   

4. Configuration & Launch

We will run the “Vanilla Agent” (Agent #30), which can read widgets from your dashboard. We must configure it to talk to our local Bridge (Port 4000) instead of OpenAI servers.

1. Navigate to the Agent:
   Bash
   cd 30-vanilla-agent-raw-widget-data
   
2. Install Dependencies:
   Bash
   pip install langchain-openai fastapi uvicorn python-dotenv
   
3. Launch with Redirection:
   Run this command block to inject the configuration and start the server.

• OPENAI_BASE_URL: Points the agent to our local LiteLLM bridge.
• OPENAI_API_KEY: A dummy key (required to pass validation checks).

Bash
export OPENAI_BASE_URL=”http://127.0.0.1:4000″
export OPENAI_API_KEY=”sk-fake-key”

uvicorn main:app –host 127.0.0.1 –port 8095 –reload
Success Indicator: You will see Uvicorn running on http://127.0.0.1:8095.

---

5. Connecting to OpenBB

1. Open OpenBB Workspace (Web or Desktop).
2. Open the Copilot Menu (Sidebar).
3. Click (+) to Add Copilot.
4. Enter the URL: http://127.0.0.1:8095.
5. Click Add.

Verification: You should see a green indicator next to “Vanilla Agent.”

6. How to Use It

The Vanilla Agent does not have internet access; it relies on context.

1. Add a widget to your dashboard (e.g., Stock Price for AAPL).
2. Click the @ (Add to Chat) button on the widget header.
3. Ask the chat: “Summarize the price trend in this widget.”

Result: The agent retrieves the JSON data from the widget, sends it to Gemini (via LiteLLM), and returns the analysis.