ArmyAnt

ArmyAnt is a layered .NET 10 experimental agent runtime for building both single-agent and multi-agent workflows without coupling the core architecture to any specific LLM provider.

The repository is organized around one core idea: keep public contracts and runtime behavior provider-agnostic, then isolate provider-specific code in a dedicated integration layer. In the current implementation, Microsoft Agent Framework and Microsoft.Extensions.AI dependencies are confined to the MAF integration and demo edge of the system.

Current Status

ArmyAnt has completed the M0-M6 milestones tracked in memory/plan.md, including:

• solution and layering foundation
• public contracts and builder entry points
• core planning, protocol, and task-board state machines
• single-agent runtime
• multi-agent orchestration runtime
• file-system persistence
• MAF-based integration and executable demos
• generic colony task-graph runtime with fan-out/fan-in scheduling

Recent verification completed in this repository:

• unit tests: 283/283 passing
• Demo.Colony: verified end-to-end with reviewer final report returned as the final user-visible response

Architecture

ArmyAnt uses a strict layered design:

1. Abstractions Public contracts, interfaces, and data models.
2. Core Pure policies and state machines such as todo/task workflows, protocol correlation, prompt layering, and skill metadata parsing.
3. Runtime Single-agent execution loop, tool invocation pipeline, context management, and transcript recording.
4. Orchestration Multi-agent colony scheduling, task graph coordination, subagent isolation, and team protocol routing.
5. Integrations Provider-specific adapters. The current implementation is Microsoft Agent Framework based.
6. Demo Executable samples that assemble the system and show the runtime behavior.

Provider isolation is enforced in Directory.Build.targets: only ArmyAnt.Integrations.Maf and ArmyAnt.Demo may reference Microsoft.Agents.* or Microsoft.Extensions.AI.* packages.

Solution Layout

Source Projects

• src/ArmyAnt.Abstractions Contracts for agents, colonies, planning, messaging, protocols, transcripts, skills, stores, and hosting.
• src/ArmyAnt.Core Provider-agnostic policies and state machines, including prompt layering, context compaction, skill parsing, task board logic, and protocol correlation.
• src/ArmyAnt.Runtime Single-agent runtime assembly and execution pipeline.
• src/ArmyAnt.Orchestration Multi-agent runtime, including ColonyCoordinator, ColonyHarness, TaskBoardCoordinator, SubagentRunner, and structured output parsing.
• src/ArmyAnt.Persistence.FileSystem File-backed implementations of the persistence abstractions.
• src/ArmyAnt.Integrations.Maf Microsoft Agent Framework integration layer and colony builder.
• src/ArmyAnt.Extensions.Worktrees Reserved extension seam for git worktree related capabilities.
• src/ArmyAnt.Demo Console demo entry point with single-agent and colony scenarios.

Tests and Documentation

• tests/ArmyAnt.Tests.Unit Unit coverage across contracts, core logic, orchestration, and persistence.
• tests/ArmyAnt.Tests.Integration Cross-layer integration coverage.
• docs/reference-matrix.md Project reference matrix and layering rules.
• docs/colony-runtime-target-model.md Target design for the generic colony runtime.
• reference/agent_workflow_design Design references that guide implementation decisions.
• memory/plan.md Execution plan and audit log for the project milestones.

Key Capabilities

Single-Agent Runtime

• profile-driven agent execution
• isolated tool registration and invocation
• transcript and todo persistence via store abstractions
• provider-agnostic runtime orchestration

Generic Colony Runtime

• task-graph-based scheduling instead of hard-coded role stages
• role-targeted and agent-targeted task routing
• fan-out and fan-in execution patterns
• task leasing, retries, failure handling, and dependency unlocking
• structured planner output via task_plan_submission JSON
• structured worker/scout/reviewer output via task_execution_result JSON
• final response prioritization: structuredOutputs.final_report -> final-report.md -> internal task summary fallback

Persistence and Extensibility

• file-backed message, todo, task, transcript, and skill stores
• explicit integration seam for alternative providers
• extension seam for worktree-based or future sandboxed execution features

Build Requirements

• .NET SDK with net10.0 support
• Windows, Linux, or macOS shell capable of running dotnet CLI
• optional: Anthropic-compatible credentials for real provider-backed demo runs

Repository-wide build defaults are defined in Directory.Build.props:

• TargetFramework: net10.0
• LangVersion: latest
• Nullable: enable
• TreatWarningsAsErrors: true

Getting Started

Restore

dotnet restore ArmyAnt.slnx

Build

dotnet build ArmyAnt.slnx

Run Unit Tests

dotnet test .\tests\ArmyAnt.Tests.Unit\ArmyAnt.Tests.Unit.csproj

Run All Tests

dotnet test ArmyAnt.slnx

Running the Demo

The executable demo lives in src/ArmyAnt.Demo/Program.cs and supports two modes.

Demo.SingleAgent

dotnet run --project .\src\ArmyAnt.Demo -- single

This assembles a Scout agent with three demo tools:

• get_datetime
• list_files
• read_file

Demo.Colony

dotnet run --project .\src\ArmyAnt.Demo -- colony

This assembles a four-role colony:

• Planner
• Scout
• Worker
• Reviewer

The current demo flow is task-graph driven:

1. Planner emits a structured task plan.
2. Scout and Worker run as parallel fan-out tasks.
3. Reviewer performs fan-in aggregation and emits the final report.
4. ColonyHarness returns the reviewer final report as the final response when available.

Environment Variables

If no provider credentials are configured, the demo falls back to EchoChatClient.

To run against an Anthropic-compatible endpoint, configure:

• ANTHROPIC_API_KEY
• ANTHROPIC_MODEL
• ANTHROPIC_BASE_URL

Optional diagnostics:

• ARMYANT_DEBUG_CHAT_RESPONSE=1

Design Notes

• Public contracts and core runtime layers do not depend on Microsoft Agent Framework types.
• Structured outputs are parsed in orchestration, not in provider adapters.
• Demo-specific prompting is kept in the demo layer; scheduler behavior stays generic.
• The file-system persistence layer implements abstractions only and does not pull runtime logic downward.

License

This project is licensed under the MIT License. See LICENSE.