microsoft/aspire · error · InvalidOperationException

Deployment target annotation is required on resource

Error message

Deployment target annotation is required on resource '{Target.Name}' to deploy as hosted agent.

What it means

An AzureHostedAgentResource wraps a target containerized workload and deploys it as a hosted agent in an Azure AI Foundry project. To know where to deploy, its pipeline step annotation reads the target resource's deployment target annotation, which carries the compute environment. This error is thrown during pipeline step construction when the target resource was never associated with a deployment target.

Solutions

Associate the target resource with an Azure compute environment so it gets a deployment target annotation (e.g. publish it as a container app inside the AzureCognitiveServicesProjectResource environment)
Ensure the target passed to AzureHostedAgentResource is a containerized project resource, not a plain Resource
Check that the compute environment resource is created and the target is added to it before the hosted agent's pipeline steps run

Example fix

// before
var agent = builder.AddHostedAgent("my-agent", project); // project has no deployment target
// after
var foundry = builder.AddAzureCognitiveServicesProject("foundry");
var project = builder.AddDockerfileEnvironmentContainerAppHost(...).AsFoundryHostedAgentTarget(foundry);
var agent = builder.AddHostedAgent("my-agent", project);

Defensive patterns

Strategy: validation

Validate before calling

// In AppHost code, before creating the hosted agent, assert the target has a deployment target:
if (target.GetDeploymentTargetAnnotation() is null)
{
    throw new InvalidOperationException($"{target.Name} must be added to a Foundry compute environment before AddHostedAgent.");
}

Try / catch

try
{
    // build/publish pipeline that includes the hosted agent steps
}
catch (InvalidOperationException ex) when (ex.Message.Contains("Deployment target annotation is required"))
{
    // surface a targeted message: wire the target into a Foundry project environment
}

Prevention

Always create the AzureCognitiveServicesProjectResource environment first, then register containerized targets in it, then attach hosted agents
Review AppHost diffs that change target/compute-environment wiring for hosted agents
Keep the AddHostedAgent call adjacent to the code that binds the target to the compute environment

When it happens

Trigger: Creating `new AzureHostedAgentResource(name, target)` (or the AddHostedAgent-style extension) where `target` is a project/container resource that has no deployment target annotation, then running publish/deploy so the PipelineStepAnnotation executes and `Target.GetDeploymentTargetAnnotation()` returns null.

Common situations: Forgetting to publish the target project as a container (no AddDockerfileEnvironmentContainerAppHost / PublishAsAzureContainerApp-style wiring); pointing the hosted agent at a bare resource that is only meant for local run mode; wiring the agent before the target is added to a compute environment.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/704fa05678cc501b. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs:43

/// </summary>
public class AzureHostedAgentResource : Resource, IResourceWithEnvironment
{
    internal const string DefaultResponsesProtocolVersion = "2.0.0";

    /// <summary>
    /// Creates a new instance of the <see cref="AzureHostedAgentResource"/> class.
    /// </summary>
    public AzureHostedAgentResource([ResourceName] string name, IResource target, Action<HostedAgentConfiguration>? configure = null) : base(name)
    {
        ArgumentNullException.ThrowIfNull(target);
        Target = target;
        Configure = configure;
        Annotations.Add(new ManifestPublishingCallbackAnnotation(PublishAsync));
        // Set up steps for deploying this particular hosted agent
        Annotations.Add(new PipelineStepAnnotation(async (ctx) =>
        {
            List<PipelineStep> steps = [];
            var deploymentAnnotation = Target.GetDeploymentTargetAnnotation() ?? throw new InvalidOperationException($"Deployment target annotation is required on resource '{Target.Name}' to deploy as hosted agent.");
            var project = deploymentAnnotation.ComputeEnvironment as AzureCognitiveServicesProjectResource
                ?? throw new InvalidOperationException($"Compute environment for resource '{Target.Name}' must be an AzureCognitiveServicesProjectResource to deploy as hosted agent.");

            // Create a step to deploy container as agent
            var agentDeployStep = new PipelineStep
            {
                Name = $"deploy-{Name}",
                Action = async (ctx) =>
                {
                    var version = await DeployAsync(ctx, project).ConfigureAwait(false);
                    ctx.ReportingStep.Log(LogLevel.Information, new MarkdownString($"Successfully deployed **{Name}** as Hosted Agent (version {version})"));
                    Version.Set(version.Version);
                },
                Tags = [WellKnownPipelineTags.DeployCompute],
                RequiredBySteps = [WellKnownPipelineSteps.Deploy],
                Resource = this,
                DependsOnSteps = [WellKnownPipelineSteps.DeployPrereq, AzureEnvironmentResource.ProvisionInfrastructureStepName]
            };

View on GitHub (pinned to 25830f84bd)