Guest post by [Magnus Samuelsen](https://www.linkedin.com/in/magnus-samuelsen), Open Source Contributor and AI Engineer at Jyske Bank --- ## Pydantic AI Meets OpenBB Workspace Right now, OpenBB Workspace users can use the built-in Copilot with OpenAI, or build an integration from scratch. The OpenBB AI SDK gives you the protocol, but you're still left wiring up LLM calls, tool orchestration, and streaming events. This is where [openbb-pydantic-ai](https://github.com/MagnusS0/openbb-pydantic-ai) comes in. I built this library to handle all of that for you. It's a bridge that lets you write Pydantic AI agents that speak native OpenBB. It translates `QueryRequest` payloads into Pydantic AI runs and streams native OpenBB events back to the client, so you can focus on your agent's logic, not the integration plumbing. This post will walk you through the architecture of the adapter that makes this possible, the key technical challenges I solved, and how you can get your own custom agent running in minutes. ### The Challenge: Not Just a Chatbot Integrating an AI agent into OpenBB Workspace is more complex than connecting to a chat interface. The Workspace is a dynamic environment where users and AI interact with data widgets, visualizations, and complex analysis dashboards. An effective agent must: - **"See" the Workspace**: Understand the current state of the Workspace, including available widgets, data sources, and user interactions. - **Access Remote Resources**: Fetch data from widgets that exist on the client's browser and call external tools from MCP Servers, running locally on your machine or connected through the OpenBB Workspace via [MCP](https://openbb.co/blog/openbb-the-interface-that-makes-mcp-work-for-financial-workflows). - **Stream Rich Events**: Stream reasoning steps, tool use, artifacts like tables and charts, and provide citations that the Workspace UI can render appropriately. ## The Solution: A UI Event Stream Adapter Fortunately, Pydantic AI has a flexible adapter system exactly for this type of job. It's `UIAdapter` and `UIEventStream` abstract classes are designed for translating between agent events and different UI protocols. By implementing `OpenBBAIAdapter` and `OpenBBAIEventStream`, we can map OpenBB's `QueryRequest` payloads into Pydantic AI event streams, and vice versa. As mentioned earlier, though, integration with OpenBB Workspace is more than just event translation, so there are some extra features in addition to basic request handling. ### Workspace Context Injection The first challenge is making the agent aware of the user's Workspace. The adapter extracts Workspace context (available widgets, URLs, defaults) from the `QueryRequest`, builds an `OpenBBDeps` dependency object, and injects it into the agent run as `RunContext`. This context updates the system prompt in the Pydantic AI message stack, giving the agent the necessary awareness to make informed decisions.

### The Deferred Call Handshake Next, we need to enable the agent to access client-side widget data. For this we build an `ExternalToolset` on the fly based on the widgets present in the `OpenBBDeps` object. We expose *all* available widgets as function tools to the agent. In addition, we build a separate toolset for MCP tools that are passed in the `tools` field of the `QueryRequest`. When an agent needs widget data, we can't block the server waiting for the browser. Instead, we use a deferred execution pattern: 1. **Agent requests data**: The agent calls a tool, which raises `CallDeferred` and ends the run with a `DeferredToolRequests` payload 2. **Connection closes**: The adapter emits a final `get_widget_data` SSE event containing the widget IDs and closes the stream. We include the `tool_call_id` in `extra_state.tool_calls`, a pass-through object the frontend will return unchanged 3. **Frontend executes**: The browser fetches the requested widget data or MCP tool results 4. **New request**: The frontend sends a fresh `POST /query` request with the tool results and the original `extra_state` attached 5. **Agent resumes**: It extracts `tool_call_id` values from `extra_state.tool_calls` to match each result back to its corresponding tool call, rebuilds the proper `ToolReturnPart` messages, and injects them into a new agent run to continue streaming This explicit handshake keeps the server stateless, with no long-lived connections or session storage required, while giving the agent real-time access to client-side data. Each widget call also generates a citation, so users can track where data comes from. | Widget Type | Agent Can Parse | Status | |-------------|-----------------|--------| | Tables, JSON | Yes | Full support | | Charts, Text | Yes | Full support | | PDFs, Images | No | Tool available; agent receives raw bytes but cannot yet process | | Custom widgets | Partial | Depends on output schema | ### Server-Side Visualization Tools Not everything needs a round trip to the client. I also include some visualization tools, `openbb_create_chart` and `openbb_create_table`, that run as normal tools on the server side. When the agent uses this, it produces an OpenBB-ready artifact, so you can stream charts and tables correctly formatted for the Workspace UI without any extra effort. If you instruct the agent to use placeholders (e.g. {{place_chart_here}}) in its response, the adapter will replace these with the correct artifact references automatically. If not they are emitted at the end of the run. By using Pydantic AI's `ToolReturn` object, we can send the heavy chart configuration as a side-channel artifact to the UI, while returning a simple "Chart created successfully" message to the agent. This is an attempt at keeping the agent's context window clean and focused on the conversation.

Finally, the adapter translates every remaining Pydantic AI event into OpenBB SSE events. Text chunks are streamed as `MessageChunkSSE`, reasoning steps (including Thinking tokens) are grouped under a "Step-by-step reasoning" dropdown passed as `StatusUpdateSSE`, and any tool invocation that stays on the server is passed as details in a `StatusUpdateSSE` to the user so they can observe a complex, multi-tool workflow in real time. Tables and charts (whether produced by the visualization helpers or another tool) are emitted as `MessageArtifactSSE` events with the correct rendering parameters, and citations are buffered and emitted at the end of the run. The end result is that you can build a fully-featured AI agent for OpenBB Workspace using Pydantic AI's high-level abstractions, while still taking advantage of the Workspace's dynamic environment and rich UI capabilities. Because the adapter handles all the translation and streaming logic, you can focus on designing your agent's behavior, tools, and prompts without worrying about the underlying protocol details. In practice, this means you only need a single line of code to turn any Pydantic AI agent into an OpenBB Workspace agent: ``` OpenBBAIAdapter.dispatch_request(request, agent=agent) ``` Simply call `dispatch_request` with the incoming `QueryRequest` and your Pydantic AI `agent` instance, and the adapter takes care of the rest. (Full example below.) ## What Does This Unlock? By bridging Pydantic AI with OpenBB Workspace, you can now take full control over the AI agent's behavior, tools, and prompts while seamlessly integrating with the user's workspace environment. This means using any model provider supported by Pydantic AI, custom tools for analysis, and optimized prompts for your specific use case. For example: - You could build an agent that focuses on a different domain than finance. Perhaps you want to analyze sports statistics or personal health data, all while leveraging the powerful Workspace UI for visualizations and interactivity. - You have trained a custom model that you run locally or on a private server, and you want to use that model to power your agent in the OpenBB Workspace. - You build custom agent workflows that follow a specific logic or sequence of tool calls tailored to your use case. Whether you have a specific analysis workflow in mind or want to experiment with different model providers and prompt strategies, this adapter gets you there faster. And if you build something useful, share it with the community! ## Bringing It All Together: A Complete Example Here's a complete example of how to set up a custom Pydantic AI agent using the `openbb-pydantic-ai` adapter, running it inside OpenBB Workspace with OpenRouter as the model provider and a local MCP server: ```python from anyio import BrokenResourceError from fastapi import FastAPI, Request from fastapi.middleware.cors import CORSMiddleware from fastapi.responses import JSONResponse from pydantic_ai import Agent from pydantic_ai.mcp import MCPServerStreamableHTTP from pydantic_ai.models.openai import OpenAIChatModel from openbb_pydantic_ai import OpenBBAIAdapter, OpenBBDeps # Connect to local MCP server for additional tools mcp = MCPServerStreamableHTTP( url="http://localhost:8001/mcp/", max_retries=3, ) # Use any OpenRouter model you prefer model = OpenAIChatModel( provider="openrouter", model_name="prime-intellect/intellect-3", ) # Define agent with workspace-aware instructions agent = Agent( model, instructions=( """ You have access to the OpenBB Workspace and you can use the widgets to get data. To get data use the widget tools. Other data sources and analysis tools are available via the MCP toolset. When you want to visualize data, use the `openbb_create_chart` tool. This tool supports line, bar, scatter, pie, and donut charts. Always use this tool when you want to display visualizations. For tables, simply output markdown tables and they will be rendered nicely. Or use the `openbb_create_table` tool for large tables. Use placerholder {{place_chart_here}} in your response to indicate where charts should go. Highlight key insights and suggest actionable next steps when helpful. If the next step is obvious, you can just do it without asking the user. """ ), deps_type=OpenBBDeps, retries=3, toolsets=[mcp], ) app = FastAPI() AGENT_BASE_URL = "http://localhost:8003" # OpenBB Workspace discovers agents via this endpoint @app.get("/agents.json") async def agents_json(): return JSONResponse( content={ "": { "name": "My Custom Agent", "description": "This is my custom agent", "image": f"{AGENT_BASE_URL}/my-custom-agent/logo.png", "endpoints": { "query": f"{AGENT_BASE_URL}/query", }, "features": { "streaming": True, "widget-dashboard-select": True, # Access priority widgets "widget-dashboard-search": True, # Access non-priority widgets "mcp-tools": True, # Use MCP tools }, } } ) # Main query endpoint that handles SSE streaming @app.post("/query") async def query(request: Request): """ OpenBB Workspace sends POST requests with QueryRequest payload. The adapter handles SSE streaming automatically. """ try: return await OpenBBAIAdapter.dispatch_request( request, agent=agent ) except BrokenResourceError: # Client disconnected we expect this sometimes pass # CORS configuration for OpenBB Workspace domain app.add_middleware( CORSMiddleware, allow_origins=["https://pro.openbb.co"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) ``` ### Future Roadmap: Smarter Context Management While the current adapter solves the connectivity problem, the next step is context efficiency. Financial datasets can be massive, sometimes hundreds of thousands of tokens for a single widget. Feeding raw JSON into an LLM's context window is inefficient and prone to cause hallucinations. ## Get Started Today Install `openbb-pydantic-ai` from PyPI, plug in your model, and deploy your agent in no time. Build that niche earnings-call analyzer, ESG scoring agent, or custom quant workflow and share it with the OpenBB community. If you have ideas on how to improve this or just want to discuss agents, reach me on [LinkedIn](https://no.linkedin.com/in/magnus-samuelsen) or [GitHub](https://github.com/MagnusS0). --- *Magnus Samuelsen is an AI Engineer at Jyske Bank, working at the intersection of AI, finance and banking. He holds an MSc in Business Administration and Data Science from Copenhagen Business School. Magnus is also an active open-source contributor around AI in finance, having led the addition of MCP (Model Context Protocol) support to the Open Data Platform. You can find him on LinkedIn.*

Stories by Magnus Samuelsen

Building AI agents for OpenBB Workspace with Pydantic AI