Click “Add matching widget to dashboard” to add the widget to your current dashboard with the same parameters applied by Copilot.
---
---
title: Skills
sidebar_position: 14
description: Create and invoke custom AI skills from the OpenBB Copilot chat interface
keywords:
- skills
- custom skills
- AI skills
- skill commands
- reusable prompts
- copilot skills
---
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
3. Enter your base URL; Workspace fetches `/agents.json` and uses `/query` for conversations.
Ensure CORS settings are correct and SSE are configured on your service.
## Example
Simplistic example that allows users to communicate with an agent that can optimize the user prompt. The code is open source [and available here](https://github.com/OpenBB-finance/agents-for-openbb/tree/main/20-financial-prompt-optimizer).
This agent does nothing else - it doesn't parse data added to context, doesn't pass data in the dashboard, doesn't share step-by-step reasoning or citations, doesn't create artifacts, etc. We will dive on each of these features in the AI features tab.
```python
from typing import AsyncGenerator
import openai
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse
from sse_starlette.sse import EventSourceResponse
from openbb_ai.models import MessageChunkSSE, QueryRequest
from openbb_ai import message_chunk
from openai.types.chat import (
ChatCompletionMessageParam,
ChatCompletionUserMessageParam,
ChatCompletionAssistantMessageParam,
ChatCompletionSystemMessageParam,
)
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
@app.get("/agents.json")
def get_copilot_description():
"""Agent descriptor for the OpenBB Workspace."""
return JSONResponse(
content={
"financial_prompt_optimizer": {
"name": "Financial Prompt Optimizer",
"description": "Optimizes a user's prompt for finance: clearer, more specific, and actionable.",
"image": "https://github.com/OpenBB-finance/copilot-for-terminal-pro/assets/14093308/7da2a512-93b9-478d-90bc-b8c3dd0cabcf",
"endpoints": {"query": "http://localhost:7777/v1/query"},
"features": {
"streaming": True,
"widget-dashboard-select": False,
"widget-dashboard-search": False,
},
}
}
)
@app.post("/v1/query")
async def query(request: QueryRequest) -> EventSourceResponse:
"""Stream a concise optimized prompt and rationale."""
openai_messages: list[ChatCompletionMessageParam] = [
ChatCompletionSystemMessageParam(
role="system",
content=(
"You are a concise Financial Prompt Optimizer.\n"
"Rewrite the user's prompt to be clearer, more specific, and immediately actionable for financial analysis.\n"
"Always return exactly the improved prompt:\n"
"Optimized Prompt: 
## Architecture
This pattern extends widget citations by adding document-level text extraction and positioning. Extract PDF content with character-level precision for accurate highlighting.
`agents.json` configuration:
```python
return JSONResponse(content={
"vanilla_agent_pdf_citations": {
"name": "Vanilla Agent PDF Citations",
"description": "A vanilla agent that handles PDF data with citation support.",
"endpoints": {"query": "http://localhost:7777/v1/query"},
"features": {
"streaming": True,
"widget-dashboard-select": True,
"widget-dashboard-search": False,
},
}
})
```
### Query flow
- Extract PDF content when widget data contains PDF format
- Use `pdfplumber` to get text with character positions
- Store text positions for citation highlighting
- Create multiple citation types:
- Basic widget citation for data source
- Highlighted citation for specific text passages
- Stream citations with bounding boxes for visual highlighting
### OpenBB AI SDK
- `CitationHighlightBoundingBox`: Precise text highlighting with coordinates
- `PdfDataFormat`: Identifies PDF content in widget data
- `quote_bounding_boxes`: Attach visual highlights to citations
- Text position tracking: `x0`, `top`, `x1`, `bottom` for accurate placement
## Core logic
Extract PDF text with positions for precise highlighting:
```python
import pdfplumber
from openbb_ai import cite, citations
from openbb_ai.models import CitationHighlightBoundingBox
def extract_pdf_with_positions(pdf_bytes: bytes) -> Tuple[str, List[Dict[str, Any]]]:
"""Extract text and positions from PDF."""
document_text = ""
text_positions = []
with pdfplumber.open(io.BytesIO(pdf_bytes)) as pdf:
for page_num, page in enumerate(pdf.pages, 1):
# Extract character-level data for positioning
if page.chars:
# Group characters into lines
lines = {}
for char in page.chars:
y = round(char['top'])
if y not in lines:
lines[y] = {'chars': [], 'x0': char['x0'], 'x1': char['x1']}
lines[y]['chars'].append(char['text'])
lines[y]['x0'] = min(lines[y]['x0'], char['x0'])
lines[y]['x1'] = max(lines[y]['x1'], char['x1'])
# Get first meaningful line for citation
sorted_lines = sorted(lines.items())
for y_pos, line_data in sorted_lines[:5]:
line_text = ''.join(line_data['chars']).strip()
if line_text and len(line_text) > 10:
text_positions.append({
'text': line_text,
'page': page_num,
'x0': line_data['x0'],
'top': y_pos,
'x1': line_data['x1'],
'bottom': y_pos + 12
})
break
# Extract full text for context
page_text = page.extract_text()
if page_text:
document_text += page_text + "\\n\\n"
return document_text, text_positions
```
Create citations with line/word level highlighting in the PDF:
```python
async def handle_widget_data(data: list[DataContent | DataFileReferences]):
"""Process widget data and create PDF citations."""
widget_text, pdf_text_positions = await handle_widget_data(message.data)
context_str += widget_text
# Create citations for widget data
for widget_data_request in message.input_arguments["data_sources"]:
widget = matching_widgets[0]
# Basic widget citation
basic_citation = cite(
widget=widget,
input_arguments=widget_data_request["input_args"],
)
citations_list.append(basic_citation)
# PDF citation with highlighting
if pdf_text_positions and len(pdf_text_positions) > 0:
first_line = pdf_text_positions[0]
pdf_citation = cite(
widget=widget,
input_arguments=widget_data_request["input_args"],
extra_details={
"Page": first_line['page'],
"Reference": "First sentence of document"
}
)
# Add precise text highlighting
pdf_citation.quote_bounding_boxes = [[
CitationHighlightBoundingBox(
text=first_line['text'][:100],
page=first_line['page'],
x0=first_line['x0'],
top=first_line['top'],
x1=first_line['x1'],
bottom=first_line['bottom']
)
]]
citations_list.append(pdf_citation)
```
---
---
title: Create charts
sidebar_position: 6
description: Stream inline charts as part of your agent’s response
keywords:
- charts
- visualization
- artifacts
- SSE
---
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
## Architecture
Emit chart artifacts so visualizations render below the answer. The example shows multiple chart types in one response.
`agents.json` configuration with `widget-dashboard-select` feature enabled:
```python
return JSONResponse(content={
"vanilla_agent_charts": {
"endpoints": {"query": "http://localhost:7777/v1/query"},
"features": {
"widget-dashboard-select": False,
"widget-dashboard-search": False,
},
}
})
```
### Query flow
- Process user request and prepare data for visualization
- Stream explanatory text with `message_chunk()`
- Create chart data as list of dictionaries
- Choose appropriate chart type based on data characteristics:
- **Line/Bar/Scatter**: Use `x_key` and `y_keys` for XY data
- **Pie/Donut**: Use `angle_key` for values, `callout_label_key` for labels
- Emit `chart()` artifacts with proper configuration
- Charts render interactively below streamed content
### OpenBB AI SDK
- `chart(type, data, x_key, y_keys, name, description)`: Creates `MessageArtifactSSE` for chart display
- Chart types: `"line"`, `"bar"`, `"scatter"`, `"pie"`, `"donut"`
- Chart parameters handled by specific models:
- `LineChartParameters`, `BarChartParameters`, `ScatterChartParameters`
- `PieChartParameters`, `DonutChartParameters`
- `message_chunk(text)`: Streams explanatory text around charts
- Charts support interactive features like zoom, hover, and data export
## Core logic
```python
from openbb_ai import message_chunk, chart
from openbb_ai.models import QueryRequest
import datetime
async def query(request: QueryRequest) -> EventSourceResponse:
async def execution_loop():
# Stream introduction
yield message_chunk("Let me create some visualizations to illustrate the data trends.\n\n").model_dump()
# Prepare time series data
price_data = [
{"date": "2024-01-01", "price": 150.0, "volume": 1200000},
{"date": "2024-01-02", "price": 152.5, "volume": 1350000},
{"date": "2024-01-03", "price": 148.2, "volume": 1100000},
{"date": "2024-01-04", "price": 155.8, "volume": 1450000},
]
# Create line chart for price trend
yield chart(
type="line",
data=price_data,
x_key="date",
y_keys=["price"],
name="Stock Price Trend",
description="Daily stock price movement over time"
).model_dump()
yield message_chunk("\n\nThe line chart shows an overall upward trend. Now let's look at volume distribution:\n\n").model_dump()
# Create bar chart for volume
yield chart(
type="bar",
data=price_data,
x_key="date",
y_keys=["volume"],
name="Trading Volume",
description="Daily trading volume by date"
).model_dump()
# Portfolio allocation pie chart
portfolio_data = [
{"asset": "Stocks", "allocation": 60},
{"asset": "Bonds", "allocation": 25},
{"asset": "Cash", "allocation": 10},
{"asset": "Real Estate", "allocation": 5}
]
yield message_chunk("\n\nHere's the portfolio allocation breakdown:\n\n").model_dump()
yield chart(
type="pie",
data=portfolio_data,
angle_key="allocation",
callout_label_key="asset",
name="Portfolio Allocation",
description="Investment portfolio distribution by asset class"
).model_dump()
return EventSourceResponse(execution_loop(), media_type="text/event-stream")
```
---
---
title: Create HTML artifacts
sidebar_position: 7
description: Stream inline HTML artifacts as part of your agent's response
keywords:
- html
- artifacts
- visualization
- custom rendering
- SSE
- widgets
---
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
## Architecture
Emit HTML artifacts so custom visualizations render below the answer. HTML content is sanitized with DOMPurify before rendering for security.
`agents.json` configuration:
```python
return JSONResponse(content={
"vanilla_agent_html": {
"name": "HTML Artifacts Agent",
"description": "An example agent that produces HTML artifacts rendered inline in the chat.",
"endpoints": {"query": "/v1/query"},
"features": {
"streaming": True,
"widget-dashboard-select": False,
"widget-dashboard-search": False,
},
}
})
```
### Query flow
- Process user request and prepare HTML content
- Stream explanatory text with `message_chunk()`
- Create HTML content as a string (inline styles supported)
- Emit `html_artifact()` events with proper configuration
- HTML renders inline below streamed content
- Users can click widget icon to add artifacts to dashboard
### SSE event format
HTML artifacts are sent as SSE events with the following structure:
```python
{
"event": "copilotMessageArtifact",
"data": {
"type": "html",
"uuid": "unique-id",
"name": "artifact_name",
"description": "A description of the artifact",
"content": "