FieldCure.Ai.Execution 0.4.1

FieldCure.Ai.Execution

Agent loop and sub-agent execution engine for autonomous LLM tool-use workflows.

Components

Quick Start

AgentLoop (standalone)

using FieldCure.Ai.Execution;
using FieldCure.Ai.Providers;
using FieldCure.Ai.Providers.Models;

var loop = new AgentLoop();

var result = await loop.RunAsync(new AgentLoopContext
{
    Provider = myProvider,         // IAiProvider instance
    SystemPrompt = "You are helpful.",
    UserPrompt = "Summarize this document.",
    Tools = [searchTool, readTool], // IAssistTool list
    MaxRounds = 10,
});

Console.WriteLine(result.Summary);   // Last assistant message
Console.WriteLine(result.Status);    // Completed, Truncated, MaxRoundsReached, Failed
Console.WriteLine(result.Messages);  // Full conversation for audit logging

SubAgentExecutor

using FieldCure.Ai.Execution;
using FieldCure.Ai.Execution.Models;

var executor = new SubAgentExecutor(
    agentLoop: new AgentLoop(),
    resolveProvider: model => ProviderFactory.Create(model),
    resolveTools: (servers, allowed, ct) => BootstrapMcpTools(servers, allowed, ct)
);

var result = await executor.ExecuteAsync(new SubAgentRequest
{
    Prompt = "Research competitor news and write a report.",
    McpServers = ["builtin_essentials"],
    AllowedTools = ["http_request"],
    MaxRounds = 10,
    Timeout = TimeSpan.FromMinutes(2),
    ContextHints = new Dictionary<string, string>
    {
        [ContextHintKeys.KbId] = "my-kb-uuid",  // RAG kb_id propagation
    },
});

Console.WriteLine(result.Report);   // Sub-agent's final report
Console.WriteLine(result.Status);   // Completed, Truncated, TimedOut, MaxRoundsReached, Failed

Status values

Note: when the context guard forces a final summary round (see MaxContextChars), the terminating response is classified as Completed even if IsTruncated would otherwise flip it — the guard asked for a summary on purpose, so the partial marker doesn't apply.

Tool execution order

Within a single round, AgentLoop executes the model's tool_use blocks sequentially (foreach over response.ToolCalls). Parallel dispatch of independent tool calls is not a responsibility of this package — callers that need it (e.g., AssistStudio's ChatPanel for delegate_task fan-out) implement it at their own level on top of SubAgentExecutor.

Design Principles

• AgentLoop is pure - no timeout, no retry, no MCP. Just CancellationToken.
• Timeout is the caller's responsibility (CancelAfter + catch OperationCanceledException).
• Retry is the caller's responsibility (wrap IAiProvider or handle externally).
• MCP bootstrapping stays in the consumer (Runner, AssistStudio Core).
• ContextHints are resolved by SubAgentExecutor into system prompt text. AgentLoop never sees them.

Dependencies

• FieldCure.Ai.Providers (IAiProvider, IAssistTool, AiRequest, AiResponse, ChatMessage)

License

MIT