CommonTools

Common Tools

Agent Framework Toolkit includes a provider-independent set of commonly useful tools in the AgentFrameworkToolkit.Tools.Common namespace.

Note

These tools are regular AITool instances and can be used with both Agent Framework Toolkit agents and plain AIAgent instances from Microsoft Agent Framework.

Package

dotnet add package AgentFrameworkToolkit.Tools

Quick start

using AgentFrameworkToolkit.OpenAI;
using AgentFrameworkToolkit.Tools;
using AgentFrameworkToolkit.Tools.Common;

OpenAIAgentFactory agentFactory = new("<apiKey>");
AIToolsFactory toolsFactory = new();

OpenAIAgent agent = agentFactory.CreateAgent(new AgentOptions
{
    Model = "gpt-5",
    Instructions = "Use tools when helpful.",
    Tools =
    [
        ..toolsFactory.GetTimeTools(),
        ..toolsFactory.GetRandomTools(),
        ..toolsFactory.GetWebsiteTools(),
        ..toolsFactory.GetHttpClientTools(),
        ..toolsFactory.GetEmailTools(new GetEmailToolsOptions
        {
            EmailToolsOptions = new EmailToolsOptions
            {
                Host = "smtp.example.com",
                Port = 587,
                UseSecureConnection = true,
                Username = "<smtp-username>",
                Password = "<smtp-password>",
                FromAddress = "agent@example.com",
                FromDisplayName = "Agent",
                ConfineSendingToTheseDomains = ["example.com"]
            }
        })
    ]
});

FileSystemTools

File system tools include both read and write operations. If you enable them, you should typically confine them to specific folders.

Tool names

• Read: get_content_of_file, get_files, get_folders, file_exists, folder_exists
• Write: create_file, create_folder, move_file, delete_file, delete_folder, copy_file, copy_folder

Confining file system access

If you set FileSystemToolsOptions.ConfinedToTheseFolderPaths, every operation will be validated to ensure it stays within one of those folder paths (including subfolders). If you do not set it, no confinement is applied.

using AgentFrameworkToolkit.Tools;
using AgentFrameworkToolkit.Tools.Common;

AIToolsFactory toolsFactory = new();

IList<AITool> tools = toolsFactory.GetFileSystemTools(new GetFileSystemToolsOptions
{
    FileSystemToolsOptions = new FileSystemToolsOptions
    {
        ConfinedToTheseFolderPaths = ["C:\\data\\agent-workdir"]
    }
});

HttpClientTools

HTTP tools provide simple GET/POST/PUT/PATCH/DELETE/HEAD helpers that return a formatted response string.

Tool names

http_get, http_post, http_put, http_patch, http_delete, http_head

Options

• HttpClientToolsOptions.IncludeHeaders (default: false)
• HttpClientToolsOptions.ThrowOnError (default: false)
• HttpClientToolsOptions.HttpClientFactory (optional)

AIToolsFactory toolsFactory = new();
IList<AITool> tools = toolsFactory.GetHttpClientTools(new GetHttpClientToolsOptions
{
    HttpClientToolsOptions = new HttpClientToolsOptions { IncludeHeaders = true }
});

TimeTools

Time tools provide current time in UTC and local time. Local time can optionally accept a timeZoneId parameter (Windows/ICU timezone ids supported by .NET).

Tool names

get_now_local, get_now_utc

AIToolsFactory toolsFactory = new();
IList<AITool> tools = toolsFactory.GetTimeTools(new GetTimeToolsOptions
{
    GetNowLocalOptions = new GetNowLocalOptions
    {
        IncludeTimezoneParameter = true,
        DefaultLocalTimezoneIdIfNoneIsProvided = "UTC"
    }
});

RandomTools

Random tools provide random integer and random double generation.

Tool names

get_random_integer, get_random_double

Options

• GetRandomToolsOptions.GetRandomInteger (default: true)
• GetRandomToolsOptions.GetRandomDouble (default: true)
• GetRandomIntegerOptions.DefaultMin / GetRandomIntegerOptions.DefaultMax (defaults: 0 / 100)
• GetRandomDoubleOptions.DefaultMin / GetRandomDoubleOptions.DefaultMax (defaults: 0.0 / 1.0)

AIToolsFactory toolsFactory = new();
IList<AITool> tools = toolsFactory.GetRandomTools(new GetRandomToolsOptions
{
    GetRandomIntegerOptions = new GetRandomIntegerOptions
    {
        DefaultMin = 1,
        DefaultMax = 101
    },
    GetRandomDoubleOptions = new GetRandomDoubleOptions
    {
        DefaultMin = 0.5,
        DefaultMax = 10.0
    }
});

WeatherTools (OpenWeatherMap)

Weather tools use the OpenWeatherMap API and require an API key.

Tool names

get_weather_for_city

AIToolsFactory toolsFactory = new();
IList<AITool> tools = toolsFactory.GetWeatherTools(new OpenWeatherMapOptions
{
    ApiKey = "<openweathermap-api-key>",
    PreferredUnits = WeatherOptionsUnits.Metric
});

WebsiteTools

Website tools fetch the content of a page from a URL, optionally stripping HTML/JS/CSS and returning plain text.

Tool names

get_content_of_url

AIToolsFactory toolsFactory = new();
IList<AITool> tools = toolsFactory.GetWebsiteTools(new GetWebsiteToolsOptions
{
    GetContentOfPageOptions = new GetContentOfPageOptions { StripMarkup = true }
});

EmailTools

Email tools send emails through SMTP.

Tool names

send_email

Options

• EmailToolsOptions.Host (required)
• EmailToolsOptions.Port (default: 587)
• EmailToolsOptions.UseSecureConnection (default: true)
• EmailToolsOptions.Username and EmailToolsOptions.Password (optional, must be provided together)
• EmailToolsOptions.FromAddress (required)
• EmailToolsOptions.FromDisplayName (optional)
• EmailToolsOptions.ConfineSendingToTheseDomains (optional)

AIToolsFactory toolsFactory = new();
IList<AITool> tools = toolsFactory.GetEmailTools(new GetEmailToolsOptions
{
    EmailToolsOptions = new EmailToolsOptions
    {
        Host = "smtp.example.com",
        Port = 587,
        UseSecureConnection = true,
        Username = "<smtp-username>",
        Password = "<smtp-password>",
        FromAddress = "agent@example.com",
        FromDisplayName = "Agent",
        ConfineSendingToTheseDomains = ["example.com"]
    }
});

Warning

Store SMTP credentials in secure configuration or secret stores and do not hardcode them. If possible, set EmailToolsOptions.ConfineSendingToTheseDomains so the tool can only send to approved recipient domains.