Skip to main content

Open Source Agent

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.

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.

How it fits with Workspace​

Agent Rita runs as an HTTP service that implements the Workspace agent contract:

  • GET /agents.json returns the agent metadata, available models, and supported Workspace features.
  • POST /v1/query receives chat messages, dashboard context, widgets, and available MCP tools, then streams Server-Sent Events (SSE) back to Workspace.

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.

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.

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.

Run locally​

Prerequisites:

  • Bun installed locally.
  • OpenBB Workspace available in your browser.
  • At least one model provider configured. Agent Rita supports OpenAI, OpenRouter, Groq, and Ollama.

Clone the repository and install dependencies:

git clone https://github.com/OpenBB-finance/agent-rita.git
cd agent-rita
bun install

Set a model provider. For example, with OpenAI:

export OPENAI_API_KEY=sk-...
export DEFAULT_MODEL=openai:gpt-4o

For OpenRouter:

export OPENROUTER_API_KEY=sk-or-...
export DEFAULT_MODEL=openrouter:openai/gpt-oss-20b

For a local Ollama model:

ollama pull gpt-oss:20b
export DEFAULT_MODEL=ollama:gpt-oss:20b

Start the agent:

bun run dev:agent

By default, the agent listens on:

http://localhost:7777

To run the agent and the companion MCP server together:

bun run dev:all

To run only the companion MCP server:

bun run dev:mcp

By default, the companion MCP server listens on:

http://localhost:8787/mcp

Connect it to Workspace​

Add Agent Rita as a custom agent from the Workspace chat agent selector:

  1. Open Workspace.
  2. Open the chat agent menu.
  3. Add a custom agent with this base URL:
http://localhost:7777

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.

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.

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.

Configuration​

Common environment variables:

VariableUsed byDescription
OPENAI_API_KEYAgent, companion MCP serverEnables OpenAI chat models. Also powers document RAG embeddings for query_documents and list_documents.
OPENROUTER_API_KEYAgentEnables OpenRouter models.
GROQ_API_KEYAgentEnables Groq models.
OLLAMA_BASE_URLAgentSets the Ollama API URL. Defaults to http://localhost:11434/api.
DEFAULT_MODELAgentSelects the default model shown in agents.json.
PORTAgentSets the agent port. Defaults to 7777.
MCP_PORTCompanion MCP serverSets the companion MCP server port. Defaults to 8787.
TAVILY_API_KEYCompanion MCP serverEnables web_search.
DAYTONA_API_KEYCompanion MCP serverEnables execute_code.

What to customize​

For Workspace-specific behavior, start with the agent service:

  • src/routes/agents.ts controls the agents.json response.
  • src/routes/query.ts receives Workspace requests and chooses the model.
  • src/routes/generate/ contains the single-shot generation routes for dashboard titles, chat titles, prompt enhancement, widget metadata, and code generation.
  • src/agent/ contains the main agent loop, prompt builder, context handling, round-trip handling, and tool registration.
  • src/agent/tools/ contains local tools for widget search, widget data, skills, SQL, generated artifacts, and native Workspace bridge actions.
  • src/mcp/ maps Workspace-provided MCP tool descriptors into model-callable tools and handles returned MCP citations, artifacts, and typed results.
  • mcp-server/ contains the optional companion MCP server for web search, web-page fetch, Mermaid rendering, Python execution, and document RAG.

If you are building a smaller custom agent from scratch, see Agents Integration, OpenBB AI SDK, and the agents.json reference.

On this page