feat(agentic): Phase 2 — IAgent + native tool-calling AgentExecutor (#1544)

Foundational single-model agent for the multi-agent layer:

- IAgent<T>: uniform named/described/RunAsync contract that both leaf agents and coordinators (supervisor/swarm) implement, so agents nest and any agent can be surfaced as a tool to another.

- AgentExecutor<T>: drives an IChatClient<T> in a provider-native function-calling loop (call model -> run requested tools -> feed ToolResult messages back -> repeat) until a final answer or the iteration cap. Replaces the legacy prompt-parsed ReAct loop. Aggregates token usage; returns the full transcript.

- AgentExecutorOptions (nullable defaults: name/description/system-prompt/max-iterations/sampling/tool-choice) + AgentRunResult (FinalText/Messages/Iterations/Completed/Usage).

- Tests (10, green net10.0 + net471) via a deterministic ScriptedChatClient + RecordingTool: plain answer, tool round-trip with arg + result-passthrough assertions, system-prompt prepend, tool advertisement on/off, iteration-cap -> Completed=false, usage aggregation, empty/null guards. No null-forgiving.

Stacked on Phase 0 (#1545); part of epic #1544 (Phase 2).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: franklinic

src/Agentic/Agents/AgentExecutor.cs

@@ -0,0 +1,153 @@
+using AiDotNet.Agentic.Models;
+using AiDotNet.Agentic.Tools;
+
+// Disambiguate from the legacy AiDotNet.PromptEngineering.Templates.ChatMessage (global using).
+using ChatMessage = AiDotNet.Agentic.Models.ChatMessage;
+
+namespace AiDotNet.Agentic.Agents;
+
+/// <summary>
+/// A single-model agent that drives an <see cref="IChatClient{T}"/> in a native tool-calling loop:
+/// it calls the model, runs any tools the model requests, feeds the results back, and repeats until the
+/// model returns a final answer (or the iteration cap is hit).
+/// </summary>
+/// <typeparam name="T">The numeric type shared with the underlying <see cref="IChatClient{T}"/>.</typeparam>
+/// <remarks>
+/// <para>
+/// This replaces the legacy prompt-parsed ReAct loop with provider-native function calling: tool requests
+/// arrive as structured <see cref="ToolCallContent"/> rather than scraped from prose, and tool results go
+/// back as <see cref="ChatRole.Tool"/> messages. It is the leaf <see cref="IAgent{T}"/> that the multi-agent
+/// coordinators (supervisor/swarm) compose.
+/// </para>
+/// <para><b>For Beginners:</b> Give it a model and (optionally) a toolbox. Ask it something. Internally it
+/// loops: "model, here's the task and your tools" → if the model asks to use a tool, the executor runs it
+/// and tells the model the result → repeat → until the model just answers. You get that final answer back,
+/// plus the full transcript of what happened.
+/// </para>
+/// </remarks>
+public sealed class AgentExecutor<T> : IAgent<T>
+{
+    private readonly IChatClient<T> _client;
+    private readonly ToolCollection _tools;
+    private readonly AgentExecutorOptions _options;
+
+    /// <summary>
+    /// Initializes a new <see cref="AgentExecutor{T}"/>.
+    /// </summary>
+    /// <param name="client">The chat model the agent drives.</param>
+    /// <param name="tools">The tools the agent may use. <c>null</c> means the agent has no tools.</param>
+    /// <param name="options">Agent settings. <c>null</c> uses defaults.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="client"/> is <c>null</c>.</exception>
+    public AgentExecutor(IChatClient<T> client, ToolCollection? tools = null, AgentExecutorOptions? options = null)
+    {
+        Guard.NotNull(client);
+        _client = client;
+        _tools = tools ?? new ToolCollection();
+        _options = options ?? new AgentExecutorOptions();
+    }
+
+    /// <inheritdoc/>
+    public string Name =>
+        _options.Name is { } name && name.Trim().Length > 0 ? name : "agent";
+
+    /// <inheritdoc/>
+    public string Description => _options.Description ?? string.Empty;
+
+    /// <summary>
+    /// Runs the agent against a single user message.
+    /// </summary>
+    /// <param name="userMessage">The user's request.</param>
+    /// <param name="cancellationToken">Token used to cancel the run.</param>
+    /// <returns>A task producing the agent's <see cref="AgentRunResult"/>.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="userMessage"/> is <c>null</c>.</exception>
+    public Task<AgentRunResult> RunAsync(string userMessage, CancellationToken cancellationToken = default)
+    {
+        Guard.NotNull(userMessage);
+        return RunAsync(new[] { ChatMessage.User(userMessage) }, cancellationToken);
+    }
+
+    /// <inheritdoc/>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="messages"/> is <c>null</c>.</exception>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="messages"/> is empty.</exception>
+    public async Task<AgentRunResult> RunAsync(
+        IReadOnlyList<ChatMessage> messages,
+        CancellationToken cancellationToken = default)
+    {
+        Guard.NotNull(messages);
+        if (messages.Count == 0)
+        {
+            throw new ArgumentException("The conversation must contain at least one message.", nameof(messages));
+        }
+
+        var transcript = new List<ChatMessage>(messages.Count + 4);
+        var systemPrompt = _options.SystemPrompt;
+        if (systemPrompt is { } prompt && prompt.Trim().Length > 0)
+        {
+            transcript.Add(ChatMessage.System(prompt));
+        }
+
+        transcript.AddRange(messages);
+
+        var hasTools = _tools.Count > 0;
+        var requestOptions = new ChatOptions
+        {
+            Temperature = _options.Temperature,
+            MaxOutputTokens = _options.MaxOutputTokens,
+            Tools = hasTools ? _tools.GetDefinitions() : null,
+            ToolChoice = hasTools ? (_options.ToolChoice ?? ToolChoiceMode.Auto) : null,
+        };
+
+        var maxIterations = _options.MaxIterations is { } configured && configured > 0
+            ? configured
+            : AgentExecutorOptions.DefaultMaxIterations;
+
+        var inputTokens = 0;
+        var outputTokens = 0;
+        var sawUsage = false;
+
+        for (var iteration = 1; iteration <= maxIterations; iteration++)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+
+            var response = await _client.GetResponseAsync(transcript, requestOptions, cancellationToken)
+                .ConfigureAwait(false);
+            transcript.Add(response.Message);
+
+            if (response.Usage is { } usage)
+            {
+                sawUsage = true;
+                inputTokens += usage.InputTokens;
+                outputTokens += usage.OutputTokens;
+            }
+
+            var toolCalls = response.Message.ToolCalls;
+            var wantsTools = response.FinishReason == ChatFinishReason.ToolCalls || toolCalls.Count > 0;
+
+            if (hasTools && wantsTools && toolCalls.Count > 0)
+            {
+                foreach (var call in toolCalls)
+                {
+                    cancellationToken.ThrowIfCancellationRequested();
+                    var toolMessage = await _tools.InvokeToToolMessageAsync(call, cancellationToken)
+                        .ConfigureAwait(false);
+                    transcript.Add(toolMessage);
+                }
+
+                continue;
+            }
+
+            return AgentRunResult.Finished(
+                response.Message.Text,
+                transcript,
+                iteration,
+                sawUsage ? new ChatUsage(inputTokens, outputTokens) : null);
+        }
+
+        var lastText = transcript.Count > 0 ? transcript[transcript.Count - 1].Text : string.Empty;
+        return AgentRunResult.Stopped(
+            lastText,
+            transcript,
+            maxIterations,
+            sawUsage ? new ChatUsage(inputTokens, outputTokens) : null);
+    }
+}

src/Agentic/Agents/AgentExecutorOptions.cs

@@ -0,0 +1,66 @@
+using AiDotNet.Agentic.Models;
+
+namespace AiDotNet.Agentic.Agents;
+
+/// <summary>
+/// Settings for an <see cref="AgentExecutor{T}"/>: identity, system prompt, the tool-loop budget, and the
+/// sampling knobs forwarded to each model call.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Every value is nullable and defaults to a sensible behavior when left <c>null</c>, following the
+/// library-wide options pattern (zero-config by default, fully overridable). The executor applies the
+/// documented defaults internally, so the common case is <c>new AgentExecutor&lt;float&gt;(client)</c>.
+/// </para>
+/// <para><b>For Beginners:</b> These are the dials for one agent. The most useful ones are
+/// <see cref="SystemPrompt"/> (the agent's standing instructions / persona) and <see cref="MaxIterations"/>
+/// (how many think→use-tool→think rounds it may take before it must answer).
+/// </para>
+/// </remarks>
+public sealed class AgentExecutorOptions
+{
+    /// <summary>
+    /// The default maximum number of model calls in a single run when <see cref="MaxIterations"/> is unset.
+    /// </summary>
+    public const int DefaultMaxIterations = 10;
+
+    /// <summary>
+    /// Gets or sets the agent's name (used by coordinators and when the agent is surfaced as a tool).
+    /// <c>null</c> or empty falls back to <c>"agent"</c>.
+    /// </summary>
+    public string? Name { get; set; }
+
+    /// <summary>
+    /// Gets or sets the agent's one-line specialty description. <c>null</c> falls back to an empty string.
+    /// </summary>
+    public string? Description { get; set; }
+
+    /// <summary>
+    /// Gets or sets the system prompt prepended to every run (the agent's standing instructions/persona).
+    /// <c>null</c> or whitespace means no system message is added.
+    /// </summary>
+    public string? SystemPrompt { get; set; }
+
+    /// <summary>
+    /// Gets or sets the maximum number of model calls in one run (each tool round costs one call).
+    /// <c>null</c> or a non-positive value uses <see cref="DefaultMaxIterations"/>. When the cap is reached
+    /// before a final answer, the run returns with <see cref="AgentRunResult.Completed"/> set to <c>false</c>.
+    /// </summary>
+    public int? MaxIterations { get; set; }
+
+    /// <summary>
+    /// Gets or sets the sampling temperature forwarded to each model call. <c>null</c> uses the connector default.
+    /// </summary>
+    public double? Temperature { get; set; }
+
+    /// <summary>
+    /// Gets or sets the per-call output-token cap forwarded to each model call. <c>null</c> uses the connector default.
+    /// </summary>
+    public int? MaxOutputTokens { get; set; }
+
+    /// <summary>
+    /// Gets or sets how eagerly the model may use the agent's tools when tools are present. <c>null</c> is
+    /// treated as <see cref="ToolChoiceMode.Auto"/>. Ignored when the agent has no tools.
+    /// </summary>
+    public ToolChoiceMode? ToolChoice { get; set; }
+}

src/Agentic/Agents/AgentRunResult.cs

@@ -0,0 +1,88 @@
+using AiDotNet.Agentic.Models;
+
+// Disambiguate from the legacy AiDotNet.PromptEngineering.Templates.ChatMessage (global using).
+using ChatMessage = AiDotNet.Agentic.Models.ChatMessage;
+
+namespace AiDotNet.Agentic.Agents;
+
+/// <summary>
+/// The outcome of an agent run: the final text answer, the full conversation transcript it produced,
+/// how many model calls it took, whether it finished cleanly, and the aggregate token usage.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <see cref="Messages"/> is the complete transcript the agent worked with (system prompt, the inbound
+/// conversation, every assistant turn, and every tool-result message), so a caller can inspect the
+/// agent's reasoning, persist the thread, or feed it into another agent. <see cref="Completed"/> is
+/// <c>false</c> only when the agent hit its iteration cap before producing a final (non-tool) answer.
+/// </para>
+/// <para><b>For Beginners:</b> After an agent runs, this is what you get back. <see cref="FinalText"/> is
+/// the answer most callers want; <see cref="Messages"/> is the full play-by-play if you want to see how it
+/// got there; <see cref="Completed"/> tells you whether it actually finished or ran out of allowed steps.
+/// </para>
+/// </remarks>
+public sealed class AgentRunResult
+{
+    private AgentRunResult(
+        string finalText,
+        IReadOnlyList<ChatMessage> messages,
+        int iterations,
+        bool completed,
+        ChatUsage? usage)
+    {
+        FinalText = finalText;
+        Messages = messages;
+        Iterations = iterations;
+        Completed = completed;
+        Usage = usage;
+    }
+
+    /// <summary>
+    /// Gets the agent's final text answer. When <see cref="Completed"/> is <c>false</c> this is the text of
+    /// the last message produced before the iteration cap was hit (possibly empty).
+    /// </summary>
+    public string FinalText { get; }
+
+    /// <summary>
+    /// Gets the complete conversation transcript the agent produced, including the system prompt (if any),
+    /// the inbound messages, every assistant turn, and every tool-result message.
+    /// </summary>
+    public IReadOnlyList<ChatMessage> Messages { get; }
+
+    /// <summary>
+    /// Gets the number of model calls the run made (each tool round is one call).
+    /// </summary>
+    public int Iterations { get; }
+
+    /// <summary>
+    /// Gets a value indicating whether the agent produced a final answer (<c>true</c>) or stopped because it
+    /// reached its iteration cap (<c>false</c>).
+    /// </summary>
+    public bool Completed { get; }
+
+    /// <summary>
+    /// Gets the aggregate token usage across every model call in the run, or <c>null</c> when no call
+    /// reported usage.
+    /// </summary>
+    public ChatUsage? Usage { get; }
+
+    /// <summary>
+    /// Creates a result for a run that produced a final answer.
+    /// </summary>
+    internal static AgentRunResult Finished(
+        string finalText,
+        IReadOnlyList<ChatMessage> messages,
+        int iterations,
+        ChatUsage? usage) =>
+        new(finalText, messages, iterations, completed: true, usage);
+
+    /// <summary>
+    /// Creates a result for a run that hit its iteration cap before producing a final answer.
+    /// </summary>
+    internal static AgentRunResult Stopped(
+        string lastText,
+        IReadOnlyList<ChatMessage> messages,
+        int iterations,
+        ChatUsage? usage) =>
+        new(lastText, messages, iterations, completed: false, usage);
+}

src/Agentic/Agents/IAgent.cs

@@ -0,0 +1,53 @@
+using AiDotNet.Agentic.Models;
+
+// Disambiguate from the legacy AiDotNet.PromptEngineering.Templates.ChatMessage, which is in scope
+// project-wide via a global using in AiModelBuilder.cs. The agentic subsystem uses the Models type.
+using ChatMessage = AiDotNet.Agentic.Models.ChatMessage;
+
+namespace AiDotNet.Agentic.Agents;
+
+/// <summary>
+/// A named, runnable agent: given a conversation, it produces a final answer (after optionally using
+/// tools and/or delegating to other agents along the way).
+/// </summary>
+/// <typeparam name="T">
+/// The numeric type shared with the underlying <see cref="IChatClient{T}"/> (e.g., <see cref="float"/>
+/// or <see cref="double"/>), so an agent and the model it drives agree on one tensor element type.
+/// </typeparam>
+/// <remarks>
+/// <para>
+/// This is the single abstraction the multi-agent layer composes. A leaf agent (<see cref="AgentExecutor{T}"/>)
+/// drives a chat model in a tool-calling loop; a coordinator (supervisor/swarm) is itself an
+/// <see cref="IAgent{T}"/> that routes work to other <see cref="IAgent{T}"/> members. Because the contract is
+/// uniform, agents nest: a supervisor can supervise supervisors, and any agent can be exposed to another as a
+/// callable tool.
+/// </para>
+/// <para><b>For Beginners:</b> An agent is a worker with a <see cref="Name"/> and a one-line
+/// <see cref="Description"/> of what it's good at. You hand it the conversation so far and it hands back a
+/// result. Whether it solved the task alone or quietly asked teammates for help is its own business — callers
+/// only see the final answer.
+/// </para>
+/// </remarks>
+public interface IAgent<T>
+{
+    /// <summary>
+    /// Gets the unique, stable name other agents and routers use to reference this agent.
+    /// </summary>
+    string Name { get; }
+
+    /// <summary>
+    /// Gets a short natural-language description of the agent's specialty, used by coordinators (and by
+    /// models, when the agent is surfaced as a tool) to decide when to route work here.
+    /// </summary>
+    string Description { get; }
+
+    /// <summary>
+    /// Runs the agent over the supplied conversation and returns its result.
+    /// </summary>
+    /// <param name="messages">The ordered conversation so far. Must be non-null and non-empty.</param>
+    /// <param name="cancellationToken">Token used to cancel the run.</param>
+    /// <returns>A task producing the agent's <see cref="AgentRunResult"/>.</returns>
+    Task<AgentRunResult> RunAsync(
+        IReadOnlyList<ChatMessage> messages,
+        CancellationToken cancellationToken = default);
+}