LevelUp.Strategos.Agents 2.8.0

Strategos.Agents

Microsoft Agent Framework integration for Strategos. Provides abstractions for LLM-powered workflow steps with conversation continuity and streaming responses.

Installation

dotnet add package LevelUp.Strategos.Agents

Features

Agent Steps

Build an IAgentStep<TState, TResult> with the fluent builder (post-DR-11 two-arity contract). WithSystemPrompt, WithUserPrompt, and WithApplyResult are required; missing any throws AGAG001 at Build():

using Strategos.Agents;
using Strategos.Steps;

var step = new AgentStepBuilder<DocumentState, DocumentAnalysis>()
    .WithSystemPrompt(_ => "You are a document analyst. Extract key insights.")
    .WithUserPrompt(s => s.DocumentText)
    .WithApplyResult((state, result, _) =>
        Task.FromResult(new StepResult<DocumentState>(state with { Analysis = result })))
    .WithTool(summarizeFunction)
    .ConfigureChatClient(b => b.UseLogging(loggerFactory))
    .Build(chatClient);

var stepResult = await step.ExecuteAsync(state, context, ct);

Tool Sources

Beyond per-call WithTool, register IToolSource ports that resolve their AIFunctions lazily on first execution. The in-process AgentToolSource reflects [AgentTool]-annotated methods (no external dependency); the McpToolSource (in Strategos.Agents.Mcp) discovers tools from a remote MCP server. Sources merge after WithTool tools, in registration order:

using Strategos.Agents;
using Strategos.Agents.Mcp;

var step = new AgentStepBuilder<DocumentState, DocumentAnalysis>()
    .WithSystemPrompt(_ => "Use the available tools.")
    .WithUserPrompt(s => s.DocumentText)
    .WithApplyResult((state, result, _) =>
        Task.FromResult(new StepResult<DocumentState>(state with { Analysis = result })))
    .WithToolSource(AgentToolSource.FromObject(new MyLocalSkills()))
    .WithToolSource(McpToolSource.ForHttpEndpoint(
        new Uri("https://tools.example.com/mcp"), TimeSpan.FromSeconds(30)))
    .Build(chatClient);

Conversation Continuity

Enable per-agent conversation threads for context retention:

public record MyState : IWorkflowState, IConversationalState
{
    public Guid WorkflowId { get; init; }
    public ImmutableDictionary<string, string> SerializedThreads { get; init; }
        = ImmutableDictionary<string, string>.Empty;

    public IConversationalState WithSerializedThread(string agentType, string thread)
        => this with { SerializedThreads = SerializedThreads.SetItem(agentType, thread) };
}

Streaming Responses

Register an IStreamingHandler with WithStreaming(...) to observe tokens as they arrive. Streaming is an observability side-channel — the terminal typed result contract is unchanged (tokens fire before ApplyResult runs):

var step = new AgentStepBuilder<DocumentState, DocumentAnalysis>()
    .WithSystemPrompt(_ => "You are a document analyst.")
    .WithUserPrompt(s => s.DocumentText)
    .WithApplyResult((state, result, _) =>
        Task.FromResult(new StepResult<DocumentState>(state with { Analysis = result })))
    .WithStreaming(myStreamingHandler) // IStreamingHandler
    .Build(chatClient);

Diagnostics

Strategos.Agents throws typed AgentException subclasses keyed by short diagnostic identifiers (AGAG001..AGAG009). The identifiers are part of the public contract — catch on the exception type, branch on exception.Diagnostic, and forward the code to your telemetry pipeline. The literals live in Strategos.Agents.Diagnostics.AgentDiagnostics.

AGAG008 is reserved (pending a build-time validation case) and is not currently emitted.

Configuration

services.AddStrategosAgents()
    .AddConversationThreadManager<MyThreadManager>()
    .AddStreamingCallback<WebSocketStreamingCallback>();

AddStreamingCallback/IStreamingCallback wire the legacy specialist-agent streaming surface. For AgentStep streaming, use .WithStreaming(IStreamingHandler) — see Streaming Responses.

Core Abstractions

Documentation

• Agent Selection Guide - Configuring agents in workflows
• Agents API Reference - Complete API documentation

License

MIT