π«π· 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 inOrkeon.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 publishedSchema.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
TResponsecarries[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 inMaxToolResultLengthOverrides). Declaretruncated, 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). truncatedhas one meaning: more results exist than were returned. A tool that pages a list asks the store for one item past its bound and answerstruncated: hits.Count > boundwith the page cut to the bound; a page that is exactly full is not truncated (#283). Test both: "exactlymaxresults: 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,JsonNodeorJsonElement, or one withType = "any"β is emitted with notype: the model may send any JSON value. - A dictionary (
ImmutableDictionary<string, T>,IReadOnlyDictionary,IDictionary) is emitted as{"type":"object","additionalProperties":{β¦}}, the value schema inferred fromT. - 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'propertiesandrequired(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:
- YAML defaults injection: missing optional parameters are filled in with their
Defaultvalues - Deserialization:
Dictionary<string, object?>βTRequestviaComponentBase<TRequest, TResponse>β a value that cannot be converted answersInvalid parameters: β¦ - Validation: optional call to
ValidateTypedRequest(TRequest)β returnnullif valid, an error message otherwise - Execution: call to
ExecuteTypedAsync(TRequest, CancellationToken)β your business logic - Serialization:
TResponseβDictionary<string, object?> - Filtering: only the declared returns are included in the response (see Step 2)
- Outcome: a
successboolean in the response decides the call's success; when it isfalse, theerrorstring (or theerrorslist) becomes the error the agent sees. A response withoutsuccesscounts 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 acceptedIntTolerantConverter:"42"β42LongTolerantConverter:"123456789"β123456789LDecimalInvariantConverter:"3.14"β3.14m(culture-invariant)DoubleInvariantConverter:"3.14"β3.14dRawObjectConverter: unwrapsJsonElementinto 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 intests/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),DiskBackedFileSystemServiceandPassThroughFileSystemService(real disk, for tests only β see the VFS exception for tests),ThrowingFileSystemService.Call the tool the way an agent does β
CallAsyncwith aToolCallRequestwhose 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.