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

Create an agent

POST
/agents

Creates a new agent or a new version of an existing agent.

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.
HostedAgents=V1PreviewWorkflowAgents=V1PreviewAgentEndpoints=V1PreviewCodeAgents=V1PreviewExternalAgents=V1Preview
x-ms-agent-namestringoptional
The unique name that identifies the agent. Max 63 chars, must start and end with alphanumeric, hyphens allowed in the middle.
x-ms-code-zip-sha256stringoptional
SHA-256 hex digest of the uploaded code zip. Used for change detection (dedup) and integrity verification.
Request BodyContent-Type: application/json
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.
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
The agent definition. This can be a workflow, hosted agent, or a simple agent definition.
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.
blueprint_referenceManagedAgentIdentityBlueprint
The blueprint reference for the agent.
One of the following:
ManagedAgentIdentityBlueprintManagedAgentIdentityBlueprintReference
agent_endpointAgentEndpointConfig
An optional endpoint configuration. If not specified, a default endpoint configuration will be set for the agent
version_selectorVersionSelector
The version selector of the agent endpoint determines how traffic is routed to different versions of the agent.
protocolsenum[]
The protocols that the agent supports
activityresponsesa2amcpinvocationsinvocations_ws
authorization_schemes(Entra | BotService | BotServiceRbac)[]
The authorization schemes supported by the agent endpoint
agent_cardAgentCard
Optional agent card for the agent
versionstringrequired
The version of the agent card.
descriptionstring
The description of the agent card.
skillsAgentCardSkill[]required
The set of skills that an agent can perform.
Responses
objectenumrequired
The object type, which is always 'agent'.
agent
idstringrequired
The unique identifier of the agent.
namestringrequired
The name of the agent.
versionsobjectrequired
The latest version of the agent.
latestAgentVersionObjectrequired
agent_endpointAgentEndpointConfig
The endpoint configuration for the agent
version_selectorVersionSelector
The version selector of the agent endpoint determines how traffic is routed to different versions of the agent.
protocolsenum[]
The protocols that the agent supports
activityresponsesa2amcpinvocationsinvocations_ws
authorization_schemes(Entra | BotService | BotServiceRbac)[]
The authorization schemes supported by the agent endpoint
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_cardAgentCard
versionstringrequired
The version of the agent card.
descriptionstring
The description of the agent card.
skillsAgentCardSkill[]required
The set of skills that an agent can perform.