Deployment Workflows for Agents v2

[nnellanspdl]

TLDR: I'm looking for the "golden path" to managing and deploying Foundry Agents at scale and via automation workflows and Agents-as-code.

ARM providers exist for Foundry accounts, Projects, Model Deployments, and other Foundry-related things. So, I can deploy and manage those easily via IaC such as Bicep and/or Terraform.

However, deploying and managing Agents is much trickier. I'm specifically referring to the new v2 Agents (prompt agents, hosted agents, and workflows). It appears I must interact with the Foundry SDK in order to manage these Agents. And there are multiple ways that I've found to interact with the Foundry SDK:

Directly use the Preview REST API (2025-11-15-preview)

• Call the <project>/agents endpoint to create a new Agent
• Call the <project>/agents/<agent> endpoint to update an existing Agent
• Call the <project>/agents/<agent>/versions endpoint to create a new version of an Agent
  • Question: this might be an idempotent endpoint that can be used to both "create" and "update" and Agent, is that correct?

Use the Azure CLI (with the preview command group)

• az cognitiveservices agent create
• az cognitiveservices agent update
• Issue: this only works for hosted agents, and does not support prompt agents or workflows

Use the Azure Developer CLI (with the preview extension) and AgentSchema

• azd ai agent init --manifest agentSchema.yaml
  • This lets me define my agents using Agent Schema, which is nice. Agents-as-code is really what I'm looking for here.
  • Question: this only supports the AgentManifest spec and not the AgentDefinition spec, correct?
  • Question: does this fully support all features of all 3 types of Agents (prompt, hosted, workflows)?
  • From what I understand, this command only updates another file azure.yaml. Then, I must deploy that azure.yaml file with another command azd up, correct? This is slightly clunky.

Use the various SDKs programatically

• Python AI Projects client library (preview)
• JavaScript AI Projects client library (preview)
• Question: Java doesn't yet have a preview library for Agents v2, correct?
• This is not my ideal scenario for automation workflows: writing python or javascript files that download and load external libraries, and then deploy/update agents after pulling in the agent settings from another external file. It all seems very "heavy" for lack of a better word. I like my automation workflows to be light and easy, like run a CLI with some parameters, or run a Bicep deploy with a template file.

---

Did I miss any ways to deploy/update Agents V2 in Foundry?

What is Microsoft's preferred method for managing Agents at scale, for example across many Foundries and many landing zones/Subscriptions?

[thedevopsguy]

Hi @nnellanspdl,

Here’s what I’ve learned so far:

• Foundry Agents v2 (prompt, hosted, workflows) are not ARM resources, so IaC tools like Bicep/Terraform can’t manage them directly. You’ll need to use the REST API, SDKs, or CLI tools.
• The REST API (Nov15, 2025 preview) supports all agent types. However, endpoints like /versions are not idempotent – each call creates a new version. You’ll need to implement your own logic to avoid unnecessary version churn.
• The Azure CLI (az cognitiveservices agent) is limited to hosted agents. It’s useful for container-based deployments but doesn’t support prompt agents or workflows yet.
• The azd ai agent extension is promising for “agents-as-code” workflows, but it’s still preview and focused on hosted agents. It uses a unified Agent YAML (manifest + definition) and doesn’t yet support prompt-only or workflow agents.
• SDKs (Python, JS/TS, .NET) are the most complete and flexible option today. They support all agent types and are ideal for CI/CD. Java SDK is in preview but doesn’t yet support agent operations.

Microsoft’s current “golden path” for scalable agent deployment:

• Treat agents as code (YAML/JSON) in source control.
• Use CI/CD pipelines (GitHub Actions, Azure DevOps) to deploy via SDK or REST.
• Automate versioning, environment-specific config, and rollback logic.
• Use service principals with appropriate RBAC (e.g., Azure AI Project Manager).

If you’re deploying across multiple Foundry projects or subscriptions, parameterize your deployment scripts and use environment-specific secrets or variables. For hosted agents, you can use container tags or metadata to track versions. For prompt agents, consider embedding commit hashes or semantic versions in the agent description.

[nnellanspdl]

Thanks @thedevopsguy !

[nnellanspdl]

Keeping this thread up to date with my latest findings:

It appears the REST API for Foundry Projects v2 has hit GA/v1 release. Here is the Microsoft short link for the v1 docs: https://aka.ms/azsdk/azure-ai-projects-v2/api-reference-v1

• Hosted Agents are still marked as preview, and you must set a special header when using them
• Workflow Agents are still marked as preview, and you must set a special header when using them

The Python SDK had a new beta release 2.0.0 b4 which uses the new GA/v1 API referenced above

• Interestingly, they removed the agent methods for create(), create_from_manifest(), update() and update_from_manifest(). They want you to use the remaining methods create_version() and create_version_from_manifest() instead.
  • This ties back to my idea that the create_version method is an idempotent method that supports both creating new agents, and updating existing agents. I tested this out, and it does indeed work this way.

The AgentSchema project does support all 3 types of Agents, but it appears this is not yet ready for primetime, in my opinion.

• PromptAgent
• ContainerAgent
• Workflow