|
| 1 | +--- |
| 2 | +title: Open Source Agent |
| 3 | +sidebar_position: 8 |
| 4 | +description: Run and customize Agent Rita, OpenBB's open source reference agent for Workspace. |
| 5 | +keywords: |
| 6 | +- Agent Rita |
| 7 | +- open source agent |
| 8 | +- custom agents |
| 9 | +- OpenBB Workspace |
| 10 | +- MCP |
| 11 | +- agents.json |
| 12 | +--- |
| 13 | + |
| 14 | +import HeadTitle from '@site/src/components/General/HeadTitle.tsx'; |
| 15 | + |
| 16 | +<HeadTitle title="Open Source Agent | OpenBB Workspace Docs" /> |
| 17 | + |
| 18 | +Agent Rita is OpenBB's open source reference agent for Workspace. It shows how to build a financial agent that can read dashboard context, fetch widget data, run SQL over loaded data, and stream answers back through the Workspace chat interface. |
| 19 | + |
| 20 | +Use it when you want a working agent to run, inspect, and fork instead of starting from the lower-level agent contract. The source code is available in the [Agent Rita repository](https://github.com/OpenBB-finance/agent-rita). |
| 21 | + |
| 22 | +## How it fits with Workspace |
| 23 | + |
| 24 | +Agent Rita runs as an HTTP service that implements the Workspace agent contract: |
| 25 | + |
| 26 | +- `GET /agents.json` returns the agent metadata, available models, and supported Workspace features. |
| 27 | +- `POST /v1/query` receives chat messages, dashboard context, widgets, and available MCP tools, then streams Server-Sent Events (SSE) back to Workspace. |
| 28 | + |
| 29 | +If MCP servers are configured in Workspace, Agent Rita can use their tools. Workspace owns those MCP connections, sends the available tool descriptors in each request, executes selected tools, and forwards results back to the agent through the normal `/v1/query` flow. |
| 30 | + |
| 31 | +This keeps the agent focused on Workspace-specific state: widget discovery, widget data round-trips, SQL over loaded data, citations, generated artifacts, and native Workspace actions. |
| 32 | + |
| 33 | +## Run locally |
| 34 | + |
| 35 | +Prerequisites: |
| 36 | + |
| 37 | +- [Bun](https://bun.sh/) installed locally. |
| 38 | +- OpenBB Workspace available in your browser. |
| 39 | +- At least one model provider configured. Agent Rita supports OpenAI, OpenRouter, Groq, and Ollama. |
| 40 | + |
| 41 | +Clone the repository and install dependencies: |
| 42 | + |
| 43 | +```bash |
| 44 | +git clone https://github.com/OpenBB-finance/agent-rita.git |
| 45 | +cd agent-rita |
| 46 | +bun install |
| 47 | +``` |
| 48 | + |
| 49 | +Set a model provider. For example, with OpenAI: |
| 50 | + |
| 51 | +```bash |
| 52 | +export OPENAI_API_KEY=sk-... |
| 53 | +export DEFAULT_MODEL=openai:gpt-4o |
| 54 | +``` |
| 55 | + |
| 56 | +For OpenRouter: |
| 57 | + |
| 58 | +```bash |
| 59 | +export OPENROUTER_API_KEY=sk-or-... |
| 60 | +export DEFAULT_MODEL=openrouter:openai/gpt-oss-20b |
| 61 | +``` |
| 62 | + |
| 63 | +For a local Ollama model: |
| 64 | + |
| 65 | +```bash |
| 66 | +ollama pull gpt-oss:20b |
| 67 | +export DEFAULT_MODEL=ollama:gpt-oss:20b |
| 68 | +``` |
| 69 | + |
| 70 | +Start the agent: |
| 71 | + |
| 72 | +```bash |
| 73 | +bun run dev |
| 74 | +``` |
| 75 | + |
| 76 | +By default, the agent listens on: |
| 77 | + |
| 78 | +```text |
| 79 | +http://localhost:7777 |
| 80 | +``` |
| 81 | + |
| 82 | +## Connect it to Workspace |
| 83 | + |
| 84 | +Add Agent Rita as a custom agent from the Workspace chat agent selector: |
| 85 | + |
| 86 | +1. Open Workspace. |
| 87 | +2. Open the chat agent menu. |
| 88 | +3. Add a custom agent with this base URL: |
| 89 | + |
| 90 | +```text |
| 91 | +http://localhost:7777 |
| 92 | +``` |
| 93 | + |
| 94 | +Workspace fetches `http://localhost:7777/agents.json` and uses the advertised `/v1/query` endpoint for chat requests. If you have MCP servers configured in Workspace, their tools are included in requests to Agent Rita and can be used by the agent when relevant. |
| 95 | + |
| 96 | +If Workspace runs in Docker, on another machine, or behind a remote URL, replace `localhost` with a host that the browser can reach. |
| 97 | + |
| 98 | +## Configuration |
| 99 | + |
| 100 | +Common environment variables: |
| 101 | + |
| 102 | +| Variable | Used by | Description | |
| 103 | +| --- | --- | --- | |
| 104 | +| `OPENAI_API_KEY` | Agent | Enables OpenAI chat models. | |
| 105 | +| `OPENROUTER_API_KEY` | Agent | Enables OpenRouter models. | |
| 106 | +| `GROQ_API_KEY` | Agent | Enables Groq models. | |
| 107 | +| `OLLAMA_BASE_URL` | Agent | Sets the Ollama API URL. Defaults to `http://localhost:11434/api`. | |
| 108 | +| `DEFAULT_MODEL` | Agent | Selects the default model shown in `agents.json`. | |
| 109 | +| `PORT` | Agent | Sets the agent port. Defaults to `7777`. | |
| 110 | + |
| 111 | +## What to customize |
| 112 | + |
| 113 | +For Workspace-specific behavior, start with the agent service: |
| 114 | + |
| 115 | +- `src/routes/agents.ts` controls the `agents.json` response. |
| 116 | +- `src/routes/query.ts` receives Workspace requests and chooses the model. |
| 117 | +- `src/agent/` contains the main agent loop, prompt builder, context handling, round-trip handling, and tool registration. |
| 118 | +- `src/agent/tools/` contains local tools for widget search, widget data, skills, SQL, generated artifacts, and native Workspace bridge actions. |
| 119 | + |
| 120 | +If you are building a smaller custom agent from scratch, see [Agents Integration](/workspace/developers/agents-integration), [OpenBB AI SDK](/workspace/developers/openbb-ai-sdk), and the [`agents.json` reference](/workspace/developers/json-specs/agents-json-reference). |
0 commit comments