Skip to main content
Microsoft Foundry
Sign in
View as Markdown
View as Markdown
Agents

Generate an agent

POST
/agents:generate

Generates and creates an agent from kind-specific high-level inputs. The generated definition remains fully editable through the standard agent versioning operations.

Query Parameters
api-versionstringrequired
The API version to use for this operation.
Header Parameters
Foundry-Featuresstringrequired
A feature flag opt-in required when using preview operations or modifying persisted preview resources.
VoiceAgents=V1Preview
Request BodyThe kind-specific inputs for generating and creating an agent.Content-Type: application/json
kindenumrequired
The agent kind. Always voice.
voice
namestringrequired
The unique name for the agent to create. Must be a non-empty DNS-like agent name.
model_typeenum
How the model backing a voice agent is served. This is independent of the architecture (realtime or cascaded), which the service derives from the selected model.
managedself_deployed
modelstring
Optional model identifier. Required when model_type is self_deployed; optional when model_type is managed or omitted. The service never invents a customer deployment name.
use_casestring
An optional authoring use case. An empty string is accepted.
goalstring
An optional natural-language description of what the agent should do. When supplied, it seeds the generated instructions.
descriptionstring
An optional agent description. The authoring service resolves its fallback when omitted.
tools(function | mcp | system | toolbox)[]
Optional tools carried through verbatim onto the generated agent (see VoiceAgentTool).
One of the following:
functionVoiceAgentFunctionTool
A native function tool executed by the client.
mcpVoiceAgentMcpTool
An MCP tool available to a voice agent.
systemVoiceAgentSystemTool
A service-managed control that acts on the active voice session without customer code or external authentication.
toolboxVoiceAgentToolboxTool
A reference to a Foundry toolbox, which is a versioned bundle of tools executed through its MCP endpoint.
draftboolean
(Preview) When true, the generated voice agent is created as a draft — an editable, unpublished version the caller can review and refine before publishing it via the standard create/version path. The service defaults to false if a value is not specified by the caller, in which case the agent is created and published normally.
Responses
objectenumrequired
The object type, which is always 'agent'.
agent
idstringrequired
The unique identifier of the agent.
namestringrequired
The name of the agent.
stateenumrequired
The operational state of an agent.
enableddisabled
configuration_stateenumrequired
The operational state of an agent.
enableddisabled
state_sourceenum
Indicates the source of an agent's operational state. Empty when the state is not derived from a specific source.
agent_instance_identityagent_blueprint
versionsobjectrequired
The latest version of the agent.
latestAgentVersionObjectrequired
agent_endpointAgentEndpointConfig
version_selectorVersionSelector
protocol_configurationProtocolConfiguration
Per-protocol configuration for the agent endpoint.
authorization_schemes(Entra | BotService | BotServiceRbac | BotServiceTenant)[]
The authorization schemes supported by the agent endpoint
publish_approval_statusenum
The Microsoft Agent Certification review status of the Microsoft 365 store title published for an agent.
not_publishedpendingapprovedrejectedno_approval_needed
digital_worker_typeenum
The type of digital worker.
m365
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_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.