agentrs 0.1.1

AgentRs .NET

AgentRs is a .NET port of the Rust agentrs SDK. It keeps the same core programming model: provider-agnostic LLM abstractions, composable tools, MCP integration, pluggable memory, multi-agent orchestration, and YAML-driven runtime loading.

The current port preserves the main semantics of the Rust workspace while expressing them with idiomatic C# and .NET APIs such as Task, IAsyncEnumerable<T>, records, and nullable reference types.

Solution Layout

AgentRs.sln
├── src/AgentRs.Core           # Contracts, shared DTOs, errors, streaming helpers, test doubles
├── src/AgentRs.Providers      # OpenAI, Azure OpenAI, Anthropic, Gemini, Ollama providers
├── src/AgentRs.Tools          # Tool registry, built-in tools, custom tool helpers
├── src/AgentRs.Generators     # Roslyn generator for [AgentTool] wrappers
├── src/AgentRs.Mcp            # MCP protocol, stdio/http client, tool adapter
├── src/AgentRs.Memory         # In-memory, sliding window, token-aware, vector, Redis memory
├── src/AgentRs.Agents         # Agent builder, runner, loop strategies
├── src/AgentRs.Multi          # Multi-agent orchestration, routing, event bus, shared memory
├── src/AgentRs.Configuration  # YAML runtime and agent loading
├── src/AgentRs                # Facade assembly with global imports
├── examples/AgentRs.Examples  # Ported examples and YAML configs
└── tests/AgentRs.Tests        # Ported integration tests

Ported Concepts

• LlmProvider → ILlmProvider
• Tool → ITool
• Memory → IMemory
• Agent → IAgent
• Message, CompletionRequest, CompletionResponse, ToolOutput, AgentOutput kept as shared DTOs in AgentRs.Core
• ReAct, chain-of-thought, and plan-and-execute loops are available in AgentRs.Agents
• Sequential, parallel, supervisor, and graph orchestration are available in AgentRs.Multi
• YAML runtime loading is available in AgentRs.Configuration

Provider Support

• OpenAiProvider
• AzureOpenAiProvider
• AnthropicProvider
• GeminiProvider
• OllamaProvider

Current fidelity notes from the Rust implementation are preserved:

• OpenAI and Azure OpenAI support request/response mapping and SSE streaming
• Anthropic and Gemini support non-streaming completion only
• Ollama wraps the OpenAI-compatible implementation using its local endpoint

Built-in Tools

• CalculatorTool
• WebFetchTool
• WebSearchTool
• FileReadTool
• FileWriteTool
• BashTool
• PythonTool

Custom tools can be registered through either DelegateTool<TInput> or the source-generated [AgentTool] path.

Custom Tools

The port now supports a Rust #[tool]-style workflow through AgentToolAttribute in src/AgentRs.Tools/AgentToolAttribute.cs and the generator in src/AgentRs.Generators/AgentToolGenerator.cs.

Use [AgentTool] on a static method that:

• returns Task<T> or ValueTask<T>
• accepts one required input DTO parameter
• can optionally accept ToolContext and/or CancellationToken

Example:

using AgentRs.Tools;

[AgentTool("reverse_text", "Reverse a string")]
public static Task<string> ReverseTextAsync(ReverseInput input, CancellationToken cancellationToken = default)
    => Task.FromResult(new string(input.Text.Reverse().ToArray()));

public sealed record ReverseInput(string Text);

The generator emits a wrapper named <MethodName>Tool, so the example above becomes ReverseTextAsyncTool and can be registered like any other ITool:

var agent = Agent.Builder()
    .Llm(llm)
    .Tool(ReverseTextAsyncTool.New())
    .Build();

DelegateTool<TInput> remains available as a manual fallback when a generated wrapper is not desired.

Streaming

IAgent.StreamRunAsync now drives real provider streaming through ILlmProvider.StreamAsync instead of replaying a final response.

The event stream can emit:

• AgentEvent.Thinking
• AgentEvent.Token
• AgentEvent.ToolCall
• AgentEvent.ToolResult
• AgentEvent.Done

This preserves the Rust-style behavior where streamed tool-call deltas are reconstructed into tool invocations during the ReAct loop.

Example:

await foreach (var evt in agent.StreamRunAsync("Say hello"))
{
    switch (evt)
    {
        case AgentEvent.Token(var value):
            Console.Write(value);
            break;
        case AgentEvent.Done:
            Console.WriteLine();
            break;
    }
}

YAML Loading

AgentRs.Configuration.YamlConfiguration exposes:

• LoadAgentFromYamlAsync
• LoadAgentFromYamlStringAsync
• LoadMultiAgentFromYamlAsync
• LoadMultiAgentFromYamlStringAsync
• LoadRuntimeFromYamlAsync
• LoadRuntimeFromYamlStringAsync

Supported YAML runtime shapes mirror the Rust project examples under C:\projects\AgentAI\rust\agentrs\examples\configs.

Examples

examples/AgentRs.Examples contains .NET equivalents for the Rust examples, including YAML configs under examples/AgentRs.Examples/configs.

Run them with:

dotnet run --project examples/AgentRs.Examples -- simple-agent
dotnet run --project examples/AgentRs.Examples -- tool-use
dotnet run --project examples/AgentRs.Examples -- streaming
dotnet run --project examples/AgentRs.Examples -- multi-agent
dotnet run --project examples/AgentRs.Examples -- mcp-integration
dotnet run --project examples/AgentRs.Examples -- yaml-single-agent
dotnet run --project examples/AgentRs.Examples -- yaml-multi-agent
dotnet run --project examples/AgentRs.Examples -- yaml-runtime

The mcp-integration example uses the local stub server from tests/AgentRs.McpTestServer.

Build And Test

dotnet build AgentRs.sln
dotnet test tests/AgentRs.Tests/AgentRs.Tests.csproj

NuGet

The publishable facade package is agentrs.net.

Pack it with:

dotnet pack src/AgentRs/AgentRs.csproj -c Release -o artifacts/nuget

The package bundles the facade assembly, the supporting AgentRs.* runtime assemblies, XML docs, the README.md, and the AgentTool source generator analyzer so consumers can install a single NuGet package.

Notes

• The workspace targets net10.0 because the installed SDK in this environment does not provide the net9.0 template target.
• The generated solution file is AgentRs.sln; the default slnx file from template creation is not required by the build.
• MCP stdio spawning supports quoted executable paths for local test-server and example scenarios.