Skip to main content
Microsoft Foundry
Sign in
View as Markdown
View as Markdown
Agent Versions

Create an agent version

POST
/agents/{agent_name}/versions

Creates a new version for the specified agent and returns the created version resource.

Path Parameters
agent_namestringrequired
The unique name that identifies the agent. Name can be used to retrieve/update/delete the agent. - Must start and end with alphanumeric characters, - Can contain hyphens in the middle - Must not exceed 63 characters.
Query Parameters
api-versionstringrequired
The API version to use for this operation.
Header Parameters
Foundry-Featuresstringoptional
A feature flag opt-in required when using preview operations or modifying persisted preview resources.
WorkflowAgents=V1PreviewExternalAgents=V1PreviewDraftAgents=V1PreviewVoiceAgents=V1PreviewDigitalWorker=V1Preview
x-ms-code-zip-sha256stringoptional
SHA-256 hex digest of the uploaded code zip. Used for change detection (dedup) and integrity verification.
Request BodyThe content multipart request content.Content-Type: application/json
metadataobject
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
descriptionstring
A human-readable description of the agent.
definitionhosted | prompt | workflow | externalrequired
One of the following:
hostedHostedAgentDefinition
The hosted agent definition.
promptPromptAgentDefinition
The prompt agent definition
workflowWorkflowAgentDefinition
The workflow agent definition. Microsoft Foundry is retiring workflows on December 1, 2026. If you're looking to build new workflows, use Microsoft Agent Framework. To migrate existing workflows, see the Migration guide.
externalExternalAgentDefinition
The external agent definition. Represents a third-party agent hosted outside Foundry (for example, on GCP or AWS). Registration is metadata-only: Foundry records the agent definition to light up observability experiences (traces, evaluations) over customer-emitted OpenTelemetry data.
blueprint_referenceManagedAgentIdentityBlueprint
One of the following:
ManagedAgentIdentityBlueprintManagedAgentIdentityBlueprintReference
digital_worker_typeenum
The type of digital worker.
m365
draftboolean
(Preview) Whether this agent version is a draft (candidate) rather than a release. The service defaults to false if a value is not specified by the caller. Draft versions are recorded but excluded from default 'latest' resolution and are not auto-promoted.
Responses
metadataobject | nullrequired
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
objectenumrequired
The object type, which is always 'agent.version'.
agent.version
idstringrequired
The unique identifier of the agent version.
namestringrequired
The name of the agent. Name can be used to retrieve/update/delete the agent.
versionstringrequired
The version identifier of the agent. Agents are immutable and every update creates a new version while keeping the name same.
descriptionstring
A human-readable description of the agent.
created_atintegerrequired
definitionhosted | prompt | workflow | externalrequired
One of the following:
hostedHostedAgentDefinition
The hosted agent definition.
promptPromptAgentDefinition
The prompt agent definition
workflowWorkflowAgentDefinition
The workflow agent definition. Microsoft Foundry is retiring workflows on December 1, 2026. If you're looking to build new workflows, use Microsoft Agent Framework. To migrate existing workflows, see the Migration guide.
externalExternalAgentDefinition
The external agent definition. Represents a third-party agent hosted outside Foundry (for example, on GCP or AWS). Registration is metadata-only: Foundry records the agent definition to light up observability experiences (traces, evaluations) over customer-emitted OpenTelemetry data.
draftboolean
Whether this agent version is a draft (candidate) rather than a release. Draft versions are recorded but excluded from default 'latest' resolution and are not auto-promoted. Defaults to false.
statusenum
The provisioning status of an agent version.
creatingactivefaileddeletingdeleted
instance_identityAgentIdentity
principal_idstringrequired
The principal ID of the agent instance
client_idstringrequired
The client ID of the agent instance. Also referred to as the instance ID
statusenum
The status of an agent identity, applicable to both the agent instance identity and the agent blueprint.
activedisabled
blueprintAgentIdentity
principal_idstringrequired
The principal ID of the agent instance
client_idstringrequired
The client ID of the agent instance. Also referred to as the instance ID
statusenum
The status of an agent identity, applicable to both the agent instance identity and the agent blueprint.
activedisabled
blueprint_referenceManagedAgentIdentityBlueprint
One of the following:
ManagedAgentIdentityBlueprintManagedAgentIdentityBlueprintReference
agent_guidstring
The unique GUID identifier of the agent.