Legacy .NET to Agent-Native: A Zero-Rewrite Migration Playbook

Introduction

Enterprise modernization does not always require replacing an existing application. Many organizations operate business-critical .NET systems that contain years of validated business rules, operational knowledge, integration contracts, and regulatory controls. Rewriting these systems to accommodate agentic AI introduces substantial cost and operational risk, particularly when the existing application continues to support essential business processes.

A more controlled approach is to preserve the legacy application while introducing an integration layer that allows AI agents to interact with approved business capabilities. This architecture can be described as an agent-native modernization strategy: existing applications remain responsible for their established business operations, while an agent runtime interprets goals, selects permitted capabilities, coordinates workflows, and requests execution through explicit interfaces.

Agent-native modernization is the process of making existing software capabilities accessible to governed AI agents through stable interfaces, controlled execution, and observable workflows without requiring a complete application rewrite.

For organizations using .NET Framework, ASP.NET MVC, Windows Communication Foundation (WCF), SOAP services, or older REST APIs, this strategy creates a practical path toward AI-assisted operations. The objective is not to turn every legacy component into an autonomous agent. It is to make existing business capabilities safely available to systems that can reason about tasks and coordinate multiple operations.

This playbook presents an incremental architecture using facade adapters, ASP.NET Core, OpenAPI, Microsoft Semantic Kernel, and a controlled agent runtime. It focuses on preserving existing behavior, limiting the migration surface, and establishing measurable operational safeguards.

Industry Background

Legacy .NET applications frequently operate in environments where modernization must accommodate long-lived dependencies. A manufacturing system might rely on WCF services hosted on IIS, an insurance platform might expose SOAP endpoints, and an internal business application might combine ASP.NET MVC controllers with SQL Server stored procedures.

These systems can continue to provide business value even when their interfaces are inconvenient for modern automation. Their limitations usually concern integration, discoverability, workflow coordination, and operational flexibility rather than the validity of their underlying business rules.

Agentic AI introduces a different interaction model. Traditional integrations generally execute predefined sequences of requests. An agent-based workflow can interpret a natural-language objective, select from available tools, inspect results, and determine an appropriate next action within configured constraints.

However, an agent cannot safely use an enterprise application simply because the application has a network endpoint. It needs a well-defined contract, reliable error semantics, authorization boundaries, and predictable execution behavior.

The architectural challenge is therefore to bridge two different models: established transactional software and probabilistic reasoning systems. The legacy application should retain responsibility for deterministic business rules, while the agent layer should coordinate tasks and interpret information without becoming an uncontrolled replacement for the system of record.

The Business Problem

A typical enterprise modernization project encounters several interconnected problems.

Interface incompatibility: Older applications may expose SOAP operations, WCF contracts, proprietary service methods, or tightly coupled MVC controllers. These interfaces are not necessarily suitable for direct consumption by modern AI orchestration frameworks.

Business logic duplication: Reimplementing existing rules inside an AI service creates multiple sources of truth. A loan eligibility rule, inventory reservation policy, or approval threshold could diverge between the legacy application and the new implementation.

Operational risk: Replacing a functioning system can introduce migration defects, downtime, data inconsistencies, and additional validation requirements.

Uncontrolled tool execution: An AI agent that can invoke business operations without explicit authorization, input validation, or approval requirements can create unacceptable financial, operational, and compliance risks.

Limited observability: Conventional application logs may record HTTP requests but fail to explain which agent initiated an operation, which tools were selected, what approval was granted, or why a workflow stopped.

A zero-rewrite strategy addresses these problems by changing the access architecture instead of replacing the business application. It does not mean zero engineering effort. Adapter development, API contracts, identity integration, testing, monitoring, and deployment controls remain necessary.

The key principle is straightforward: modernize the boundary before modernizing the business logic.

Understanding the Technology

Agent-native integration combines several architectural components. Each component has a distinct responsibility and should not be treated as interchangeable with the others.

A facade adapter is an integration boundary that presents a stable interface while hiding the implementation details of an underlying system. It can translate REST requests into SOAP messages, normalize legacy response formats, and expose a narrower set of operations than the original application supports.

Semantic Kernel provides software abstractions for integrating AI models with application functions, prompts, and orchestration workflows. Its plugin and function-calling capabilities can help expose approved business operations to an agent. The exact APIs and orchestration capabilities depend on the package version selected for the project.

The agent runtime is the execution environment that combines model interaction, tool selection, policy enforcement, workflow state, and operational controls. It should remain a separate architectural responsibility even when it is hosted in the same ASP.NET Core application as the facade adapter.

Core Architecture

A practical architecture separates the existing system, the compatibility boundary, and the AI orchestration layer.

1. Legacy .NET System

The existing application remains the system of record. It continues to own transactions, validation rules, persistence, and established business processes.

For example, a legacy order-management application may already expose operations for retrieving an order, checking inventory, validating a customer account, and submitting a shipment request. These operations should remain authoritative. The AI layer must not bypass them by writing directly to production tables or recreating their business rules.

If the legacy application uses WCF or SOAP, its existing service contracts can remain in place while a new adapter translates supported requests into the appropriate legacy operations.

2. Facade Adapter Layer

The facade adapter is the most important boundary in a zero-rewrite migration. It converts between modern application contracts and legacy implementation details.

An ASP.NET Core adapter can expose narrowly scoped HTTP endpoints, validate requests, invoke typed clients, translate legacy faults into stable error responses, and apply timeouts. Where appropriate, it can use a reverse-proxy library such as YARP to route traffic to existing services. YARP is useful for proxying HTTP traffic, but SOAP protocol translation and business-level response normalization may require additional application code.

The adapter should expose business capabilities rather than mirror every legacy method. Instead of publishing an unrestricted endpoint for executing arbitrary service operations, expose a specific operation such as GetOrderStatus or RequestShipmentApproval.

This design reduces coupling and creates an interface that can remain stable even if the underlying legacy application changes.

3. Semantic Kernel Host

The Semantic Kernel host registers approved functions and connects the application to a configured AI model. Plugin functions should use typed inputs and outputs, meaningful descriptions, and explicit failure handling.

The host is not a substitute for the adapter. The adapter provides a stable integration contract, while the Semantic Kernel host determines how an AI-enabled workflow can discover and invoke permitted functions.

Keeping these responsibilities separate allows the same facade APIs to serve conventional applications, scheduled jobs, and agent-driven workflows.

4. Autonomous Agent Runtime

The agent runtime coordinates multi-step work. It interprets an objective, determines which approved tools may be relevant, evaluates returned results, and proceeds according to workflow policies.

For example, an order-support agent could retrieve an order, check shipment status, summarize a delivery exception, and prepare a response for a support representative. If an operation would change an order or issue a refund, the runtime should apply the relevant authorization and approval policy before execution.

The runtime should use bounded iterations, explicit timeouts, controlled retries, and persistent workflow state when tasks must survive restarts. A model-generated plan must never override application authorization or business validation.

5. Governance and Observability

A separate governance layer establishes which identities can invoke which functions, which operations require approval, and which events must be recorded.

Every meaningful operation should be traceable across the incoming request, agent execution, selected function, adapter call, and legacy response. Correlation identifiers and structured events help engineers reconstruct failures without relying exclusively on model-generated explanations.

How It Works

Consider an enterprise support request: determine why a customer order has not shipped and prepare a recommended response.

1. 1.The user submits the request through an authenticated application interface.
2. 2.The runtime receives the objective, identifies the permitted tools, and establishes the workflow context.
3. 3.The agent invokes a registered order-lookup function using a validated order identifier.
4. 4.The function calls the facade adapter through an authenticated API request.
5. 5.The adapter translates the request into the legacy service contract and retrieves the authoritative order information.
6. 6.The adapter returns a normalized response, including a stable status and relevant error information.
7. 7.The agent evaluates the result and, if permitted, invokes a shipment-status function.
8. 8.The runtime combines the verified results into a concise explanation and recommended response.
9. 9.The application records the tool calls, relevant outcomes, and final workflow status.

This sequence illustrates an important distinction: the agent coordinates the investigation, but the legacy application remains authoritative for order data.

The same approach can support more complex workflows, provided each operation has a defined contract and appropriate controls. The agent should stop when required information is unavailable, authorization fails, or a policy requires human intervention.

Implementing the Facade with ASP.NET Core

A small, explicit API is preferable to exposing an entire legacy service surface. The following example illustrates the shape of a modern endpoint that delegates to an existing application service.

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/orders")]
public sealed class OrdersController : ControllerBase
{
    private readonly ILegacyOrderService _orders;

    public OrdersController(ILegacyOrderService orders)
    {
        _orders = orders;
    }

    [HttpGet("{orderId}/status")]
    public async Task<IActionResult> GetStatus(
        string orderId,
        CancellationToken cancellationToken)
    {
        if (string.IsNullOrWhiteSpace(orderId))
        {
            return BadRequest(new
            {
                error = "A valid order identifier is required."
            });
        }

        var result = await _orders.GetStatusAsync(
            orderId,
            cancellationToken);

        if (result is null)
        {
            return NotFound(new
            {
                error = "The requested order was not found."
            });
        }

        return Ok(result);
    }
}

The ILegacyOrderService interface represents an application-specific abstraction that must be implemented using the actual legacy integration. The example does not assume that a WCF endpoint, database schema, or existing service contract follows a particular structure.

In production, the adapter also needs authentication and authorization, request-size limits, input constraints, downstream timeouts, exception mapping, and structured logging. If order identifiers have a prescribed format, validate that format rather than relying only on a non-empty string.

OpenAPI can document the endpoint contract, making it easier to test the adapter and register the corresponding function with the agent framework. Contract documentation improves discoverability, but it does not automatically make an endpoint safe for AI-driven execution.

Registering Business Capabilities with Semantic Kernel

The next step is to expose a narrowly defined application function to the orchestration layer. The function should call the adapter through a typed HTTP client rather than access the legacy database directly.

A conceptual plugin might contain an operation named GetOrderStatus with an order identifier as its input and a normalized order-status response as its output. The description should explain the function's purpose, required input, and limitations without implying capabilities that it does not provide.

Function registration and invocation should follow the Semantic Kernel version adopted by the project. Teams should verify the package documentation and supported function-calling behavior rather than assume that examples from different releases are interchangeable.

The plugin should not expose credentials, unrestricted SQL execution, arbitrary URL fetching, filesystem access, or administrative service methods. Tool descriptions help a model choose functions, but descriptions are not security controls. Enforcement must occur in the application code and the authorization layer.

For workflows that require several operations, the runtime should define which calls can be performed independently, which require previous results, and which need approval. Deterministic sequences are often better implemented as ordinary application workflows with AI used only for interpretation or exception handling.

Enterprise Use Cases

Customer Support and Service Operations

Agents can retrieve customer records, inspect order statuses, summarize historical interactions, and prepare responses using existing enterprise APIs. Sensitive changes, account closures, and financial adjustments should remain subject to established authorization and approval rules.

Finance and Back-Office Processing

A governed workflow can gather invoice details, compare records, identify missing documentation, and prepare an exception report. Payment execution and accounting adjustments require stronger controls than read-only analysis and should not be delegated to unrestricted model discretion.

IT Service Management

An agent can query approved diagnostic endpoints, collect service-health information, summarize incident history, and recommend remediation steps. Restarting production services, changing firewall rules, or modifying infrastructure should require explicit permissions and, where appropriate, human approval.

Manufacturing and Inventory

Existing ERP and inventory services can supply stock levels, production status, and order information. An agent may coordinate inquiries across these systems without replacing the transactional applications that enforce reservations, quantity constraints, and production rules.

Legacy Application Modernization

An adapter can make older .NET functionality accessible to modern web clients, automation systems, and AI workflows. This creates an incremental path for replacing individual legacy components later, when business requirements justify the investment.

Performance Considerations

Agent-driven requests generally involve more processing stages than direct API calls. A single task may include model inference, one or more tool selections, HTTP requests, downstream service calls, and additional inference. Each stage adds latency and potential failure points.

Performance should therefore be measured at the workflow level rather than inferred from the response time of an individual endpoint.

Zero-rewrite migration blueprint wrapping legacy .NET services with API facades for Semantic Kernel agent consumption.

Important considerations include:

• ◆Model latency: Record time spent waiting for model responses separately from application execution time.
• ◆Tool-call count: Bound the number of model iterations and function invocations per workflow.
• ◆Downstream latency: Measure the time required by the adapter and legacy services independently.
• ◆Payload size: Return only the information required for the task. Large records and unnecessary historical data increase transfer costs and model-processing overhead.
• ◆Concurrency: Use asynchronous I/O for network operations and establish limits on concurrent requests to protect older services.
• ◆Timeouts: Configure end-to-end deadlines and downstream timeouts that reflect the actual operational requirements.
• ◆Caching: Cache suitable read-only data only when its freshness, authorization scope, and invalidation rules are understood.

Retries require particular care. Repeating a read-only request is often acceptable, but retrying an operation that creates an invoice, submits an order, or issues a payment may duplicate the business action. Use idempotency keys, deduplication, or transaction-aware mechanisms where supported.

A sensible baseline records median and high-percentile workflow latency, success rates, model-token usage, tool-call counts, downstream error rates, and resource consumption. Optimize the measured bottleneck rather than adding infrastructure indiscriminately.

Security Considerations

AI-enabled integration expands the set of ways in which enterprise operations can be initiated. Security must therefore be enforced independently of the model's reasoning.

Identity propagation: Authenticate users and services using established identity mechanisms. Where delegated access is required, preserve the user's authorization context instead of automatically granting the agent broad service privileges.

Least privilege: Register only the functions required for a particular workflow. Read-only functions should not share unrestricted credentials with write-capable functions.

Input validation: Treat model-generated arguments as untrusted input. Validate identifiers, amounts, formats, enumerated values, and business constraints before invoking downstream operations.

Prompt injection: Treat instructions and content retrieved from documents, emails, web pages, and other external sources as untrusted data. Retrieved content must not be allowed to redefine application policies or authorize tool execution.

Human approval: Require explicit approval for high-impact actions such as financial transfers, destructive operations, sensitive record changes, and production configuration updates. Approval must be bound to the specific action and its parameters.

Secrets management: Store service credentials in an appropriate secret-management system. Do not place secrets in prompts, function descriptions, source control, or model-visible tool results.

Auditability: Record the initiating identity, workflow identifier, selected operation, authorization decision, approval reference where applicable, execution result, and relevant timestamps. Protect logs against unauthorized access and avoid recording unnecessary sensitive data.

Network isolation: Keep legacy endpoints inaccessible from public networks unless there is a documented requirement. Use private connectivity, TLS, appropriate service authentication, and controlled egress where supported by the deployment environment.

The governing rule is that a model may propose an action, but application policy must determine whether that action is allowed.

Scalability and Deployment

A zero-rewrite architecture can begin as a small deployment and expand as usage grows. The facade and agent runtime may initially share a deployment unit, but their responsibilities should remain separated through clear interfaces.

For production environments, consider independently scaling the adapter and agent runtime when their resource profiles differ. Adapters typically spend significant time waiting for downstream I/O, while model orchestration may be constrained by inference latency, provider limits, concurrency, or token budgets.

A typical deployment can include an ASP.NET Core API, a Semantic Kernel host, a protected connection to the legacy service, centralized logging, metrics, and an identity provider. A background worker and durable workflow store may be necessary for long-running tasks or workflows that must resume after a process restart.

Use health checks to distinguish application availability from downstream dependency health. A running agent service does not necessarily mean that the legacy system is reachable or that the configured model endpoint is available.

Version API contracts independently from internal agent instructions where practical. Deploy adapter changes through staged environments and verify backward compatibility before switching production traffic. Feature flags and restricted pilot access can limit exposure while teams validate real workloads.

If the legacy system cannot tolerate increased concurrency, apply rate limits, bounded queues, circuit breakers, and bulkheads. These controls reduce the likelihood that an AI workflow generates enough requests to destabilize a business-critical dependency.

Best Practices

Enterprise teams should establish a consistent implementation standard before expanding the number of available tools.

• ◆Begin with read-only capabilities and observable business outcomes.
• ◆Preserve existing business rules and transaction boundaries.
• ◆Design narrow, typed APIs with stable error contracts.
• ◆Keep the facade adapter separate from model-specific orchestration logic.
• ◆Use explicit authorization policies for each business operation.
• ◆Establish limits for workflow duration, iterations, tool calls, concurrency, and cost.
• ◆Require idempotency or deduplication for retryable write operations.
• ◆Test the adapter independently of the model and evaluate the agent separately from the underlying business service.
• ◆Maintain regression tests against representative legacy-system responses and failure conditions.
• ◆Record tool-level traces and workflow-level metrics.
• ◆Version prompts, tool definitions, application code, and relevant model configuration so that behavior can be investigated after deployment.
• ◆Define a fallback path when the model, adapter, or legacy system becomes unavailable.

Testing should include successful execution, invalid inputs, permission failures, timeouts, malformed downstream responses, duplicate requests, prompt injection attempts, and unexpected model tool selections. A successful demonstration is not sufficient evidence of production readiness.

Common Mistakes

Rewriting Business Logic Inside Prompts

Prompts are not a reliable substitute for deterministic business rules. Eligibility checks, pricing rules, access restrictions, and accounting calculations should remain enforced by the application or a trusted domain service.

Exposing Every Legacy Endpoint

A large tool catalog increases complexity and may make inappropriate operations easier to select. Publish the smallest useful set of business capabilities and expand it according to demonstrated requirements.

Treating OpenAPI as an Authorization Mechanism

OpenAPI describes an interface; it does not independently enforce who may call it. Authentication, authorization, input validation, and business-level policy checks remain necessary.

Allowing Unbounded Agent Loops

Without execution limits, an agent can repeatedly call tools, consume excessive resources, or produce inconsistent results. Use bounded workflows, explicit stopping conditions, and escalation paths.

Ignoring Legacy System Capacity

An application designed for a small number of predictable requests may struggle when an agent issues several concurrent queries for one user request. Load-test the complete integration and protect downstream dependencies with enforced concurrency limits.

Confusing an Agent with a System of Record

An agent's summary or inferred conclusion is not an authoritative transaction record. Business-critical decisions should rely on validated system responses and persistent application state.

Technology Comparison

Different modernization strategies address different constraints. A zero-rewrite architecture is not automatically superior to replacing or refactoring a legacy system; its value depends on the cost and risk of changing the existing application.

For many enterprises, the facade approach is an effective first step because it improves integration without requiring an immediate replacement decision. It can also support a later domain-by-domain modernization program.

Adoption Strategy

A controlled migration can be organized into five phases.

Phase 1: Discover and Prioritize

Inventory legacy services, authentication mechanisms, dependencies, data ownership, operational limits, and business-critical workflows. Identify a use case with measurable value, limited impact, and a clear fallback path.

Select an initial capability that is useful but does not require the agent to make irreversible decisions. A read-only order-status investigation or internal knowledge-assisted support workflow is often easier to evaluate than autonomous transaction execution.

Phase 2: Build the Facade

Create a narrow ASP.NET Core API that wraps the selected legacy operation. Define request and response contracts, standardize error handling, add authentication, and document the interface using OpenAPI where appropriate.

Validate the facade with automated contract tests, integration tests, and representative failure scenarios. Confirm that existing application behavior remains unchanged.

Phase 3: Introduce the Agent Runtime

Register the approved facade operations as Semantic Kernel functions or plugins. Configure model access, bounded tool execution, structured logging, and explicit stopping conditions.

Initially, allow the agent to inspect data and prepare recommendations. Compare its outputs with verified application records and human assessments before allowing it to initiate consequential operations.

Phase 4: Run a Controlled Pilot

Release the workflow to a small, authorized group. Measure task completion, factual accuracy, latency, tool-selection quality, downstream error rates, cost per completed task, and escalation frequency.

Review failures to distinguish model reasoning errors from API defects, authorization problems, incomplete source data, and legacy-system limitations. Each category requires a different corrective action.

Phase 5: Expand Under Governance

Introduce additional capabilities only after the initial workflow meets agreed acceptance criteria. Add write operations through explicit permission scopes, transaction safeguards, approval policies, and audit requirements.

Maintain a rollback strategy for adapter deployments and the ability to disable agent-driven execution without interrupting conventional application workflows. Reassess the architecture as operational evidence accumulates.

Measuring Success

Migration success should be measured by business and operational outcomes rather than the number of AI tools created.

Useful indicators include:

• ◆Reduction in time required to investigate a support request.
• ◆Percentage of workflows completed without manual data gathering.
• ◆Accuracy of extracted facts against authoritative system records.
• ◆Percentage of tool calls completed successfully.
• ◆Rate of policy violations and unauthorized action attempts.
• ◆Median and high-percentile end-to-end latency.
• ◆Cost per successfully completed workflow.
• ◆Frequency of manual escalation and recovery from downstream failures.
• ◆Regression rate in existing business processes.

Define a baseline before the pilot and compare results against the same task population where possible. Human review remains important when outputs influence financial, legal, operational, or customer-facing decisions.

A useful acceptance criterion is not merely that the agent can invoke an API. It is that the complete workflow performs reliably, respects authorization, produces verifiable results, and can be operated and audited by the engineering team.

Limitations

A zero-rewrite strategy does not eliminate legacy constraints. The underlying system may have slow service calls, undocumented behavior, limited concurrency, outdated authentication, or dependencies that cannot be safely exposed through a modern API.

An adapter can normalize interfaces, but it cannot automatically repair poor data quality, remove all technical debt, or guarantee transaction consistency across multiple independent systems. Cross-system workflows may require durable orchestration, compensation logic, reconciliation, and explicit ownership of intermediate state.

Agent behavior is also probabilistic. Function selection, interpretation of ambiguous requests, and generated explanations may vary across model configurations and inputs. These characteristics make unrestricted autonomous execution unsuitable for many high-impact business operations without additional controls.

Organizations must also consider model-provider availability, data-handling requirements, inference costs, contractual restrictions, and deployment constraints. A private or locally hosted model changes some infrastructure and data-governance considerations, but it does not remove the need for application-level authorization and validation.

In some cases, the correct long-term decision will still be to replace a legacy component. The facade approach should preserve that option rather than become another permanent source of unnecessary complexity.

Looking Ahead

As enterprises explore agentic AI, the most practical modernization path is likely to begin with bounded workflows that use existing business capabilities rather than attempt to replace entire transactional systems with autonomous agents.

Established interfaces, typed contracts, identity controls, and observable execution remain foundational regardless of which model or orchestration framework an organization selects. Framework APIs and model capabilities can change, so integration boundaries should minimize dependence on a specific model implementation.

Organizations can also evaluate standardized approaches to tool discovery and inter-service communication as their integration requirements evolve. Any such protocol should be adopted based on its actual security model, interoperability requirements, operational maturity, and compatibility with existing systems rather than on novelty alone.

The architectural priority is to make business capabilities accessible without surrendering control over how they are executed. A well-designed facade, a governed agent runtime, and a reliable legacy system can coexist while delivering incremental modernization.

Conclusion

Moving from legacy .NET to an agent-native architecture does not require an immediate rewrite of business-critical applications. A facade adapter can expose selected capabilities through stable APIs, while Semantic Kernel and a controlled agent runtime coordinate bounded workflows around those capabilities.

The strongest implementations preserve the existing system as the authority for business rules and transactions, enforce permissions outside the model, limit execution, and make every important operation observable. They also introduce AI capabilities incrementally, beginning with measurable read-only workflows before considering higher-impact actions.

For enterprise architects, the central decision is not whether legacy software should be replaced with AI. It is how to make existing business capabilities safely composable while retaining operational reliability and a credible path for future modernization. A zero-rewrite migration provides that path when it is treated as a disciplined architecture program rather than a shortcut around engineering controls.