Class ToolCallPolicy

Namespace

LMKit.Agents.Tools

Assembly

LM-Kit.NET.dll

Configures per-turn policies that control how an agent may invoke registered tools.

public sealed class ToolCallPolicy

Inheritance

object

ToolCallPolicy

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

Example: Configuring an agent with different tool policies

This example demonstrates creating agents with various tool usage policies depending on the task requirements.

using LMKit.Agents;
using LMKit.Agents.Tools;
using LMKit.Model;

using var model = new LM("path/to/model.gguf");

// Default policy: let the model decide
var defaultPolicy = new ToolCallPolicy
{
    Choice = ToolChoice.Auto,
    MaxCallsPerTurn = 3
};

// Research policy: must use tools for data gathering
var researchPolicy = new ToolCallPolicy
{
    Choice = ToolChoice.Required,
    MaxCallsPerTurn = 5
};

// Creative policy: no external tools, pure generation
var creativePolicy = new ToolCallPolicy
{
    Choice = ToolChoice.None
};

// Build agents with these policies
var generalAgent = Agent.CreateBuilder()
    .WithModel(model)
    .WithToolPolicy(defaultPolicy)
    .Build();

var researchAgent = Agent.CreateBuilder()
    .WithModel(model)
    .WithToolPolicy(researchPolicy)
    .Build();

var creativeAgent = Agent.CreateBuilder()
    .WithModel(model)
    .WithToolPolicy(creativePolicy)
    .Build();

Example: Forcing a specific tool for workflow steps

This example shows how to force the agent to call a specific tool, which is useful in guided workflows where certain steps must always execute.

using LMKit.Agents;
using LMKit.Agents.Tools;
using LMKit.Model;

using var model = new LM("path/to/model.gguf");

// Step 1: Force the search tool first
var searchPolicy = new ToolCallPolicy
{
    Choice = ToolChoice.Specific,
    ForcedToolName = "web_search",
    MaxCallsPerTurn = 1
};

var searchAgent = Agent.CreateBuilder()
    .WithModel(model)
    .WithToolPolicy(searchPolicy)
    .WithTools(registry => registry.Register("web_search", new WebSearchTool()))
    .Build();

// The agent will always call web_search first
var result = await searchAgent.RunAsync("Find the latest news about AI regulations.");
Console.WriteLine(result.Content);

Remarks

ToolCallPolicy is a configuration object that specifies the rules governing tool usage during a single turn of agent execution. It allows you to control whether tools can be called, which specific tool must be called, and how many tool calls are permitted before the agent must produce a final response.

Policy Enforcement
This class defines the policy but does not enforce it directly. The agent execution runtime reads these settings and applies them during message processing. If you are building custom execution logic, you are responsible for honoring the policy.

Common Patterns

• Auto (default)Let the model decide whether to use tools based on the user's request.
• RequiredForce the model to use at least one tool, useful for data retrieval tasks.
• NoneDisable tools entirely for purely generative responses.
• SpecificForce the model to call a particular tool, useful for guided workflows.

Properties

Choice

Gets or sets the tool usage mode for this turn.

ForcedToolName

Gets or sets the name of the tool to force when Choice is Specific.

MaxCallsPerTurn

Gets or sets the maximum number of tool invocations allowed per turn.