Optimizely.Opal.Tools 0.2.0

Opal Tools SDK for C#

This SDK helps you create tool services for the Opal AI Assistant platform using C# and ASP.NET Core.

Installation

You can install the SDK using NuGet:

dotnet add package OpalToolsSDK

Quick Start

Here's a simple example of how to create a tools service with two tools:

using Microsoft.AspNetCore.Builder;
using OpalToolsSDK;
using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// Create and register the tools service
var toolsService = app.AddOpalToolsService();

// Register all tools from this assembly
toolsService.RegisterToolsFromExecutingAssembly(app);

// Start the app
app.Run();

// Tool parameter models
public class GreetingParameters
{
    [Required]
    [Description("Name of the person to greet")]
    public string Name { get; set; } = string.Empty;
    
    [Description("Language for greeting (defaults to random)")]
    public string? Language { get; set; }
}

public class DateParameters
{
    [Description("Date format (defaults to ISO format)")]
    public string Format { get; set; } = "yyyy-MM-dd";
}

// Tool implementations
public static class Tools
{
    [Tool("greeting", "Greets a person in a random language (English, Spanish, or French)")]
    public static async Task<object> Greeting(GreetingParameters parameters)
    {
        // Get parameters
        var name = parameters.Name;
        var language = parameters.Language;
        
        // If language not specified, choose randomly
        if (string.IsNullOrEmpty(language))
        {
            var random = new Random();
            var languages = new[] { "english", "spanish", "french" };
            language = languages[random.Next(languages.Length)];
        }
        
        // Generate greeting based on language
        string greeting;
        if (language.ToLower() == "spanish")
        {
            greeting = $"¡Hola, {name}! ¿Cómo estás?";
        }
        else if (language.ToLower() == "french")
        {
            greeting = $"Bonjour, {name}! Comment ça va?";
        }
        else // Default to English
        {
            greeting = $"Hello, {name}! How are you?";
        }
        
        return new
        {
            greeting,
            language
        };
    }
    
    [Tool("todays-date", "Returns today's date in the specified format")]
    public static async Task<object> TodaysDate(DateParameters parameters)
    {
        // Get parameters
        var format = parameters.Format;
        
        // Get today's date
        var today = DateTime.Now;
        
        // Format the date
        var formattedDate = today.ToString(format);
        
        return new
        {
            date = formattedDate,
            format,
            timestamp = ((DateTimeOffset)today).ToUnixTimeSeconds()
        };
    }
}

Authentication

To create a tool that requires authentication:

[Tool("get-calendar", "Gets user's calendar events")]
[RequiresAuth("google", "calendar")]
public static async Task<object> GetCalendar(CalendarParameters parameters, AuthData authData)
{
    // Use authData.Provider and authData.Credentials to authenticate
    // ...
    
    return new
    {
        events = new[] { "Event 1", "Event 2" }
    };
}

Tool Request/Response Format

The tool request format follows the Opal Tools Management Service specification:

{
  "parameters": {
    "name": "John",
    "language": "spanish"
  },
  "auth": {
    "provider": "google",
    "credentials": {
      "token": "access_token_value"
    }
  }
}

The response is the direct JSON serialization of the object returned by your tool method:

{
  "greeting": "¡Hola, John! ¿Cómo estás?",
  "language": "spanish"
}

API Reference

Models

• ParameterType: Enum for parameter types (String, Integer, Number, Boolean, Array, Object)
• Parameter: Parameter definition for a tool
• AuthRequirement: Authentication requirements for a tool
• Function: Function definition for a tool
• AuthData: Authentication data from a request

Attributes

• [Tool(name, description)]: Marks a method as an Opal tool
• [RequiresAuth(provider, scopeBundle, required)]: Specifies authentication requirements

ToolsService

• AddOpalToolsService(): Extension method to add the tools service to a WebApplication
• RegisterToolsFromCallingAssembly(): Registers all tools from the calling assembly
• RegisterToolsFromExecutingAssembly(): Registers all tools from the executing assembly
• RegisterToolsFromAssembly(assembly): Registers all tools from the specified assembly

Best Practices

1. Use the [Tool] attribute on static methods
2. Define parameter models with clear property descriptions
3. Return simple objects that can be serialized to JSON
4. Use async methods for tools that perform I/O operations
5. Handle errors gracefully within your tool methods
6. Provide clear descriptions for tools and parameters

Advanced Usage

Custom Parameter Validation

You can use standard .NET validation attributes:

public class GreetingParameters
{
    [Required]
    [StringLength(100)]
    public string Name { get; set; } = string.Empty;
    
    [RegularExpression("english|spanish|french", ErrorMessage = "Language must be english, spanish, or french")]
    public string? Language { get; set; }
}

Dependency Injection

For tools that need access to services:

[Tool("get-weather", "Gets the weather for a location")]
public static async Task<object> GetWeather(WeatherParameters parameters, HttpContext context)
{
    var weatherService = context.RequestServices.GetRequiredService<IWeatherService>();
    var forecast = await weatherService.GetForecastAsync(parameters.Location);
    
    return new
    {
        location = parameters.Location,
        forecast
    };
}

License

MIT License