Class AgentExecutor

Namespace: LMKit.Agents

Assembly: LM-Kit.NET.dll

Default executor for running agents using MultiTurnConversation.

The executor creates and manages a conversation context, applies the agent's configuration, handles the execution loop including tool calls and planning strategies, and produces execution results.

public sealed class AgentExecutor : IAgentExecutor, IMultiTurnConversation, IConversation, IDisposable

Inheritance: object

AgentExecutor

Implements: IAgentExecutor

IMultiTurnConversation

IConversation

IDisposable

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

Example: Execute a simple agent

using LMKit.Model;
using LMKit.Agents;
using System;
using System.Threading.Tasks;

LM model = LM.LoadFromModelID("llama-3.2-3b");

// Build an agent
Agent agent = new AgentBuilder()
    .WithModel(model)
    .WithPersona("Helpful Assistant")
    .WithInstruction("You are a helpful AI assistant that answers questions clearly.")
    .Build();

// Create executor and run
using var executor = new AgentExecutor();
AgentExecutionResult result = await executor.ExecuteAsync(agent, "What is machine learning?");

Console.WriteLine($"Status: {result.Status}");
Console.WriteLine($"Response: {result.Content}");

Example: Agent with tools

using LMKit.Model;
using LMKit.Agents;
using LMKit.Agents.Tools;
using System;
using System.Threading.Tasks;

public class MathTools
{
    [LMFunction("calculate", "Perform a mathematical calculation")]
    public double Calculate(double a, double b, string operation)
    {
        return operation switch
        {
            "add" => a + b,
            "multiply" => a * b,
            _ => 0
        };
    }
}

LM model = LM.LoadFromModelID("llama-3.2-3b");

var tools = new ToolRegistry();
tools.Register(new MathTools());

Agent agent = new AgentBuilder()
    .WithModel(model)
    .WithPersona("Math Assistant")
    .WithTools(tools)
    .Build();

using var executor = new AgentExecutor();
var result = await executor.ExecuteAsync(agent, "What is 15 multiplied by 7?");
Console.WriteLine(result.Content);

Example: Multi-turn conversation with agent

using LMKit.Model;
using LMKit.Agents;
using LMKit.TextGeneration;
using System;
using System.Threading.Tasks;

LM model = LM.LoadFromModelID("llama-3.2-3b");

Agent agent = new AgentBuilder()
    .WithModel(model)
    .WithPersona("Tutor")
    .WithInstruction("You are a patient tutor helping students learn.")
    .Build();

// Create conversation for multi-turn interaction
using var conversation = new MultiTurnConversation(model);
using var executor = new AgentExecutor(conversation);

// First turn
var result1 = await executor.ExecuteAsync(agent, "Explain what a variable is in programming.");
Console.WriteLine($"Turn 1: {result1.Content}");

// Second turn (conversation history is maintained)
var result2 = await executor.ExecuteAsync(agent, "Can you give me an example?");
Console.WriteLine($"Turn 2: {result2.Content}");

Example: Subscribe to tool invocation events

using LMKit.Agents;
using System;

using var executor = new AgentExecutor();

// Subscribe to events on the executor (NOT on executor.Conversation)
executor.BeforeToolInvocation += (sender, e) =>
{
    Console.WriteLine($"About to call tool: {e.ToolName}");
};

executor.AfterToolInvocation += (sender, e) =>
{
    Console.WriteLine($"Tool {e.ToolName} completed");
};

var result = await executor.ExecuteAsync(agent, "Search for AI news");

Remarks

Execution Flow

Create or reuse a MultiTurnConversation with the agent's model.
Apply the agent's identity as the system prompt.
Initialize the planning handler based on the agent's strategy.
Copy tools from the agent's capabilities to the conversation.
Configure memory and tool policy from the agent.
Execute the planning loop until complete or max iterations reached.
Return an AgentExecutionResult with the outcome.

Planning Strategies
The executor supports multiple planning strategies (None, ChainOfThought, ReAct, Reflection, etc.) configured via the agent's Planning property.

Conversation Interface
This class implements IMultiTurnConversation, providing direct access to conversation features (tools, memory, chat history, events) through a unified API. Users should subscribe to events on this class rather than accessing the underlying conversation directly.

Thread Safety
This class is not thread-safe. Create separate executor instances for concurrent execution.

Constructors

AgentExecutor()

Initializes a new instance of the AgentExecutor class.

A new conversation will be created on first execution using the agent's model.

AgentExecutor(MultiTurnConversation)

Initializes a new instance of the AgentExecutor class with an existing conversation.

Use this constructor for multi-turn agent interactions where you want to maintain conversation history across executions.

Properties

ChatHistory: The full chat history of this conversation (system, user, assistant, and tool messages).

ContextRemainingSpace: Remaining token budget currently available in the context window.

ContextSize: Total token context size for this conversation.

DefaultOptions: Gets or sets the default execution options used when none are specified.

MaximumCompletionTokens: Defines the maximum number of tokens permitted for the assistant completion per turn. Set to -1 to remove the cap (subject to model/context limits).

MaximumRecallTokens

Maximum number of tokens recalled from Memory per turn.

Defaults to ContextSize / 4. The effective value is automatically capped to at most ContextSize / 2.

Memory

Long-term memory store used to recall relevant context across turns.

Assign an AgentMemory implementation to enable retrieval of relevant text partitions. Retrieved snippets are injected as hidden context up to MaximumRecallTokens.

Model: Gets the LM instance associated with this conversation. Useful for inspecting capabilities (e.g., tool-calls, reasoning support).

PlanningContext: Gets the current planning context, if execution is in progress.

ReasoningLevel

Controls how (and whether) intermediate "reasoning"/"thinking" content is produced and/or exposed.

Use None to fully disable reasoning. Higher levels hint the model to allocate more budget to chain-of-thought style tokens when the model supports it. Actual behavior depends on model and chat template capabilities.

Suggested semantics:

Level	Intended behavior
None	No reasoning tokens requested or exposed.
Low	Minimal reasoning; terse scratch space when helpful.
Medium	Balanced reasoning (default when enabled).
High	Maximize reasoning depth; may trade off speed.

RepetitionPenalty: A RepetitionPenalty specifying rules that discourage repeating recent n-grams/tokens. Typically disabled automatically when strict Grammar-like constraints are in use.

SamplingMode: A TokenSampling object specifying the sampling strategy followed during text completion (e.g., temperature, top-p, top-k, dynamic sampling).

Skills

Registry of Agent Skills available to this conversation.

Skills provide modular capabilities with specialized knowledge and workflows, following the Agent Skills specification.

StopSequences: Specifies sequences that cause generation to stop immediately when encountered. Matching stop sequences are not included in the final output.

SystemPrompt: Gets or sets the system prompt that is applied to the model before processing the user's request. Set this before the first user message for deterministic behavior across the session.

ToolPolicy

Per-turn tool-calling policy used by the conversation runtime.

Controls whether tools are allowed, required, disabled, or whether a specific tool must be used on the current turn.

Tools

Registry of model-callable tools available to this conversation.

Register tools before the first user turn so they are advertised to the model. Tool invocation requires a model that supports tool calls.

Methods

ClearHistory(): Clear the entire conversation: removes all messages and resets internal state.

Dispose()

Releases all resources used by this executor.

If the executor owns the conversation (created internally), the conversation is disposed.

Execute(Agent, string, AgentExecutionOptions, CancellationToken): Executes a task synchronously with the specified agent and options.

Execute(Agent, string, CancellationToken): Executes a task synchronously with the specified agent.

ExecuteAsync(Agent, string, AgentExecutionOptions, CancellationToken): Executes a task asynchronously with the specified agent and options.

ExecuteAsync(Agent, string, CancellationToken): Executes a task asynchronously with the specified agent.

Submit(Message, CancellationToken): Submits a message to the text generation model and returns the result.

Submit(string, CancellationToken): Submits a prompt to the text generation model and returns the result.

SubmitAsync(Message, CancellationToken): Asynchronously submits a message to the text generation model and returns the result.

SubmitAsync(string, CancellationToken): Asynchronously submits a prompt to the text generation model and returns the result.

Events

AfterTextCompletion: Event triggered following the execution of a text completion. Use to inspect the final assistant output and optionally influence post-processing.

AfterTokenSampling: Event triggered just after the generation of a token. Enables detailed modifications to be made to the token selection process via AfterTokenSamplingEventArgs.

AfterToolInvocation: Fired after a tool invocation finishes (or when it was cancelled/errored).

BeforeTokenSampling: Event triggered just before the generation of a token. Allows for precise adjustments to the token sampling process via BeforeTokenSamplingEventArgs.

BeforeToolInvocation: Fired before a tool invocation. Handlers may cancel the call.

MemoryRecall

Fired when one or more memory partitions are recalled for this turn.

Subscribers may inspect the recalled content and optionally cancel injection by setting Cancel to true.