Introduction
This comprehensive guide walks you through installing and launching the cloud edition of OpenLink AI Layer (OPAL) on Azure—empowering you to quickly unlock seamless AI and data integration capabilities that drive real business impact.
To give you a head start, check out this quick screencast overview demonstrating what OPAL can do right after installation, showcasing its powerful AI agent orchestration and data connectivity features.
Post-Installation Capabilities Overview
Table of Contents
- Prerequisites
- Installation & Use
- Additional Components
- Attribute-based Access Controls (ABAC)
- System-wide LLM API Key Registration
- Large Language Models Registration & Use
- Application Programming Interface (API) Access
- FAQ
- Glossary of Terms
- Related
Prerequisites
- A Microsoft Azure Portal account
Installation & Use
- Go to the OpenLink AI Layer Cloud Offer MarketPlace page.
- Select the
Get it Nowbutton to launch an instance
Note:
- Ensure when launching the offer it is assigned a
Public IPaddress
- Retrieve the default password for your instance:
ssh -i {your-pem-file.pem} azureuser@{your-instance-public-ip}
sudo cat /opt/virtuoso/database/.initial-password
- Open your browser and navigate to:
https://{your-instance-public-ip-or-domain}/chat
- Log in with the default username
dbaand the password retrieved in Step 3. When prompted, enter your preferred Large Language Model (LLM) provider’s API key.
Additional Components
Once your OPAL instance is up and running, you can optionally install additional components using the Virtuoso Application Distribution (VAD) installer—available via the Virtuoso Conductor UI or the isql command-line tool.
Important VAD Package Examples
- Assistant-Metal UI (VAD Package Link)
A user-friendly interface for interacting with OpenAI’s Assistants API. This component enables you to create, test, deploy, and manage AI Agents/Assistants using natural language prompts written in Markdown. - Linked Data Cartridges (VAD Package Link)
A powerful suite of data transformation tools that enhance data crawling across local and public HTTP networks (e.g., the Web). These transformations can be triggered by:
- SQL or SPARQL queries
- Briefcase folders
- Virtuoso’s built-in web crawlerThis package also includes a Meta Cartridge that integrates LLM-based batch processing. For example, given the URL of an HTML document, the system can:
- Trigger a batch task (executed asynchronously by the selected LLM)
- Transform content into RDF-based Knowledge Graphs
- Upload the resulting Knowledge Graph into Virtuoso’s native RDF store for Entity Relationship Graphs
These VAD packages significantly expand your OPAL instance’s capabilities—enabling advanced data workflows driven by entity relationship types defined in ontologies and enhanced through loosely coupled LLM integrations.
Supported LLMs
The following LLM providers and model families are currently supported:
- OpenAI — GPT family
- Google — Gemini and Gemma families
- Anthropic — Claude family
- Microsoft — GPT, Grok, and Phi families
- Perplexity — Sonar
- xAI — Grok family
- Mistral — Mistral family
- Alibaba — Qwen family
- DeepSeek — DeepSeek R family
- Meta — Llama family (via Groq or Cerebras)
Note: Other hosted or local LLMs that support OpenAI’s Tools API for external function call integration are also supported.
Attribute-based Access Controls (ABAC)
At this point, you need to secure your OPAL and LLM integrated environment by using fine-grained access controls to determine who is allowed to log into your assistant and under what constraints (restrictions). You achieve this by executing the following commands (using the Conductor or ISQL command-line interfaces) that set up these powerful access controls.
Fine-grained access controls use entity relationship graphs comprising relationships, authorizations, restrictions, groups, and agents (people or bots) that are named unambiguously using standardized identifiers (e.g., Internationalized Resource Identifiers [IRIs]) with terms from ontologies such as: W3C’s Access Control Ontology (http://www.w3.org/ns/auth/acl#), OpenLink Software’s Access Control Ontology(http://www.openlinksw.com/ontology/acl#), OpenLink Software’s Restrictions Ontology(http://www.openlinksw.com/ontology/restrictions#), and the Friend Of A Friend [FOAF](http://xmlns.com/foaf/0.1/).
Create Login Authorization for OPAL via /chat endpoint
OPAL is denoted by the system identifier urn:oai:chat, which makes it possible to construct an authorization for logins that belong to a designated group or list of users. In this case, we simply want to set the authorization scope to the DBA user denoted by the identifier http://localhost/dataspace/person/dba#this as follows:
SPARQL
PREFIX acl: <http://www.w3.org/ns/auth/acl#>
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX oplres: <http://www.openlinksw.com/ontology/restrictions#>
WITH <urn:virtuoso:val:default:rules>
DELETE {
<#rulePublicChat> ?p ?o .
} WHERE {
<#rulePublicChat> a acl:Authorization ; ?p ?o .
}
INSERT {
<#rulePublicChat> a acl:Authorization ;
foaf:maker <#dba> ;
oplacl:hasAccessMode oplacl:Read, oplacl:Write ;
acl:accessTo <urn:oai:chat> ;
acl:agent <http://localhost/dataspace/person/dba#this> ;
oplacl:hasRealm oplacl:DefaultRealm ;
oplacl:hasScope oplacl:Query .
} ;
Create Login Authorization for OPAL via /assist-metal endpoint
If you want to extend the login access to OPAL’s Assistants functionality via its /assist-metalendpoint, then execute the following to create a restriction on urn:oai:assistants (which is how this functionality realm is denoted):
SPARQL
PREFIX acl: <http://www.w3.org/ns/auth/acl#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
PREFIX oplres: <http://www.openlinksw.com/ontology/restrictions#>
WITH <urn:virtuoso:val:default:rules>
INSERT
{
<#assistantsAdmin> a acl:Authorization ;
foaf:maker <#dba> ;
oplacl:hasAccessMode oplacl:Read, oplacl:Write ;
acl:accessTo <urn:oai:assistants> ;
acl:agent <http://localhost/dataspace/person/dba#this> ;
oplacl:hasRealm oplacl:DefaultRealm ;
oplacl:hasScope oplacl:Query .
} ;
System-wide LLM API Key Registration
Rather than repetitively entering LLM API Keys when you log in, it might be preferred to have those keys registered system-wide. To achieve this goal, you need to create a restriction for successfully logged-in users by executing the following:
SPARQL
PREFIX acl: <http://www.w3.org/ns/auth/acl#>
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX oplres: <http://www.openlinksw.com/ontology/restrictions#>
WITH <urn:virtuoso:val:default:restrictions>
DELETE {
?s ?p ?o .
}
WHERE {
?s a oplres:Restriction ;
oplres:hasRestrictedResource <urn:oai:chat> ; ?p ?o .
FILTER(?s = <#restrictionAuthChatKey>)
}
INSERT {
<#restrictionAuthChatKey> a oplres:Restriction ;
foaf:maker <#dba> ;
rdfs:label "Allow Api Key" ;
oplres:hasRestrictedResource <urn:oai:chat> ;
oplres:hasRestrictedParameter <urn:oai:chat:enable-api-keys> ;
oplres:hasRealm oplacl:DefaultRealm ;
oplres:hasAgent <http://localhost/dataspace/person/dba#this> ; ### list of NetIds to have access for system key
oplres:hasRestrictedValue "true"^^xsd:boolean .
} ;
Large Language Models Registration & Use
With your OPAL instance successfully initialized, you can now bind it to one or more LLMs from the list above. You achieve this via the following commands executed via the Conductor or iSQL interfaces.
Listing Bound LLMs
Command Syntax
OAI.DBA.FILL_CHAT_MODELS('{Api Key}', '{llm-vendor-tag}');
Where llm-vendor-tags are as follows:
alibaba, claude, deepseek, gemini, groq, mistral, openai, xai.
Usage Examples
OAI.DBA.FILL_CHAT_MODELS('sk-xxxx', 'openai');
OAI.DBA.FILL_CHAT_MODELS('sk-ant-xxx', 'claude');
Google DeepMind’s Gemini does not currently offer an API for LLM listing, so you use:
OAI.DBA.REGISTER_CHAT_MODEL(‘{llm-vendor-tag}’,‘{llm-name}’);
Usage Example
OAI.DBA.REGISTER_CHAT_MODEL('gemini','gemini-2.5-flash-preview-05-20');
You can view the effects of this command via the Bound LLMs endpoint at:
https://{CNAME}/chat/admin/models.vsp
System-Wide LLM API Key Registration
To negate the need to present API Keys for bound LLMs at login time, you can register the API Keys for your chosen LLMs via the following command using the Conductor or ISQL command line interfaces:
Command Syntax
OAI.DBA.SET_PROVIDER_KEY( '{llm-vendor-tag}', 'api-key')
Usage Examples
OAI.DBA.SET_PROVIDER_KEY('openai','sk-svcacct-xxx');
OAI.DBA.SET_PROVIDER_KEY('claude','sk-ant-api03-xxx');
OAI.DBA.SET_PROVIDER_KEY('gemini','AIxxxx');
Application Programming Interface (API) Access
Your OPAL instance is also API-accessible, providing functionality for issuing and revoking credentials in the form of:
- Dynamically negotiated OAuth access tokens
- Issued OAuth Credentials and Bearer Tokens
You obtain credentials using the https://{CNAME}/oauth/applications.vsp endpoint, which presents you with the following:
- Client Applications Landing Page
- Credentials Issue page
Once your credentials have been generated and copied to a safe location, you are ready for API-based interaction with your instance using protocols such as the Model Context Protocol (MCP) and the Agent-2-Agent (A2A) Protocol.
Model Context Protocol (MCP) Usage
OPAL includes built-in support for the MCP protocol as both a client and a server, supporting the Server Sent Events (SSE) and Streamable HTTP transport options. This protocol offers direct access to AI Agents/Assistants created using natural language via Markdown with native stored procedures or external OpenAPI-accessible web services as the underlying tooling for executing operations.
To enable use of this protocol, you will need to set up CORS access for your MCP client regarding the following virtual directories via the Conductor UI:
- /.well-known
- /OAuth2
Here’s a screenshot sequence depicting how this task is performed for the /OAuth2 virtual directory.
HTTP Server’s Virtual Domains
Virtual Directories Listing for the HTTPS Virtual Domain
CORS Accepted Client Origins Listing
Note: Click “Finish” and then “Save Changes” for the CORS settings to take effect.
MCP Server Endpoints
The following endpoints are automatically generated for your OPAL instance:
- https://{CNAME}/chat/mcp/messages – for the Streamable HTTP transport
- https://{CNAME}/chat/mcp/sse – for the Server Sent Events transport
Other MCP Interaction Options
The following MCP Servers also offer bridge-based access to your OPAL instance, courtesy of the stdio transport leveraging data access protocols such as ODBC (Open Database Connectivity) for JavaScript/TypeScript runtimes (e.g. node.js), JDBC (Java Database Connectivity) for Java runtimes, Python ODBC (pyODBC) for Python runtimes, and ADO.NET for DotNet runtimes:
- OpenLink Generic MCP Server for ODBC
- OpenLink Generic MCP Server for JDBC
- OpenLink Generic MCP Server for pyODBC
- OpenLink Virtuoso MCP Server for ADO.NET
Claude Desktop
Here’s the JSON-based MCP Server configuration template for Claude Desktop.
{
"mcpServers": {
"{Your-Designated-MCP-Server-Name-For-SSE}": {
"command": "npx",
"args": ["mcp-remote", "https://{CNAME}/chat/mcp/sse"]
},
"{Your-Designated-MCP-Server-Name-For-Streamable-HTTP}": {
"command": "npx",
"args": [
"mcp-remote",
"https://{CNAME}/chat/mcp/messages"
]
}
}
}
MCP Inspector
By default, your Azure hosted OPAL instance uses an HTTPS configuration based on a self-signed certificate generated by Virtuoso. As a result, you need to set the following environment variable before starting your MCP inspector sessions:
export NODE_TLS_REJECT_UNAUTHORIZED=0
Naturally, if you reconfigure your instance to use your CA-signed certificate or leverage Virtuoso’s native support for the ACME protocol, you can work around this MCP inspector interaction limitation.
Your OPAL instance as an MCP Client
As an MCP client, OPAL is able to bind to tools published by any MCP Server that provides a Streamable HTTP endpoint. For example, our public endpoints:
You can test this capability using our public MCP endpoints via the following steps:
- Obtain Access Credentials in the form of an API Key
- Go to the following endpoint for your Azure instance: https://{CNAME}/chat/admin/
- Click on the “Application Authentication” button, which presents an authentication dialog from which you can select the “API Key” tab for registering the API Key obtained in step 1
- Authenticate, and if successful you will be presented with a list of tools from the remote MCP server.
- Select a Tool of interest from the MCP Server e.g.,
execute_sql_queryand then expand by clicking on theexpandcontrol to interact with the SQL capture interface.
Agent-2-Agent (A2A) Protocol Usage
A2A support provides access to AI Agents/Assistants created and deployed using your OPAL instance. It also enables their use in the construction of sophisticated Agentic workflows that route requests across these Agents. Agents are discoverable to all A2A client applications and services via an automatically generated JSON-based Agent Card situated at: https://{CNAME}/.well-known/agent.json. This file comprises the description of an Agent (named “OPAL Agent”) that’s equipped with a collection of skills, each of which is associated with an Agent/Assistant comprising MCP-accessible or directly-accessible tools that are mapped to operations based on native stored procedures, OpenAPI-compliant web services, or tools published by other MCP servers.
Default Agent Card for OPAL instances
{
"name": "OPAL Agent",
"description": "OpenLink AI Layer",
"url": "https://ec2-100-26-216-125.compute-1.amazonaws.com/chat/api/a2a",
"version": "1.0.0",
"provider": {
"organization": "OpenLink Software",
"url": "https://www.openlinksw.com"
},
"authentication": {
"schemes": [
"OAuth2"
],
"credentials": "{\"authorizationUrl\":\"https://ec2-100-26-216-125.compute-1.amazonaws.com/OAuth2/authorize\",\"tokenUrl\":\"https://ec2-100-26-216-125.compute-1.amazonaws.com/OAuth2/token\",\"scopes\":[\"openid\",\"profile\"]}"
},
"capabilities": {
"streaming": true,
"pushNotifications": false,
"stateTransitionHistory": false
},
"defaultInputModes": [
"text",
"text/plain"
],
"defaultOutputModes": [
"text",
"text/plain"
],
"skills": [
{
"id": "system-data-twingler-config",
"name": "OpenLink Data Twingler v2.0.4",
"description": "OpenLink Data Twingler v2.0.4",
"tags": []
},
{
"id": "system-database-admin-config",
"name": "Virtuoso DB Admin Assistant v1.0.0",
"description": "Virtuoso DB Admin Assistant v1.0.0",
"tags": []
},
{
"id": "system-uda-support-assistant-config",
"name": "OpenLink Support Agent for ODBC and JDBC v1.0.22",
"description": "OpenLink Support Agent for ODBC and JDBC v1.0.22",
"tags": []
},
{
"id": "system-val-admin-config",
"name": "Virtuoso Authentication Layer (VAL) Assistant v1.0.0",
"description": "Virtuoso Authentication Layer (VAL) Assistant v1.0.0",
"tags": []
},
{
"id": "system-virtuoso-support-assistant-config",
"name": "Virtuoso Support Agent v1.1.45",
"description": "Virtuoso Support Agent v1.1.45",
"tags": []
}
]
}
A2A Usage Example
Here’s a simple example from the A2A Samples Collection from OpenLink’s fork of Google’s A2A repository on Github.
Instructions take the form:
User: [Using] , perform .
Where
[]is optional and<>is mandatory.
Here’s output captured from a session involving an A2A client and an OPAL Agent:
npx tsx src/cli.ts https://{CNAME} {OPAL-INSTANCE-API-KEY}
ENDPOINT {CNAME}/chat/api/a2a
✓ Agent Card Found:
Name: OPAL Agent
Description: OpenLink AI Layer
Version: 1.0.0
Streaming: Supported
No active task or context initially. Use '/new' to start a fresh session or send a message.
Enter messages, or use '/new' to start a new session. '/exit' to quit.
OPAL Agent > You:
OPAL Agent > You: /new
✨ Starting new session. Task and Context IDs are cleared.
OPAL Agent > You: Using the Data Twingler, execute: SPARQL SELECT ?s ?name WHERE { SERVICE <https://dbpedia.org/sparql> {SELECT DISTINCT * WHERE {?s a foaf:Person; foaf:name ?name.} LIMIT 5}}
Sending message...
OPAL Agent [10:45:58 AM]: ℹ️ Task Stream Event: ID: 7557962efbbb266b16198632ca925237, Context: 5bf8bc79a99845b8bc4900452d2d31fb, Status: submitted
Task ID updated from N/A to 7557962efbbb266b16198632ca925237
Context ID updated from N/A to 5bf8bc79a99845b8bc4900452d2d31fb
OPAL Agent [10:46:09 AM]: 📄 Artifact Received: (unnamed) (ID: a0c76a0c-4152-11f0-a842-9a642c1c243f, Task: 7557962efbbb266b16198632ca925237, Context: 5bf8bc79a99845b8bc4900452d2d31fb)
Part 1: 📝 Text: Here are the results of your SPARQL query:
| s | name |
|-------------------------------------------------|--------------------|
| [CaMia Hopson](http://dbpedia.org/resource/CaMia_Hopson) | CaMia Jackson |
| [Cab Calloway](http://dbpedia.org/resource/Cab_Calloway) | Cab Calloway |
| [Cab Kaye](http://dbpedia.org/resource/Cab_Kaye) | Cab Kaye |
| [Cabbrini Foncette](http://dbpedia.org/resource/Cabbrini_Foncette) | Cabbrini Foncette |
| [Cabell Breckinridge](http://dbpedia.org/resource/Cabell_Breckinridge) | Cabell Breckinridge |
These are distinct individuals identified as persons with their names retrieved from the DBpedia SPARQL endpoint.
OPAL Agent [10:46:09 AM]: ✅ Status: completed (Task: 7557962efbbb266b16198632ca925237, Context: 5bf8bc79a99845b8bc4900452d2d31fb) [FINAL]
Task 7557962efbbb266b16198632ca925237 is final. Clearing current task ID.
--- End of response stream for this input ---
FAQ
General Questions
Q: What is OPAL?
A: OPAL (OpenLink AI Layer) is an AI-powered platform that provides integration with multiple Large Language Models (LLMs) and supports advanced protocols like MCP and A2A for building AI assistants and agents.
Q: What are the prerequisites for installing OPAL on Azure?
A: You need an active Amazon Web Services account to launch an OPAL AMI instance from the Azure Marketplace.
Q: What is the default username and how do I get the password?
A: The default username is dba. To retrieve the password, SSH into your instance and run: sudo cat /opt/virtuoso/database/.initial-password
Q: Which LLM providers are supported?
A: OPAL supports OpenAI (GPT), Google (Gemini/Gemma), Anthropic (Claude), Microsoft (GPT/Grok/Phi), Perplexity (Sonar), xAI (Grok), Mistral, Alibaba (Qwen), DeepSeek, and Meta (Llama via Groq/Cerebras).
Configuration Questions
Q: Do I need to enter API keys every time I log in?
A: No, you can register LLM API keys system-wide using the OAI.DBA.SET_PROVIDER_KEY()command to avoid repetitive entry.
Q: How do I secure my OPAL instance?
A: Use Attribute-based Access Controls (ABAC) by executing SPARQL commands to set up fine-grained access controls that determine who can log in and under what restrictions.
Q: What ports need to be open in my security group?
A: You need to allow HTTPS (port 443) from source 0.0.0.0/0 in your Azure security group settings.
Q: Do I need a public IP address?
A: Yes, ensure your instance has a public IP address. If not, use the Elastic IP assignment feature in the EC2 console.
Protocol Questions
Q: What is MCP?
A: Model Context Protocol (MCP) is a protocol that enables AI applications to securely connect to external data sources and tools, providing standardized access to resources.
Q: What is A2A?
A: Agent-2-Agent (A2A) Protocol enables communication and coordination between AI agents, allowing them to work together in sophisticated workflows.
Q: Can OPAL work as both an MCP client and server?
A: Yes, OPAL includes built-in support for MCP as both a client and server, supporting Server Sent Events (SSE) and Streamable HTTP transport options.
Technical Questions
Q: How do I handle SSL certificate issues with MCP Inspector?
A: Set the environment variable export NODE_TLS_REJECT_UNAUTHORIZED=0 before starting MCP inspector sessions, as OPAL uses self-signed certificates by default.
Q: What virtual directories need CORS access for MCP?
A: You need to set up CORS access for /.well-known and /OAuth2 virtual directories via the Conductor UI.
Q: How do I register models for providers that don’t support API listing?
A: For providers like Google Gemini that don’t offer API listing, use: OAI.DBA.REGISTER_CHAT_MODEL('{llm-vendor-tag}','{llm-name}');
Glossary of Terms
A2A (Agent-2-Agent Protocol) - A communication protocol that enables AI agents to interact and coordinate with each other in sophisticated workflows.
ABAC (Attribute-based Access Control) - A security model that uses attributes, policies, and environmental conditions to control access to resources.
ACME Protocol - Automatic Certificate Management Environment, a protocol for automating domain certificate verification and creation.
ADO.NET - A data access technology from Microsoft that provides connectivity between .NET applications and databases.
Agent Card - A JSON-based descriptor file that contains information about an AI agent’s capabilities, authentication requirements, and available skills.
AMI (Amazon Machine Image) - A pre-configured virtual machine image used to create instances in Amazon EC2.
API (Application Programming Interface) - A set of protocols and tools for building software applications and enabling communication between different systems.
Bearer Token - A security token used for authentication in HTTP requests, typically included in the Authorization header.
CNAME - Canonical Name record, a type of DNS record that maps an alias name to the true or canonical domain name.
CORS (Cross-Origin Resource Sharing) - A security feature that allows web applications running at one domain to access resources from another domain.
DBA - Database Administrator, also refers to the default administrative user account in Virtuoso.
FOAF (Friend of a Friend) - An RDF vocabulary for describing people, their activities, and relationships.
IRI (Internationalized Resource Identifier) - A generalization of URIs that allows characters from the Universal Character Set.
iSQL - Interactive SQL, a command-line interface for executing SQL commands in Virtuoso.
JDBC (Java Database Connectivity) - An API for connecting Java applications to databases.
LLM (Large Language Model) - AI models trained on large amounts of text data to understand and generate human-like text.
MCP (Model Context Protocol) - A protocol that enables AI applications to securely connect to external data sources and tools.
NetID - Network identifier used for user authentication and authorization.
OAuth - An open standard for access delegation commonly used for authorization.
ODBC (Open Database Connectivity) - A standard API for accessing database management systems.
OPAL (OpenLink AI Layer) - OpenLink Software’s AI platform that integrates multiple LLMs and supports advanced AI protocols.
OpenAPI - A specification for describing REST APIs, formerly known as Swagger.
pyODBC - A Python library for connecting to databases using ODBC.
RDF (Resource Description Framework) - A framework for representing information about resources on the web.
SPARQL - A query language and protocol for querying and manipulating RDF data.
SSE (Server-Sent Events) - A web standard that allows a server to push data to a web page in real-time.
SSL (Secure Sockets Layer) - A security protocol for establishing encrypted connections between clients and servers.
stdio - Standard input/output, referring to the default communication channels in computing systems.
URI (Uniform Resource Identifier) - A string that identifies a particular resource.
VAL (Virtuoso Authentication Layer) - Virtuoso’s authentication and authorization framework.
Virtuoso - OpenLink Software’s universal database management system that supports SQL, RDF, and other data models.