Create Custom Tools with SDKs
Why build custom tools
Section titled “Why build custom tools”System tools handle common tasks. Connector tools integrate popular third-party platforms. But every organization has unique needs: proprietary CRM systems, internal analytics dashboards, custom pricing engines, or legacy databases that no pre-built tool covers. Custom tools bridge these gaps by letting your developers expose any HTTP endpoint as an Opal capability.
Key concepts
Section titled “Key concepts”Tool manifest
Section titled “Tool manifest”A JSON declaration describing the tool to Opal. It includes:
- Name and description: Human-readable labels
- Parameters: Input specifications with name, data type (string, number, boolean, array, or object), description, and required status
- Execution details: HTTP endpoint URL and method (GET or POST)
- Authentication requirements: Credential specifications
Discovery endpoint
Section titled “Discovery endpoint”An HTTP endpoint (typically /discovery) that returns tool manifests. When you register a custom tool, Opal calls this endpoint to discover available tools. If the endpoint is inaccessible or returns malformed data, Opal cannot find or use the tools.
Authentication
Section titled “Authentication”Opal supports only Opti ID for tool authentication. Common patterns include bearer tokens in Authorization headers and OAuth flows for third-party service integrations.
Choose an SDK
Section titled “Choose an SDK”| SDK | Install command | Best for |
|---|---|---|
| JavaScript/TypeScript | npm install @optimizely-opal/opal-tools-sdk | Web-based tools, Node.js workflows, UI extensions |
| Python | pip install optimizely-opal.opal-tools-sdk | Backend automation, data processing, ML pipelines |
| C# | Install-Package OptimizelyOpal.OpalToolsSDK | Enterprise .NET applications, Azure integrations |
SDK selection criteria
Section titled “SDK selection criteria”- Team expertise: Use technologies your team already knows
- Performance: C# for low-latency, Python for data-heavy, JavaScript for concurrent I/O
- Tool type: Python for data/ML, JavaScript for web APIs, C# for enterprise backends
- Ecosystem: C# for Microsoft/Azure, Python for cloud/data, JavaScript for web APIs
- Deployment: All SDKs support serverless (AWS Lambda, Azure Functions, Google Cloud Functions) and containers (Kubernetes, OCP)
SDK features
Section titled “SDK features”JavaScript/TypeScript
Section titled “JavaScript/TypeScript”- Type definitions for parameters and responses
- Express.js middleware for rapid API setup
@tool()decorators for clean tool definitions- Built-in parameter validation
- Authentication helpers for Opti ID
Python
Section titled “Python”@tool()decorators for Pythonic tool definitions- Automatic
/discoveryendpoint generation - Python type hint validation
- FastAPI integration (Python 3.7+)
- Authentication helpers
[Tool]and[RequiresAuth]attributes for declarative configuration- ASP.NET Core integration
- Advanced parameter validation with data annotations
- Dependency injection support for enterprise patterns
Register a custom tool in Opal
Section titled “Register a custom tool in Opal”After building your tool:
- Deploy it to an accessible HTTP endpoint
- Navigate to Opal > Tools
- Click Add Custom Tool
- Enter the discovery endpoint URL
- Opal calls the endpoint and displays discovered tools
- Review tool descriptions and parameters
- Click Add to register the tools
- Toggle Active and optionally Enabled in Chat
Best practices
Section titled “Best practices”- Avoid hardcoding sensitive information in tool manifests. Use environment variables and configuration management.
- Return structured JSON from tool execution endpoints for reliable parsing by Opal.
- Handle errors gracefully with descriptive error messages that help Opal explain failures to users.
- Version your tools to maintain backward compatibility when updating endpoints.
- Test discovery endpoints independently before registering in Opal.