Opal Core Concepts
Before you dive into the code, it's crucial to understand the foundational ideas that make Opal tick. Core concepts are consistent across all its SDKs.
The Tool Manifest
Imagine you're introducing your tool to the Opal platform for the first time. You need a well-structured document that explains exactly what it is, what it needs, and how to use it. That document is the Tool Manifest. It’s the single source of truth that ensures Opal understands your tool perfectly.
This JSON blueprint contains all the essential details:
Name & Description: The human-readable "elevator pitch" for your tool.
Parameters: A detailed list of every input your tool expects, including their names, data types (string, number, boolean, etc.), and whether they are required or optional.
How to Invoke: The technical instructions: the specific HTTP endpoint (URL) and method (GET/POST) Opal should call to run your tool.
Authentication Requirements: Instructions on what, if any, credentials are needed.
The Discovery Endpoint
This is a specific URL your tool service must expose, typically at /discovery. When you register your tool with Opal, this is the first place it will "knock on the door." Its sole job is to respond to Opal's call by returning that all-important Tool Manifest we just discussed. This is how Opal dynamically discovers every tool your service offers, without you having to manually configure each one in a UI.
This endpoint is the critical handshake between your service and the Opal platform. If it's down, returns an error, or provides a malformed manifest, the conversation stops before it even begins. The SDKs automate its creation, so you can focus on your tool's logic.
Tool Execution
This is the main event—the process where Opal calls your tool to do its actual job. A user or process in Opal triggers your tool. Opal packages up all the provided parameters into a neat HTTP request (a POST with a JSON body). This request is sent to your tool's designated execution endpoint. Your tool processes the request, performs its task (query a database, call an API, run a calculation, etc.), and then returns a structured response (as JSON) back to Opal. This is the "work" phase. Understanding the expected request format and designing a clear response is key to implementing your tool's core functionality effectively.
Authentication
The essential security layer that ensures only authorized requests from Opal can trigger your tools and access their capabilities.
Bearer Tokens: A simple yet powerful method where Opal passes a secret token in the Authorization header. Your tool's first job is to validate this token before doing anything else.
OAuth Flows: For tools that interact with third-party services (like Google or Salesforce), your tool can leverage OAuth through Opal to securely access user data.
The Opal SDKs provide built-in helpers to simplify implementing these critical security measures.
Do you want to learn more?
Comments