|
| 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 | +Agent Rita also exposes auxiliary generation routes for Workspace UI tasks, such as `POST /v1/generate/dashboard/title` for dashboard names and `POST /v1/generate/chat/title` for chat titles. These routes use the configured model provider for single-shot generation outside the main chat stream. |
| 30 | + |
| 31 | +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. |
| 32 | + |
| 33 | +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. The Agent Rita repository includes an optional companion MCP server in `mcp-server/` for web search, web-page fetch, Python execution, Mermaid rendering, and document RAG. |
| 34 | + |
| 35 | +## Run locally |
| 36 | + |
| 37 | +Prerequisites: |
| 38 | + |
| 39 | +- [Bun](https://bun.sh/) installed locally. |
| 40 | +- OpenBB Workspace available in your browser. |
| 41 | +- At least one model provider configured. Agent Rita supports OpenAI, OpenRouter, Groq, and Ollama. |
| 42 | + |
| 43 | +Clone the repository and install dependencies: |
| 44 | + |
| 45 | +```bash |
| 46 | +git clone https://github.com/OpenBB-finance/agent-rita.git |
| 47 | +cd agent-rita |
| 48 | +bun install |
| 49 | +``` |
| 50 | + |
| 51 | +Set a model provider. For example, with OpenAI: |
| 52 | + |
| 53 | +```bash |
| 54 | +export OPENAI_API_KEY=sk-... |
| 55 | +export DEFAULT_MODEL=openai:gpt-4o |
| 56 | +``` |
| 57 | + |
| 58 | +For OpenRouter: |
| 59 | + |
| 60 | +```bash |
| 61 | +export OPENROUTER_API_KEY=sk-or-... |
| 62 | +export DEFAULT_MODEL=openrouter:openai/gpt-oss-20b |
| 63 | +``` |
| 64 | + |
| 65 | +For a local Ollama model: |
| 66 | + |
| 67 | +```bash |
| 68 | +ollama pull gpt-oss:20b |
| 69 | +export DEFAULT_MODEL=ollama:gpt-oss:20b |
| 70 | +``` |
| 71 | + |
| 72 | +Start the agent: |
| 73 | + |
| 74 | +```bash |
| 75 | +bun run dev:agent |
| 76 | +``` |
| 77 | + |
| 78 | +By default, the agent listens on: |
| 79 | + |
| 80 | +```text |
| 81 | +http://localhost:7777 |
| 82 | +``` |
| 83 | + |
| 84 | +To run the agent and the companion MCP server together: |
| 85 | + |
| 86 | +```bash |
| 87 | +bun run dev:all |
| 88 | +``` |
| 89 | + |
| 90 | +To run only the companion MCP server: |
| 91 | + |
| 92 | +```bash |
| 93 | +bun run dev:mcp |
| 94 | +``` |
| 95 | + |
| 96 | +By default, the companion MCP server listens on: |
| 97 | + |
| 98 | +```text |
| 99 | +http://localhost:8787/mcp |
| 100 | +``` |
| 101 | + |
| 102 | +## Connect it to Workspace |
| 103 | + |
| 104 | +Add Agent Rita as a custom agent from the Workspace chat agent selector: |
| 105 | + |
| 106 | +1. Open Workspace. |
| 107 | +2. Open the chat agent menu. |
| 108 | +3. Add a custom agent with this base URL: |
| 109 | + |
| 110 | +```text |
| 111 | +http://localhost:7777 |
| 112 | +``` |
| 113 | + |
| 114 | +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. |
| 115 | + |
| 116 | +To use the companion MCP tools, add `http://localhost:8787/mcp` as an MCP server in Workspace. Workspace will include those tool descriptors in Agent Rita requests. |
| 117 | + |
| 118 | +If Agent Rita or its companion MCP server runs in Docker, on another machine, or behind a remote URL, replace `localhost` with a host that the browser can reach. |
| 119 | + |
| 120 | +## Configuration |
| 121 | + |
| 122 | +Common environment variables: |
| 123 | + |
| 124 | +| Variable | Used by | Description | |
| 125 | +| --- | --- | --- | |
| 126 | +| `OPENAI_API_KEY` | Agent, companion MCP server | Enables OpenAI chat models. Also powers document RAG embeddings for `query_documents` and `list_documents`. | |
| 127 | +| `OPENROUTER_API_KEY` | Agent | Enables OpenRouter models. | |
| 128 | +| `GROQ_API_KEY` | Agent | Enables Groq models. | |
| 129 | +| `OLLAMA_BASE_URL` | Agent | Sets the Ollama API URL. Defaults to `http://localhost:11434/api`. | |
| 130 | +| `DEFAULT_MODEL` | Agent | Selects the default model shown in `agents.json`. | |
| 131 | +| `PORT` | Agent | Sets the agent port. Defaults to `7777`. | |
| 132 | +| `MCP_PORT` | Companion MCP server | Sets the companion MCP server port. Defaults to `8787`. | |
| 133 | +| `TAVILY_API_KEY` | Companion MCP server | Enables `web_search`. | |
| 134 | +| `DAYTONA_API_KEY` | Companion MCP server | Enables `execute_code`. | |
| 135 | + |
| 136 | +## What to customize |
| 137 | + |
| 138 | +For Workspace-specific behavior, start with the agent service: |
| 139 | + |
| 140 | +- `src/routes/agents.ts` controls the `agents.json` response. |
| 141 | +- `src/routes/query.ts` receives Workspace requests and chooses the model. |
| 142 | +- `src/routes/generate/` contains the single-shot generation routes for dashboard titles, chat titles, prompt enhancement, widget metadata, and code generation. |
| 143 | +- `src/agent/` contains the main agent loop, prompt builder, context handling, round-trip handling, and tool registration. |
| 144 | +- `src/agent/tools/` contains local tools for widget search, widget data, skills, SQL, generated artifacts, and native Workspace bridge actions. |
| 145 | +- `src/mcp/` maps Workspace-provided MCP tool descriptors into model-callable tools and handles returned MCP citations, artifacts, and typed results. |
| 146 | +- `mcp-server/` contains the optional companion MCP server for web search, web-page fetch, Mermaid rendering, Python execution, and document RAG. |
| 147 | + |
| 148 | +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