Table of Contents

πŸ‡«πŸ‡· Version franΓ§aise

See also: Tool inventory Β· Back to index

Pattern β€” Implementing a new tool

This guide details the complete process of creating an Orkeon tool, based on the classes and interfaces existing in the source code.

Step 1 β€” Choose the base class

Orkeon provides three base classes in Orkeon.Tools.Abstractions.Base:

Base class Usage Built-in protection
ToolBase<TRequest, TResponse> Generic tool No specialization
FileToolBase<TRequest, TResponse> File operations IFileSystemService (the VFS β€” mandatory first ctor argument), an optional IPathValidator (defense in depth against traversal), ResolveVirtualPath(path, FileAccessRights) and EnsureDirectoryExistsAsync(...) helpers
HttpToolBase<TRequest, TResponse> HTTP/API operations A shared, redirect-free HttpClient (or yours, or one from IHttpClientFactory), ValidateUrlAsync(uri, ct) β€” the given IUrlValidator, else a fail-closed default SSRF guard β€” and SanitizeHeaders(...) when an HttpHeaderSanitizer is given

The ToolBase<TRequest, TResponse> base class inherits from ToolBase (non-generic), which implements IBaseTool (Orkeon.Domain.Tools), the one contract every tool shares: any registered IBaseTool reaches the agent that names it. The two specialized bases derive from ToolBase too.

A file tool must never touch System.IO.File/Directory itself: it resolves every path through the VFS (see VFS compliance) β€” the Orkeon.Compliance.Vfs analyzer rejects the direct calls in framework code.

Step 2 β€” Define the Request and Response types

Each typed tool requires a TRequest type (input parameters β€” a class with a parameterless constructor, a sealed record is fine) and a TResponse type (result). The [FieldSchema] and [ReturnSchema] attributes (Orkeon.Domain.Attributes) are used to automatically generate the JSON schema exposed to the LLM (ToolSchemaGenerator, Orkeon.Domain.Tools).

  • Only a property carrying [FieldSchema] is a parameter. A property without it is invisible to the LLM (it keeps its C# default). A guard in Orkeon.Hosting.Tests (BuiltInToolSchemaTests, #282) reads every tool a run registers and fails, naming the tool and the property, when a public settable property of a typed request is not in the published Schema.Parameters: annotate the property, there is no allowlist. The TypeScript typings (Typings/tools.generated.d.ts) are rendered from that same schema, so a script sees exactly what the model sees. A C# enum property is published with its names (direction: Forward, Backward, Both, read case-insensitively); a [Flags] enum (expand) is a free string whose description lists the names, one or several joined by commas.
  • Parameter names are the property names in snake_case (TargetLanguage β†’ target_language), both in the schema and in the deserializer. A [JsonPropertyName] must therefore spell the same snake_case name, or the schema and the binding disagree.
  • Returns are opt-in by attribute: when at least one property of TResponse carries [ReturnSchema], only the annotated properties are returned to the agent; when none does, every property is.
  • A response is serialised in declaration order, and the pipeline cuts it from the end (at AgentDefaults.ResolveMaxToolResultLength: 4 000 characters unless the tool is listed in MaxToolResultLengthOverrides). Declare truncated, a cursor, a total and the counts before the bulky collections, and a rendering (mermaid_flowchart, dot) last, so a cut result still says what it is (#283). A rendering for a human reader is off by default (include_mermaid: false).
  • truncated has one meaning: more results exist than were returned. A tool that pages a list asks the store for one item past its bound and answers truncated: hits.Count > bound with the page cut to the bound; a page that is exactly full is not truncated (#283). Test both: "exactly max results: false" and "one more: true".

[FieldSchema] attribute (on TRequest)

Available properties:

[FieldSchema(
    Description = "...",       // Human-readable description for the LLM
    Type = "string",           // JSON Schema type (inferred when omitted)
    Format = "uri",            // OpenAPI format (inferred when omitted)
    IsRequired = true,         // Required; when omitted, inferred from C# nullability
                               // (a non-nullable string or int IS required β€” say
                               // IsRequired = false for an optional one with a default)
    Default = "value",         // YAML default value
    Enum = new[] { "a", "b" }, // Allowed values
    Example = "example",       // Example for the documentation
    ItemsType = "string",      // Element type when array
    ItemsFormat = "...",       // Element format when array
    TypeDefinitionRef = "..."  // Reference to a defined type
)]

Parameter types a tool's schema carries

[FieldSchema(Type = …)] accepts only the seven JSON Schema names (string, number, integer, boolean, object, array, null) or "any". Any other value throws when the tool's schema is first read (it is built lazily, on the first access to Schema), naming the DTO and the property.

  • A free parameter β€” a property of type object, JsonNode or JsonElement, or one with Type = "any" β€” is emitted with no type: the model may send any JSON value.
  • A dictionary (ImmutableDictionary<string, T>, IReadOnlyDictionary, IDictionary) is emitted as {"type":"object","additionalProperties":{…}}, the value schema inferred from T.
  • A model may send a dictionary two ways: a JSON object, or an array of [{"key":…,"value":…}]. Both are accepted and read as the same dictionary; an empty [] means {}, and a repeated key or a value of the wrong type is refused.
  • An array of the tool's own record (IReadOnlyList<EditBatchOperation>) is emitted with its items' properties and required (ParameterSchema.ItemProperties): every public property of the record, described by its [FieldSchema] when it carries one, inferred from the C# type and nullability otherwise. A record that references itself is described one level deep. The validator judges each item's properties as it judges the parameters β€” required, type, enum β€” before the tool runs, naming the place (Required parameter 'operations[0].path' is missing); the TypeScript typings of the item read the same [FieldSchema] (enum, IsRequired).

A ParameterSchema written by hand follows the same rules: Type is null for a free parameter, and Values holds the value schema of a dictionary (IsMap). It can say the rest of JSON Schema too: Properties for the properties of an object parameter (each with its Required), Items for the whole schema of an array's items at any depth (ItemsType, ItemsFormat and ItemProperties are read when it is unset), AnyOf for alternatives, the bounds (Minimum, Maximum, ExclusiveMinimum, ExclusiveMaximum, MinLength, MaxLength, Pattern, MinItems, MaxItems), and AllowsAdditionalProperties = false for a closed object - ToolSchema.AllowsAdditionalParameters = false closes the tool's input the same way. An array always goes out with items: {}, any JSON value, when nothing says what it holds.

Never write Type = "any" for a dictionary or a free value: leave Type out and let the property type decide. Strict providers (Z.AI GLM-5.3) refuse a schema holding "type":"any".

[ReturnSchema] attribute (on TResponse)

[ReturnSchema(
    Description = "...",       // Description of the returned field
    Type = "boolean",          // JSON Schema type (inferred when omitted)
    Format = "...",            // JSON Schema format hint
    ItemsType = "...",         // Element type when array
    ItemsFormat = "...",       // Element format when array
    TypeDefinitionRef = "...", // Reference to a defined type
    Example = true             // Example
)]

Never a secret in the request

A request property is something the model writes: it travels through the conversation with the provider, the tool-call log (Information level) and the usage record of the call. An API key, a token or a password is therefore never a request field. Inject an ISecretProvider and read the secret by name at execution time, never keeping it in a field β€” the pattern of web_search (TAVILY_API_KEY) and image_generation (OPENAI_API_KEY): a missing secret fails with a message that names the secret and its ORKEON_<NAME> variable, never a value.

Concrete example β€” Request and Response

using Orkeon.Domain.Attributes;

public sealed record TranslateRequest
{
    [FieldSchema(Description = "Text to translate", IsRequired = true,
                 Example = "Hello, world!")]
    public string Text { get; init; } = "";

    [FieldSchema(Description = "Target language ISO code", IsRequired = true,
                 Example = "fr", Enum = new[] { "fr", "de", "es", "it", "pt", "ja", "zh" })]
    public string TargetLanguage { get; init; } = "";

    [FieldSchema(Description = "Source language (auto-detected if omitted)",
                 IsRequired = false, Default = "auto")]
    public string SourceLanguage { get; init; } = "auto";
}

public sealed record TranslateResponse
{
    [ReturnSchema(Description = "Whether the translation succeeded")]
    public bool Success { get; init; }

    [ReturnSchema(Description = "Translated text")]
    public string TranslatedText { get; init; } = "";

    [ReturnSchema(Description = "Detected source language")]
    public string DetectedLanguage { get; init; } = "";

    [ReturnSchema(Description = "Error message if translation failed")]
    public string? Error { get; init; }
}

Step 3 β€” Implement the tool class

Inherit from the chosen base class, put a [ToolContract] attribute on the class and implement ExecuteTypedAsync. The contract's first positional argument is the agent-visible name (UniqueName β€” the exact string YAML tools: lists use, and the one the doc-claims CI gate checks against docs/tools/inventory.md; keep it to [a-zA-Z0-9_-], since OpenAI-compatible providers reject anything else); Name (a display name), Description and Category ride on the same attribute (ToolBase reads them: Name => contract?.UniqueName ?? contract?.Name ?? GetType().Name). Overriding the Name/Description properties works as well β€” the RaggableTree, session and RAG tools do it β€” and the CI gate reads either form.

[ToolContract("weather_lookup",
    Description = "Current weather for a city via the provider API.")]
public class WeatherTool : HttpToolBase<WeatherRequest, WeatherResponse> { … }

Five more virtual members are worth declaring:

Member Default What reads it
Access ToolAccess.Unspecified The per-call permission gate (Read / Edit / Execute); unspecified is classified fail-closed
AccessFor(arguments) Access The class of one call, for a tool whose operations differ (github, http_api); return the most restrictive class for arguments it does not recognise
Category the contract's Category, else "General" ("File Operations" / "Web Operations" for the two specialized bases) Catalogues and listings
RequiresHumanApproval false Approval-aware callers
UsesFileSystem false (true in FileToolBase) The mounts block of the agent's prompt; set it true for a tool that reads or writes virtual paths

The bases hand a tool their services as protected get-only properties: Logger and JsonOptions (ToolBase), HttpClient (HttpToolBase), FileSystemService (FileToolBase). The [LoggerMessage] source generator only finds a logger field, so a tool's logging methods are static partial and take the logger first: private static partial void LogFetched(ILogger logger, string city);, called as LogFetched(Logger, city).

Automatic pipeline

Before the typed pipeline runs, ToolBase.CallAsync checks the call's parameters against the generated schema (required parameters, types, allowed values) and answers a failed ToolCallResponse without calling your code. The ToolBase<TRequest, TResponse> pipeline itself is sealed (sealed override ExecuteCoreAsync) and automatically performs:

  1. YAML defaults injection: missing optional parameters are filled in with their Default values
  2. Deserialization: Dictionary<string, object?> β†’ TRequest via ComponentBase<TRequest, TResponse> β€” a value that cannot be converted answers Invalid parameters: …
  3. Validation: optional call to ValidateTypedRequest(TRequest) β€” return null if valid, an error message otherwise
  4. Execution: call to ExecuteTypedAsync(TRequest, CancellationToken) β€” your business logic
  5. Serialization: TResponse β†’ Dictionary<string, object?>
  6. Filtering: only the declared returns are included in the response (see Step 2)
  7. Outcome: a success boolean in the response decides the call's success; when it is false, the error string (or the errors list) becomes the error the agent sees. A response without success counts as a success.

An exception thrown by ExecuteTypedAsync is not fatal either: CallAsync turns it into a failed response (Tool execution failed: …), and a cancellation into Operation cancelled. An exception the tool throws on purpose, whose message alone says what to fix (an account to choose, a grant refused), implements the marker IExpectedToolError: CallAsync logs its type and message and leaves out its stack trace, which stays for every other exception, a fault.

Complete example β€” Simple tool (no external dependency)

using Microsoft.Extensions.Logging;
using Orkeon.Domain.Attributes;
using Orkeon.Domain.Tools;
using Orkeon.Tools.Abstractions.Base;

namespace MyCompany.Tools;

[ToolContract("translate",
    Description = "Translate text from one language to another. " +
                  "Source language is auto-detected if not specified.")]
public sealed class TranslateTool : ToolBase<TranslateRequest, TranslateResponse>
{
    public TranslateTool(ILogger<TranslateTool>? logger = null) : base(logger) { }

    public override ToolAccess Access => ToolAccess.Read;

    protected override string? ValidateTypedRequest(TranslateRequest request)
    {
        if (string.IsNullOrWhiteSpace(request.Text))
            return "Text to translate cannot be empty.";

        if (string.IsNullOrWhiteSpace(request.TargetLanguage))
            return "Target language must be specified.";

        return null; // Valid
    }

    protected override async Task<TranslateResponse> ExecuteTypedAsync(
        TranslateRequest request,
        CancellationToken cancellationToken)
    {
        try
        {
            // Business logic β€” a simplified translation here
            var translated = $"[{request.TargetLanguage}] {request.Text}";

            return new TranslateResponse
            {
                Success = true,
                TranslatedText = translated,
                DetectedLanguage = request.SourceLanguage == "auto" ? "en" : request.SourceLanguage
            };
        }
        catch (Exception ex)
        {
            return new TranslateResponse
            {
                Success = false,
                Error = ex.Message
            };
        }
    }
}

Step 4 β€” Complete example β€” Tool with an external dependency (HTTP)

For a tool calling an external API, use HttpToolBase<TRequest, TResponse>, which provides a shared HttpClient and URL validation β€” which your code calls (ValidateUrlAsync); nothing validates a URL behind your back.

using Microsoft.Extensions.Logging;
using Orkeon.Application.Interfaces.Security;
using Orkeon.Tools.Abstractions.Base;
using Orkeon.Domain.Attributes;
using Orkeon.Domain.Tools;
using System.Net.Http.Json;
using System.Text.Json;

namespace MyCompany.Tools;

// --- Request ---
public sealed record WeatherRequest
{
    [FieldSchema(Description = "City name to get weather for",
                 IsRequired = true, Example = "Paris")]
    public string City { get; init; } = "";

    [FieldSchema(Description = "Temperature unit",
                 IsRequired = false, Default = "celsius",
                 Enum = new[] { "celsius", "fahrenheit" })]
    public string Unit { get; init; } = "celsius";
}

// --- Response ---
public sealed record WeatherResponse
{
    [ReturnSchema(Description = "Whether the request succeeded")]
    public bool Success { get; init; }

    [ReturnSchema(Description = "Current temperature")]
    public double Temperature { get; init; }

    [ReturnSchema(Description = "Weather description")]
    public string Description { get; init; } = "";

    [ReturnSchema(Description = "Error message if request failed")]
    public string? Error { get; init; }
}

// --- Tool ---
[ToolContract("weather",
    Description = "Get current weather for a city. Returns temperature and conditions.")]
public sealed class WeatherTool : HttpToolBase<WeatherRequest, WeatherResponse>
{
    private const string BaseUrl = "https://api.weatherapi.com/v1";
    private readonly ISecretProvider _secrets;

    // Simple ctor (shared static HttpClient, redirects refused). To plug in the host's
    // IUrlValidator and HttpHeaderSanitizer, use the
    // base(IUrlValidator, HttpHeaderSanitizer, HttpClient?, ILogger?) ctor; without them
    // ValidateUrlAsync applies the fail-closed default guard.
    public WeatherTool(
        ISecretProvider secrets,
        HttpClient? httpClient = null,
        ILogger<WeatherTool>? logger = null)
        : base(httpClient, logger)
    {
        _secrets = secrets;
    }

    public override ToolAccess Access => ToolAccess.Read;

    protected override async Task<WeatherResponse> ExecuteTypedAsync(
        WeatherRequest request,
        CancellationToken cancellationToken)
    {
        using var secret = await _secrets.GetSecretAsync("WEATHER_API_KEY", cancellationToken).ConfigureAwait(false);
        try
        {
            var url = new Uri($"{BaseUrl}/current.json?key={secret.Value}&q={Uri.EscapeDataString(request.City)}");

            // SSRF check β€” mandatory as soon as any part of the URL comes from the agent
            var check = await ValidateUrlAsync(url, cancellationToken).ConfigureAwait(false);
            if (!check.IsAllowed)
                return new WeatherResponse { Success = false, Error = check.DenialReason };

            // HttpClient is the protected property inherited from HttpToolBase
            var response = await HttpClient.GetAsync(url, cancellationToken)
                .ConfigureAwait(false);

            response.EnsureSuccessStatusCode();

            var json = await response.Content.ReadFromJsonAsync<JsonElement>(
                cancellationToken: cancellationToken).ConfigureAwait(false);

            var tempC = json.GetProperty("current").GetProperty("temp_c").GetDouble();
            var condition = json.GetProperty("current")
                              .GetProperty("condition")
                              .GetProperty("text")
                              .GetString() ?? "Unknown";

            var temp = request.Unit == "fahrenheit" ? tempC * 9.0 / 5.0 + 32 : tempC;

            return new WeatherResponse
            {
                Success = true,
                Temperature = Math.Round(temp, 1),
                Description = condition
            };
        }
        catch (HttpRequestException ex)
        {
            return new WeatherResponse
            {
                Success = false,
                Error = $"HTTP error: {ex.Message}"
            };
        }
    }
}

Step 5 β€” Registration and usage

Option A β€” Direct injection via the builder

The simplest approach: instantiate the tool and pass it to the agent builder.

var weatherTool = new WeatherTool(secretProvider); // the host's ISecretProvider

var agent = new AgentBuilder()
    .Role("Weather Reporter")
    .Goal("Provide accurate weather forecasts")
    .WithTool(weatherTool)
    .Build();

Option B β€” DI registration via IServiceCollection

For full integration into the dependency injection pipeline:

// In an extension method or at startup
services.AddSingleton<IBaseTool>(sp =>
{
    var logger = sp.GetService<ILogger<WeatherTool>>();
    return new WeatherTool(sp.GetRequiredService<ISecretProvider>(), logger: logger);
});

The tool is then available via IEnumerable<IBaseTool>, and by name from YAML: AddOrkeonInfrastructure() registers the default ToolRegistry (Orkeon.Infrastructure.Tools), seeded from every IBaseTool in the container β€” the same registry the runners use, shipped in the Orkeon package, so an embedding host registers nothing more. Two DI tools with one name (compared case-insensitively) fail the registry's construction with both types named.

Option C β€” Via IToolRegistry

IToolRegistry (Orkeon.Domain.Tools; the default ToolRegistry everywhere) enables dynamic registration (RegisterToolAsync β€” refused, returning false, for a name another tool holds) and resolution of tools by name:

var toolRegistry = serviceProvider.GetRequiredService<IToolRegistry>();
var tool = await toolRegistry.GetToolByNameAsync("weather");

Step 6 β€” Internal composition pattern (FileToolBase / HttpToolBase)

ToolBase<TRequest, TResponse>, FileToolBase<TRequest, TResponse> and HttpToolBase<TRequest, TResponse> each use a composition pattern via a private inner class ComponentPipeline that inherits from ComponentBase<TRequest, TResponse> (Domain layer) β€” the specialized bases derive from the non-generic FileToolBase/HttpToolBase, not from ToolBase<,>, so each carries its own copy of the sealed pipeline.

This pattern lets the tool class access the typed pipeline's serialization/deserialization methods without inheriting directly from ComponentBase (which lives in the Domain layer and knows nothing about tool concepts).

Pipeline architecture

ToolBase<TRequest, TResponse> (or FileToolBase<> / HttpToolBase<>)
    β”‚
    β”œβ”€β”€ Contains: private ComponentPipeline _pipeline
    β”‚                  └── inherits ComponentBase<TRequest, TResponse>
    β”‚                       └── delegates to IComponentSerializer (static)
    β”‚                            └── JsonComponentSerializer (singleton)
    β”‚
    └── sealed override ExecuteCoreAsync()
         1. MergeWithYamlDefaults(parameters)     β†’ enriched Dict
         2. _pipeline.Deserialize(merged)          β†’ TRequest
         3. ValidateTypedRequest(typedRequest)     β†’ null | error
         4. ExecuteTypedAsync(request, ct)         β†’ TResponse  ← YOUR CODE
         5. _pipeline.Serialize(typedResponse)     β†’ Dict
         6. FilterOutput(resultDict)               β†’ filtered Dict
         7. return ToolCallResponse(success, result, error)

Source code excerpt (FileToolBaseGeneric.cs)

public abstract partial class FileToolBase<TRequest, TResponse> : FileToolBase
    where TRequest : class, new()
    where TResponse : class
{
    private readonly ComponentPipeline _pipeline = new();

    // The sealed pipeline prevents subclasses from bypassing
    // serialization or validation (simplified: the real method also catches
    // JsonException β†’ "Invalid parameters: …")
    protected sealed override async Task<ProtocolToolCallResponse> ExecuteCoreAsync(
        ProtocolToolCallRequest request, CancellationToken cancellationToken)
    {
        var mergedParams = MergeWithYamlDefaults(request.Parameters);
        var typedRequest = _pipeline.Deserialize(mergedParams);

        var validationError = ValidateTypedRequest(typedRequest);
        if (validationError is not null)
            return new ProtocolToolCallResponse(Success: false, Result: null, Error: validationError);

        var typedResponse = await ExecuteTypedAsync(typedRequest, cancellationToken);
        var resultDict = _pipeline.Serialize(typedResponse);
        var filteredResult = FilterOutput(resultDict);
        // ... success/error propagation from the `success` / `error` / `errors` fields ...
        return new ProtocolToolCallResponse(Success: success, Result: filteredResult, Error: error);
    }

    // Your extension point β€” pure business logic
    protected abstract Task<TResponse> ExecuteTypedAsync(
        TRequest request, CancellationToken cancellationToken);

    // Inner composition class
    private sealed class ComponentPipeline : ComponentBase<TRequest, TResponse>
    {
        public TRequest Deserialize(Dictionary<string, object?> parameters)
            => DeserializeRequest(parameters);
        public Dictionary<string, object?> Serialize(TResponse response)
            => SerializeResponse(response);
        protected override Task<TResponse> ExecuteTypedAsync(
            TRequest request, CancellationToken ct)
            => throw new NotSupportedException("Pipeline helper does not execute.");
    }
}

Serialization: snake_case and type coercion

The JsonComponentSerializer (Orkeon.Infrastructure.Serialization) uses JsonNamingPolicy.SnakeCaseLower and includes 9 tolerant converters to handle YAML values arriving as strings β€” the six below plus TolerantEnumConverterFactory (enum names matched case-insensitively, an unknown name answered with the list of valid ones), UriTolerantConverter and ImmutableArrayStringTolerantConverter:

  • BoolTolerantConverter: "true"/"false" (any case), "1"/"0" and numbers (non-zero β†’ true); "yes" is not accepted
  • IntTolerantConverter: "42" β†’ 42
  • LongTolerantConverter: "123456789" β†’ 123456789L
  • DecimalInvariantConverter: "3.14" β†’ 3.14m (culture-invariant)
  • DoubleInvariantConverter: "3.14" β†’ 3.14d
  • RawObjectConverter: unwraps JsonElement into native .NET types

This guarantees that YAML parameters (which are all strings at deserialization time) are correctly converted to the C# types expected by TRequest.

The serializer is process-wide: ComponentBase.DefaultSerializer. AddOrkeonInfrastructure() sets it (TrySetDefaultSerializer, which never overwrites one a host already set); a process that builds tools without it β€” a unit-test project, typically β€” sets it once itself (see Step 8), or the first call throws ComponentBase.DefaultSerializer has not been configured.

A file tool, the VFS way

FileReadTool.cs (Orkeon.Tools.FileSystem) is the reference: the request carries a virtual path, the tool resolves it with the right it needs, and every byte goes through FileSystemService, the protected property inherited from FileToolBase:

[ToolContract("line_count", Description = "Count the lines of a text file.")]
public sealed class LineCountTool : FileToolBase<LineCountRequest, LineCountResponse>
{
    // FileReadTool also takes an IPathValidator (base(fs, pathValidator, logger)) for
    // defense in depth on the resolved physical path
    public LineCountTool(IFileSystemService fileSystemService, ILogger<LineCountTool>? logger = null)
        : base(fileSystemService, logger) { }

    public override ToolAccess Access => ToolAccess.Read;

    protected override async Task<LineCountResponse> ExecuteTypedAsync(
        LineCountRequest request, CancellationToken cancellationToken)
    {
        // Mount + rights check (FileAccessRights.Read); physical paths never leak
        var check = ResolveVirtualPath(request.Path, FileAccessRights.Read);
        if (!check.IsAllowed)
            return new LineCountResponse { Success = false, Error = check.DenialReason };

        var stream = await FileSystemService.OpenReadStreamAsync(request.Path, cancellationToken)
            .ConfigureAwait(false);
        using var reader = new StreamReader(stream);
        var lines = 0;
        while (await reader.ReadLineAsync(cancellationToken).ConfigureAwait(false) is not null)
            lines++;
        return new LineCountResponse { Success = true, Lines = lines };
    }
}

A writing tool asks for FileAccessRights.Write (or Create), and calls EnsureDirectoryExistsAsync(virtualPath, ct) before creating a file in a new folder.

Step 7 β€” Registering a tool in a suite (NuGet package)

If the tool is meant to be distributed in a package, create a DI extension in the same project:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using Microsoft.Extensions.Logging;
using Orkeon.Application.Interfaces.Security;
using Orkeon.Domain.Tools;

namespace Orkeon.Tools.MyPackage;

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddOrkeonMyPackageTools(
        this IServiceCollection services)
    {
        // One IBaseTool registration per tool. NOT TryAddSingleton<IBaseTool, …>
        // twice: TryAdd keys on the SERVICE type, so the second call would be a
        // silent no-op. Tools with non-DI ctor args need the factory form.
        services.AddSingleton<IBaseTool>(sp => new WeatherTool(
            sp.GetRequiredService<ISecretProvider>(),
            logger: sp.GetService<ILogger<WeatherTool>>()));
        services.TryAddEnumerable(ServiceDescriptor.Singleton<IBaseTool, TranslateTool>());

        // Usable by name in YAML: the default ToolRegistry reads every IBaseTool
        // registered in DI (see Option B above).
        return services;
    }
}

Usage in Program.cs:

services.AddOrkeonApplication();
services.AddOrkeonInfrastructure();
services.AddOrkeonMyPackageTools();  // Your custom tools β€” resolvable by name from YAML

Step 8 β€” Testing the tool

Tool tests follow the repository conventions: xUnit with its native assertions only, no mocking framework and no fluent-assertion library. Doubles are hand-written classes named Mock*, Fake* or Stub* that implement the production interface, kept in a Doubles/ folder of the test project (reference: tests/core/Orkeon.Infrastructure.Tests/Doubles/MockTaskRepository.cs).

  • Serializer. Each tool test project sets the component serializer once, in a module initializer (TestModuleInitializer.cs, as in tests/tools/Orkeon.Tools.FileSystem.Tests/):

    internal static class TestModuleInitializer
    {
        [ModuleInitializer]
        internal static void Initialize()
        {
            if (!ComponentBase.IsDefaultSerializerConfigured)
                ComponentBase.DefaultSerializer = JsonComponentSerializer.Instance;
        }
    }
    
  • File system. Orkeon.Tests.Shared (tests/shared/) provides VFS doubles: FakeFileSystemService (in memory), DiskBackedFileSystemService and PassThroughFileSystemService (real disk, for tests only β€” see the VFS exception for tests), ThrowingFileSystemService.

  • Call the tool the way an agent does β€” CallAsync with a ToolCallRequest whose parameters use the snake_case names β€” so the schema check, the defaults, the deserialization and the output filtering are all exercised:

    [Fact]
    public async Task Should_CountLines_When_FileExists()
    {
        var fileSystem = new FakeFileSystemService()
            .AddMount("/workspace")
            .AddFile("/workspace/notes.txt", "one\ntwo\nthree");
        var tool = new LineCountTool(fileSystem);
    
        var response = await tool.CallAsync(new ToolCallRequest(
            ToolName: "line_count",
            Parameters: new Dictionary<string, object?> { ["path"] = "/workspace/notes.txt" }));
    
        Assert.True(response.Success, response.Error);
        var result = Assert.IsType<Dictionary<string, object?>>(response.Result);
        Assert.Equal(3, Convert.ToInt32(result["lines"], CultureInfo.InvariantCulture));
    }
    

A new built-in tool also has to appear in the inventory: the doc-claims gate (scripts/check-doc-claims.py) fails when a tool name in the code is missing from it, and the tool count on the front pages moves with it.

Pattern recap

1. Pick the base class       β†’  ToolBase<> / FileToolBase<> / HttpToolBase<>
2. Define TRequest           β†’  Record with [FieldSchema] on each parameter
3. Define TResponse          β†’  Record with [ReturnSchema] on each returned field
4. Implement the class       β†’  [ToolContract("name", Description = …)], ExecuteTypedAsync, Access
5. (Optional) Validation     β†’  override ValidateTypedRequest
6. Register                  β†’  Builder / DI (read by the default ToolRegistry) / IToolRegistry
7. Test                      β†’  xUnit, hand-written doubles, CallAsync with snake_case parameters

The JSON schema is auto-generated by ToolSchemaGenerator from the attributes β€” no manual maintenance required.