Update a hosted agent endpoint and agent card

Important

Items marked preview in this article are currently in preview. This preview is provided without a service-level agreement, and Microsoft doesn't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

Use azd ai agent endpoint update to patch endpoint and card metadata on an already-deployed Microsoft Foundry agent. You can refresh consumer-facing details without cutting a new agent version.

If you use a coding agent like GitHub Copilot, the Microsoft Foundry Skill can help update endpoint metadata and agent card settings while keeping deployment changes separate.

Prerequisites

  • An existing hosted agent deployed to a Foundry project. endpoint update doesn't create a hosted agent.
  • An azd project that declares the deployed hosted agent in azure.yaml, inline or through an explicit root $ref. An endpoint alone doesn't provide the local metadata to patch.
  • The azd Foundry extensions installed.
  • An authenticated azd session.

Decide when to update metadata

Use azd ai agent endpoint update when you only need to refresh metadata that consumers and tooling read about the agent. This metadata includes the public endpoint, display name, description, and contact info.

Common cases include:

  • You changed the public-facing display name or description on the agent card and want it reflected in the Foundry portal without redeploying.
  • You moved or re-issued the public agent endpoint URL.
  • You updated owner or contact metadata on the card for routing or governance.

If you changed the model, instructions, tools, code, or environment variables, don't use endpoint update. Those changes need a new version. Run azd deploy or azd up instead.

Update the endpoint and card

  1. Edit agentEndpoint, agentCard, or both in the azure.ai.agent service. For a file-backed service, edit the referenced definition.

  2. Run the update command:

    azd ai agent endpoint update

  3. In a multi-service project, pass the service name as a positional:

    azd ai agent endpoint update my-agent

The CLI reads the two sections from the agent service in azure.yaml and patches the existing agent record. The process doesn't create a new agent version, rebuild a container, or change any infrastructure.

Breaking endpoint changes require confirmation. Use --force only when you intend to accept them, including in unattended jobs.

Verify the update

Confirm the change took effect:

azd ai agent endpoint show my-agent

The output shows the deployed endpoint and card. endpoint show can also inspect prompt and voice agents; endpoint update is limited to hosted agents.

Review fields updated

endpoint update only updates endpoint and card metadata. Use the table to decide whether your change requires a full deploy.

Field on the azure.ai.agent service Updated by endpoint update?
agentEndpoint Yes
agentCard Yes
model, model_deployment No - requires azd deploy
instructions No - requires azd deploy
tools, toolboxes, skills No - requires azd deploy
env No - requires azd deploy
Container image / entry point / runtime No - requires azd deploy

If the update fails, read the reported validation error before retrying. Use azd ai agent doctor for project health checks; it isn't a general diff of every local field against the service.

Related content

  • อัปเดตล่าสุดเมื่อ