Skip to main content
Microsoft Foundry
Start building
View as Markdown
View as Markdown
Agents

Get an agent version

GET
/agents/{agent_name}/versions/{agent_version}

Retrieves the specified version of an agent by its agent name and version identifier.

Path Parameters
agent_namestringrequired
The name of the agent to retrieve.
agent_versionstringrequired
The version of the agent to retrieve.
Query Parameters
api-versionstringrequired
The API version to use for this operation.
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
The Unix timestamp (seconds) when the agent was created.
definitionhosted | prompt | workflow | externalrequired
One of the following:
hostedHostedAgentDefinition
The hosted agent definition.
promptPromptAgentDefinition
The prompt agent definition
workflowWorkflowAgentDefinition
The workflow agent definition.
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.
statusenum
The provisioning status of the agent version. Defaults to 'active' for non-hosted agents. For hosted agents, reflects infrastructure readiness.
creatingactivefaileddeletingdeleted
instance_identityAgentIdentity
The instance identity of the agent
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
blueprintAgentIdentity
The blueprint for the agent
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
blueprint_referenceManagedAgentIdentityBlueprint
The blueprint for the agent
One of the following:
ManagedAgentIdentityBlueprintManagedAgentIdentityBlueprintReference
agent_guidstring
The unique GUID identifier of the agent.