AgentOptimizationJobs
Create an agent optimization job
Creates an optimization job and returns the queued job. Honors Operation-Id for idempotent retry. Clients poll the URL in Operation-Location by using the get operation.
Header parameters
Operation-Id
string
Client-generated unique ID for idempotent retries. When absent, the server creates the job unconditionally.
Query parameters
api-version
string
required
The API version to use for this operation.
Request Body
The job to create.
id
string
required
Server-assigned unique identifier.
result
AgentOptimizationJobResult
Partial or terminal result produced by an agent optimization job.
candidate_summary
AgentOptimizationResultCandidateSummary
Summary of candidates produced by an agent optimization job.
completed_candidate_count
integer
required
Number of completed candidates. Does not include the baseline.
baseline_id
string
Candidate ID of the original baseline. Omitted until the baseline candidate is available.
best_id
string
Candidate ID of the highest-scoring candidate for evaluated jobs, or the selected transformed output for non-comparative jobs. Omitted until a candidate has been selected.
baseline_score
number
Normalized score of the baseline candidate from 0.0 to 1.0 for a comparatively evaluated job. Omitted otherwise and until baseline evaluation completes.
best_score
number
Best normalized score observed from 0.0 to 1.0 for a comparatively evaluated job. Omitted otherwise and until a candidate completes evaluation.
latest_promoted_candidate
AgentOptimizationCandidatePromotionInfo
Promotion metadata recorded for a candidate.
promoted_agent
AgentReference
required
type
enum
required
name
string
required
The name of the agent.
version
string
The version identifier of the agent.
token_usage
AgentOptimizationJobTokenUsage[]
required
Aggregate token usage per stage and model. Always present; empty array when no calls were measured.
latency_metrics
AgentOptimizationJobLatency[]
required
Aggregate latency per stage and model. Always present; empty when no server-measured latency is available.
termination_reason
string | enum
Reason the optimization process ended. Early termination reasons still indicate a successful job; completed candidates remain available.
enum
status
string | enum
required
Extensible status values shared by Foundry jobs.
enum
error
OpenAI.Error
misalignment
OpenAI.MisalignmentErrorDetailsResource
error_type
string | enum
enum
detailed_explanation
string
The public explanation for this block.
steer
OpenAI._MisalignmentSteer
message
string
required
The public continuation instruction.
details
OpenAI.Error[]
Additional errors that contributed to this failure.
additionalInfo
object
Additional structured information about the failure.
debugInfo
object
Diagnostic information supplied by the service for troubleshooting.
display_name
string
Human-readable label. Omitted when no label is needed; it has no uniqueness, routing, or idempotency semantics.
target_configuration
foundry_agent
Base target configuration for an optimization job.
foundry_agent
AgentOptimizationFoundryAgentTargetConfiguration
Identifies the Foundry agent that owns the configuration being optimized.
type
enum
required
Foundry-agent target discriminator.
name
string
required
Registered Foundry agent name.
version
string
Pinned agent version. Omitted to resolve and pin the latest version.
optimization_model_configuration
AgentOptimizationModelConfiguration
required
Identifies a model used by an optimization or evaluation step.
model
string
required
A non-empty Foundry model name or existing deployment name.
optimization_configuration
agent_optimization | prompt_optimization | skill_optimization
required
Base model for type-specific optimization configuration.
agent_optimization
AgentOptimizationConfiguration
Configuration for optimizing an agent for measured quality.
type
enum
required
Optimization type discriminator.
goal
string | enum
Goal for an agent-optimization job.
enum
evaluation_configuration
AgentOptimizationEvaluationConfiguration
required
Reusable quality-measurement configuration for agent optimization.
training_set
target_completion | user_conversation_simulation
required
Base discriminated model for an optimization evaluation set.
target_completion
AgentOptimizationTargetCompletionEvaluationSet
Evaluation set containing independent single-turn inputs.
type
enum
required
Target-completion set discriminator.
source
inline | dataset_reference
required
Base source for a target-completion optimization evaluation set.
inline
AgentOptimizationTargetCompletionInlineDataSource
Supplies single-turn rows directly in the optimization request.
type
enum
required
Inline source discriminator.
test_cases
AgentOptimizationTargetCompletionTestCase[]
required
Target-completion test cases.
dataset_reference
AgentOptimizationTargetCompletionDatasetReferenceDataSource
References an explicitly versioned registered Foundry dataset for target-completion evaluation.
type
enum
required
Registered dataset source discriminator.
name
string
required
Registered dataset name.
version
string
required
Registered dataset version.
user_conversation_simulation
AgentOptimizationUserConversationSimulationEvaluationSet
Evaluation set containing scenarios for simulated conversations.
type
enum
required
User-conversation-simulation set discriminator.
source
inline | dataset_reference
required
Base source for a user-conversation-simulation optimization evaluation set.
inline
AgentOptimizationUserConversationSimulationInlineDataSource
Supplies Evals user-conversation simulation test cases directly in the optimization request.
type
enum
required
Inline source discriminator.
test_cases
UserConversationSimulationTestCase[]
required
Conversation test scenarios.
dataset_reference
AgentOptimizationUserConversationSimulationDatasetReferenceDataSource
References an explicitly versioned registered Foundry dataset for user-conversation-simulation evaluation.
type
enum
required
Registered dataset source discriminator.
name
string
required
Registered dataset name.
version
string
required
Registered dataset version.
default_simulation_configuration
UserConversationSimulationConfiguration
Configures the number, length, audio effects, and simulated user behavior of conversations.
max_num_turns
integer
Hard limit on turns in each conversation. When omitted, the service defaults to 20.
conversation_repetitions
integer
Number of independent conversation repetitions for each test case. Defaults to 1 when not specified at either the data-source or test-case level.
desired_num_turns
integer
Target number of turns in each conversation. The effective value cannot exceed the effective max_num_turns. When omitted, no target is set and the simulation model determines the conversation length dynamically from the scenario.
audio_effects
UserConversationSimulationAudioEffectsConfiguration
Configures effects applied to simulated conversation audio.
effects
UserConversationSimulationAudioEffect[]
Effects to apply to simulated audio.
volume_percentage
integer
Volume of the configured audio effects, as a percentage from 1 through 100. When omitted, the service defaults to 15.
user_behavior
UserConversationSimulationUserBehaviorConfiguration
Configures conversation behavior for the simulated user.
interruption
default
Configuration for simulated user interruption behavior.
default
UserConversationSimulationDefaultInterruptionConfiguration
Configures the default interruption behavior for the simulated user.
type
enum
required
The interruption type, always default.
validation_set
target_completion | user_conversation_simulation
Base discriminated model for an optimization evaluation set.
target_completion
AgentOptimizationTargetCompletionEvaluationSet
Evaluation set containing independent single-turn inputs.
type
enum
required
Target-completion set discriminator.
source
inline | dataset_reference
required
Base source for a target-completion optimization evaluation set.
inline
AgentOptimizationTargetCompletionInlineDataSource
Supplies single-turn rows directly in the optimization request.
type
enum
required
Inline source discriminator.
test_cases
AgentOptimizationTargetCompletionTestCase[]
required
Target-completion test cases.
dataset_reference
AgentOptimizationTargetCompletionDatasetReferenceDataSource
References an explicitly versioned registered Foundry dataset for target-completion evaluation.
type
enum
required
Registered dataset source discriminator.
name
string
required
Registered dataset name.
version
string
required
Registered dataset version.
user_conversation_simulation
AgentOptimizationUserConversationSimulationEvaluationSet
Evaluation set containing scenarios for simulated conversations.
type
enum
required
User-conversation-simulation set discriminator.
source
inline | dataset_reference
required
Base source for a user-conversation-simulation optimization evaluation set.
inline
AgentOptimizationUserConversationSimulationInlineDataSource
Supplies Evals user-conversation simulation test cases directly in the optimization request.
type
enum
required
Inline source discriminator.
test_cases
UserConversationSimulationTestCase[]
required
Conversation test scenarios.
dataset_reference
AgentOptimizationUserConversationSimulationDatasetReferenceDataSource
References an explicitly versioned registered Foundry dataset for user-conversation-simulation evaluation.
type
enum
required
Registered dataset source discriminator.
name
string
required
Registered dataset name.
version
string
required
Registered dataset version.
default_simulation_configuration
UserConversationSimulationConfiguration
Configures the number, length, audio effects, and simulated user behavior of conversations.
max_num_turns
integer
Hard limit on turns in each conversation. When omitted, the service defaults to 20.
conversation_repetitions
integer
Number of independent conversation repetitions for each test case. Defaults to 1 when not specified at either the data-source or test-case level.
desired_num_turns
integer
Target number of turns in each conversation. The effective value cannot exceed the effective max_num_turns. When omitted, no target is set and the simulation model determines the conversation length dynamically from the scenario.
audio_effects
UserConversationSimulationAudioEffectsConfiguration
Configures effects applied to simulated conversation audio.
effects
UserConversationSimulationAudioEffect[]
Effects to apply to simulated audio.
volume_percentage
integer
Volume of the configured audio effects, as a percentage from 1 through 100. When omitted, the service defaults to 15.
user_behavior
UserConversationSimulationUserBehaviorConfiguration
Configures conversation behavior for the simulated user.
interruption
default
Configuration for simulated user interruption behavior.
default
UserConversationSimulationDefaultInterruptionConfiguration
Configures the default interruption behavior for the simulated user.
type
enum
required
The interruption type, always default.
evaluators
AgentOptimizationEvaluator[]
required
Evaluator references used to score candidate quality.
evaluation_model
EvaluationModelConfiguration
required
Configures the model that plays the simulated user. This model is separate from the evaluated target.
model
string
required
Model deployment that generates simulated user turns, in the format {connectionName}/modelDeploymentName.
sampling_params
ModelSamplingParams
Represents a set of parameters used to control the sampling behavior of a language model during text generation.
temperature
number
The temperature parameter for sampling. Defaults to 1.0.
top_p
number
The top-p parameter for nucleus sampling. Defaults to 1.0.
seed
integer
The random seed for reproducibility. Defaults to 42.
max_completion_tokens
integer
The maximum number of tokens allowed in the completion.
voice_model
azure-standard
Voice configuration used to convert text to speech for evaluation through the Voice Live endpoint.
azure-standard
EvaluationAzureStandardVoiceModelConfiguration
Configures an Azure standard neural voice used to convert text to speech for evaluation through the Voice Live endpoint.
type
enum
required
The voice kind. Always azure-standard.
name
string
required
The Azure neural voice name.
temperature
number
The synthesis temperature, from 0 to 1. When omitted, the service defaults to the underlying voice model's default temperature.
max_concurrent_agent_runs
integer
Maximum number of target-agent runs executed concurrently during each single-turn evaluation. If omitted, the service defaults to 1. Conversation evaluation supports only 1.
candidate_search_configuration
AgentOptimizationCandidateSearchConfiguration
required
Candidate search settings.
max_candidates
integer
Maximum number of non-baseline candidates to fully evaluate. If omitted, the service defaults to 1.
baseline_agent_configuration
AgentOptimizationBaselineAgentConfiguration
Caller-supplied baseline agent values that cannot be resolved from the target agent.
system_prompt
string
Caller-supplied baseline system prompt. Omitted to resolve the baseline from the target; a prompt agent's stored definition is authoritative.
current_model
string
A non-empty Foundry model name or existing deployment name.
skills
AgentOptimizationSkill[]
Skills available for optimization. Omitted when no manual skill surface is supplied.
tools
OpenAI.ChatCompletionTool[]
Function tools available for optimization. Omitted when no manual tool surface is supplied. The optimizer may change function and argument descriptions while preserving names and parameter JSON Schema.
agent_optimization_space
AgentOptimizationSpace
required
The agent attributes and alternative values available to an agent-optimization search.
target_attributes
TargetAttribute[]
Agent attributes the optimizer may change. If omitted, the service defaults to instructions.
model_search_space
AgentOptimizationModelName[]
Alternative model names or existing deployment names available when model is an optimization target.
prompt_optimization
PromptOptimizationConfiguration
Configuration for a one-shot prompt transformation without comparative evaluation.
type
enum
required
Optimization type discriminator.
context
OptimizationContext[]
Steering context for prompt optimization. Agent trace and skill reference context are supported only by skill optimization. Omitted when no context is supplied.
skill_optimization
SkillOptimizationConfiguration
Configuration for generating a single skill candidate from trace evidence. The candidate can contain zero or more skill outcomes; no new learnings can produce an empty skill_results array without publishing versions. Optional evaluation reuses a non-generated baseline candidate.
type
enum
required
Skill optimization discriminator.
context
OptimizationContext[]
required
At least one context item containing trace evidence, optional steering guidance, and optional exact baseline references. Supply agent_traces context; use separate steering_prompt and skill_references items for guidance and baselines. For skill optimization only, a steering prompt must be non-empty and at most 100 KiB (102,400 UTF-8 bytes), enforced by the service; oversized prompts are rejected rather than truncated.
training_split_ratio
number
Fraction of generated question groups assigned to learning, strictly greater than 0 and less than 1. Defaults to 0.7 when omitted. Normalized questions and shared source traces stay in the same group, and every generated row belongs to learning or validation. The service rejects splits that leave either side empty. Caller-provided validation data is not split.
evaluation_configuration
SkillOptimizationEvaluationConfiguration
Skill-only evaluation inputs. Training-trace grading can inform single-shot learning; supported before/after comparison reports impact without gating publication.
validation_set
AgentOptimizationTargetCompletionEvaluationSet
Evaluation set containing independent single-turn inputs.
type
enum
required
Target-completion set discriminator.
source
inline | dataset_reference
required
Base source for a target-completion optimization evaluation set.
inline
AgentOptimizationTargetCompletionInlineDataSource
Supplies single-turn rows directly in the optimization request.
type
enum
required
Inline source discriminator.
test_cases
AgentOptimizationTargetCompletionTestCase[]
required
Target-completion test cases.
dataset_reference
AgentOptimizationTargetCompletionDatasetReferenceDataSource
References an explicitly versioned registered Foundry dataset for target-completion evaluation.
type
enum
required
Registered dataset source discriminator.
name
string
required
Registered dataset name.
version
string
required
Registered dataset version.
evaluators
AgentOptimizationEvaluator[]
Existing evaluator reference. At submission, supply exactly one reference or evaluator_generation_configuration, not both; the service validates this combination. After preparation, contains the resolved exact evaluator version used for training grading and supported baseline and learned-candidate evaluation.
evaluation_model
EvaluationModelConfiguration
required
Configures the model that plays the simulated user. This model is separate from the evaluated target.
model
string
required
Model deployment that generates simulated user turns, in the format {connectionName}/modelDeploymentName.
sampling_params
ModelSamplingParams
Represents a set of parameters used to control the sampling behavior of a language model during text generation.
temperature
number
The temperature parameter for sampling. Defaults to 1.0.
top_p
number
The top-p parameter for nucleus sampling. Defaults to 1.0.
seed
integer
The random seed for reproducibility. Defaults to 42.
max_completion_tokens
integer
The maximum number of tokens allowed in the completion.
voice_model
azure-standard
Voice configuration used to convert text to speech for evaluation through the Voice Live endpoint.
azure-standard
EvaluationAzureStandardVoiceModelConfiguration
Configures an Azure standard neural voice used to convert text to speech for evaluation through the Voice Live endpoint.
type
enum
required
The voice kind. Always azure-standard.
name
string
required
The Azure neural voice name.
temperature
number
The synthesis temperature, from 0 to 1. When omitted, the service defaults to the underlying voice model's default temperature.
max_concurrent_agent_runs
integer
Maximum number of target-agent runs executed concurrently during each target-completion evaluation, from 1 to 10. If omitted, the service defaults to 1.
evaluator_generation_configuration
agent_traces
Base configuration for service-generated optimization evaluators. Currently supported for skill optimization only. Uses evaluation_configuration.evaluation_model; no separate generation model is accepted.
agent_traces
AgentOptimizationTraceEvaluatorGenerationConfiguration
Generates an evaluator from the job's trace evidence or a separate evaluator-only trace selection.
type
enum
required
Generate evaluators from the agent_traces context.
trace_window
fixed | trace_ids
Trace selection window for a one-time skill optimization job.
fixed
AgentOptimizationFixedTraceWindow
Selects the latest readable trace conversations in a half-open interval, independently of feedback availability.
type
enum
required
Fixed-window discriminator.
max_traces
integer
Maximum number of trace conversations to select, from 1 to 100 inclusive. If omitted, the service defaults to 100. Selects the latest matching readable traces before collecting their annotations or evaluation results; feedback availability does not affect selection priority.
trace_ids
AgentOptimizationTraceIdsTraceWindow
Selects explicit trace IDs within the configured telemetry source and a lookback interval ending at job creation.
type
enum
required
Explicit trace-ID selection discriminator.
trace_ids
string[]
required
At least one explicit trace identifier to look up within the configured telemetry source. Service support, maximum list size, duplicate handling, and missing-ID behavior are TBD.
lookback_hours
integer
required
Telemetry lookup horizon in hours, at least 1. The half-open lookup interval starts this many hours before job creation and ends at job creation; retries do not move the anchor.
run_duration_ms
integer
required
A duration encoded as an integer number of milliseconds.
warnings
string[]
Non-fatal warnings emitted during optimization. Omitted when no warnings were produced.
Responses
The request has succeeded and a new resource has been created as a result.
Headers
Operation-Location
string
required
URL to poll for the job status.
Location
string
required
URL of the created job resource.
Body
id
string
required
Server-assigned unique identifier.
result
AgentOptimizationJobResult
Partial or terminal result produced by an agent optimization job.
candidate_summary
AgentOptimizationResultCandidateSummary
Summary of candidates produced by an agent optimization job.
completed_candidate_count
integer
required
Number of completed candidates. Does not include the baseline.
baseline_id
string
Candidate ID of the original baseline. Omitted until the baseline candidate is available.
best_id
string
Candidate ID of the highest-scoring candidate for evaluated jobs, or the selected transformed output for non-comparative jobs. Omitted until a candidate has been selected.
baseline_score
number
Normalized score of the baseline candidate from 0.0 to 1.0 for a comparatively evaluated job. Omitted otherwise and until baseline evaluation completes.
best_score
number
Best normalized score observed from 0.0 to 1.0 for a comparatively evaluated job. Omitted otherwise and until a candidate completes evaluation.
latest_promoted_candidate
AgentOptimizationCandidatePromotionInfo
Promotion metadata recorded for a candidate.
promoted_agent
AgentReference
required
type
enum
required
name
string
required
The name of the agent.
version
string
The version identifier of the agent.
token_usage
AgentOptimizationJobTokenUsage[]
required
Aggregate token usage per stage and model. Always present; empty array when no calls were measured.
latency_metrics
AgentOptimizationJobLatency[]
required
Aggregate latency per stage and model. Always present; empty when no server-measured latency is available.
termination_reason
string | enum
Reason the optimization process ended. Early termination reasons still indicate a successful job; completed candidates remain available.
enum
status
string | enum
required
Extensible status values shared by Foundry jobs.
enum
error
OpenAI.Error
misalignment
OpenAI.MisalignmentErrorDetailsResource
error_type
string | enum
enum
detailed_explanation
string
The public explanation for this block.
steer
OpenAI._MisalignmentSteer
message
string
required
The public continuation instruction.
details
OpenAI.Error[]
Additional errors that contributed to this failure.
additionalInfo
object
Additional structured information about the failure.
debugInfo
object
Diagnostic information supplied by the service for troubleshooting.
display_name
string
Human-readable label. Omitted when no label is needed; it has no uniqueness, routing, or idempotency semantics.
target_configuration
foundry_agent
Base target configuration for an optimization job.
foundry_agent
AgentOptimizationFoundryAgentTargetConfiguration
Identifies the Foundry agent that owns the configuration being optimized.
type
enum
required
Foundry-agent target discriminator.
name
string
required
Registered Foundry agent name.
version
string
Pinned agent version. Omitted to resolve and pin the latest version.
optimization_model_configuration
AgentOptimizationModelConfiguration
required
Identifies a model used by an optimization or evaluation step.
model
string
required
A non-empty Foundry model name or existing deployment name.
optimization_configuration
agent_optimization | prompt_optimization | skill_optimization
required
Base model for type-specific optimization configuration.
agent_optimization
AgentOptimizationConfiguration
Configuration for optimizing an agent for measured quality.
type
enum
required
Optimization type discriminator.
goal
string | enum
Goal for an agent-optimization job.
enum
evaluation_configuration
AgentOptimizationEvaluationConfiguration
required
Reusable quality-measurement configuration for agent optimization.
training_set
target_completion | user_conversation_simulation
required
Base discriminated model for an optimization evaluation set.
target_completion
AgentOptimizationTargetCompletionEvaluationSet
Evaluation set containing independent single-turn inputs.
type
enum
required
Target-completion set discriminator.
source
inline | dataset_reference
required
Base source for a target-completion optimization evaluation set.
inline
AgentOptimizationTargetCompletionInlineDataSource
Supplies single-turn rows directly in the optimization request.
type
enum
required
Inline source discriminator.
test_cases
AgentOptimizationTargetCompletionTestCase[]
required
Target-completion test cases.
dataset_reference
AgentOptimizationTargetCompletionDatasetReferenceDataSource
References an explicitly versioned registered Foundry dataset for target-completion evaluation.
type
enum
required
Registered dataset source discriminator.
name
string
required
Registered dataset name.
version
string
required
Registered dataset version.
user_conversation_simulation
AgentOptimizationUserConversationSimulationEvaluationSet
Evaluation set containing scenarios for simulated conversations.
type
enum
required
User-conversation-simulation set discriminator.
source
inline | dataset_reference
required
Base source for a user-conversation-simulation optimization evaluation set.
inline
AgentOptimizationUserConversationSimulationInlineDataSource
Supplies Evals user-conversation simulation test cases directly in the optimization request.
type
enum
required
Inline source discriminator.
test_cases
UserConversationSimulationTestCase[]
required
Conversation test scenarios.
dataset_reference
AgentOptimizationUserConversationSimulationDatasetReferenceDataSource
References an explicitly versioned registered Foundry dataset for user-conversation-simulation evaluation.
type
enum
required
Registered dataset source discriminator.
name
string
required
Registered dataset name.
version
string
required
Registered dataset version.
default_simulation_configuration
UserConversationSimulationConfiguration
Configures the number, length, audio effects, and simulated user behavior of conversations.
max_num_turns
integer
Hard limit on turns in each conversation. When omitted, the service defaults to 20.
conversation_repetitions
integer
Number of independent conversation repetitions for each test case. Defaults to 1 when not specified at either the data-source or test-case level.
desired_num_turns
integer
Target number of turns in each conversation. The effective value cannot exceed the effective max_num_turns. When omitted, no target is set and the simulation model determines the conversation length dynamically from the scenario.
audio_effects
UserConversationSimulationAudioEffectsConfiguration
Configures effects applied to simulated conversation audio.
effects
UserConversationSimulationAudioEffect[]
Effects to apply to simulated audio.
volume_percentage
integer
Volume of the configured audio effects, as a percentage from 1 through 100. When omitted, the service defaults to 15.
user_behavior
UserConversationSimulationUserBehaviorConfiguration
Configures conversation behavior for the simulated user.
interruption
default
Configuration for simulated user interruption behavior.
default
UserConversationSimulationDefaultInterruptionConfiguration
Configures the default interruption behavior for the simulated user.
type
enum
required
The interruption type, always default.
validation_set
target_completion | user_conversation_simulation
Base discriminated model for an optimization evaluation set.
target_completion
AgentOptimizationTargetCompletionEvaluationSet
Evaluation set containing independent single-turn inputs.
type
enum
required
Target-completion set discriminator.
source
inline | dataset_reference
required
Base source for a target-completion optimization evaluation set.
inline
AgentOptimizationTargetCompletionInlineDataSource
Supplies single-turn rows directly in the optimization request.
type
enum
required
Inline source discriminator.
test_cases
AgentOptimizationTargetCompletionTestCase[]
required
Target-completion test cases.
dataset_reference
AgentOptimizationTargetCompletionDatasetReferenceDataSource
References an explicitly versioned registered Foundry dataset for target-completion evaluation.
type
enum
required
Registered dataset source discriminator.
name
string
required
Registered dataset name.
version
string
required
Registered dataset version.
user_conversation_simulation
AgentOptimizationUserConversationSimulationEvaluationSet
Evaluation set containing scenarios for simulated conversations.
type
enum
required
User-conversation-simulation set discriminator.
source
inline | dataset_reference
required
Base source for a user-conversation-simulation optimization evaluation set.
inline
AgentOptimizationUserConversationSimulationInlineDataSource
Supplies Evals user-conversation simulation test cases directly in the optimization request.
type
enum
required
Inline source discriminator.
test_cases
UserConversationSimulationTestCase[]
required
Conversation test scenarios.
dataset_reference
AgentOptimizationUserConversationSimulationDatasetReferenceDataSource
References an explicitly versioned registered Foundry dataset for user-conversation-simulation evaluation.
type
enum
required
Registered dataset source discriminator.
name
string
required
Registered dataset name.
version
string
required
Registered dataset version.
default_simulation_configuration
UserConversationSimulationConfiguration
Configures the number, length, audio effects, and simulated user behavior of conversations.
max_num_turns
integer
Hard limit on turns in each conversation. When omitted, the service defaults to 20.
conversation_repetitions
integer
Number of independent conversation repetitions for each test case. Defaults to 1 when not specified at either the data-source or test-case level.
desired_num_turns
integer
Target number of turns in each conversation. The effective value cannot exceed the effective max_num_turns. When omitted, no target is set and the simulation model determines the conversation length dynamically from the scenario.
audio_effects
UserConversationSimulationAudioEffectsConfiguration
Configures effects applied to simulated conversation audio.
effects
UserConversationSimulationAudioEffect[]
Effects to apply to simulated audio.
volume_percentage
integer
Volume of the configured audio effects, as a percentage from 1 through 100. When omitted, the service defaults to 15.
user_behavior
UserConversationSimulationUserBehaviorConfiguration
Configures conversation behavior for the simulated user.
interruption
default
Configuration for simulated user interruption behavior.
default
UserConversationSimulationDefaultInterruptionConfiguration
Configures the default interruption behavior for the simulated user.
type
enum
required
The interruption type, always default.
evaluators
AgentOptimizationEvaluator[]
required
Evaluator references used to score candidate quality.
evaluation_model
EvaluationModelConfiguration
required
Configures the model that plays the simulated user. This model is separate from the evaluated target.
model
string
required
Model deployment that generates simulated user turns, in the format {connectionName}/modelDeploymentName.
sampling_params
ModelSamplingParams
Represents a set of parameters used to control the sampling behavior of a language model during text generation.
temperature
number
The temperature parameter for sampling. Defaults to 1.0.
top_p
number
The top-p parameter for nucleus sampling. Defaults to 1.0.
seed
integer
The random seed for reproducibility. Defaults to 42.
max_completion_tokens
integer
The maximum number of tokens allowed in the completion.
voice_model
azure-standard
Voice configuration used to convert text to speech for evaluation through the Voice Live endpoint.
azure-standard
EvaluationAzureStandardVoiceModelConfiguration
Configures an Azure standard neural voice used to convert text to speech for evaluation through the Voice Live endpoint.
type
enum
required
The voice kind. Always azure-standard.
name
string
required
The Azure neural voice name.
temperature
number
The synthesis temperature, from 0 to 1. When omitted, the service defaults to the underlying voice model's default temperature.
max_concurrent_agent_runs
integer
Maximum number of target-agent runs executed concurrently during each single-turn evaluation. If omitted, the service defaults to 1. Conversation evaluation supports only 1.
candidate_search_configuration
AgentOptimizationCandidateSearchConfiguration
required
Candidate search settings.
max_candidates
integer
Maximum number of non-baseline candidates to fully evaluate. If omitted, the service defaults to 1.
baseline_agent_configuration
AgentOptimizationBaselineAgentConfiguration
Caller-supplied baseline agent values that cannot be resolved from the target agent.
system_prompt
string
Caller-supplied baseline system prompt. Omitted to resolve the baseline from the target; a prompt agent's stored definition is authoritative.
current_model
string
A non-empty Foundry model name or existing deployment name.
skills
AgentOptimizationSkill[]
Skills available for optimization. Omitted when no manual skill surface is supplied.
tools
OpenAI.ChatCompletionTool[]
Function tools available for optimization. Omitted when no manual tool surface is supplied. The optimizer may change function and argument descriptions while preserving names and parameter JSON Schema.
agent_optimization_space
AgentOptimizationSpace
required
The agent attributes and alternative values available to an agent-optimization search.
target_attributes
TargetAttribute[]
Agent attributes the optimizer may change. If omitted, the service defaults to instructions.
model_search_space
AgentOptimizationModelName[]
Alternative model names or existing deployment names available when model is an optimization target.
prompt_optimization
PromptOptimizationConfiguration
Configuration for a one-shot prompt transformation without comparative evaluation.
type
enum
required
Optimization type discriminator.
context
OptimizationContext[]
Steering context for prompt optimization. Agent trace and skill reference context are supported only by skill optimization. Omitted when no context is supplied.
skill_optimization
SkillOptimizationConfiguration
Configuration for generating a single skill candidate from trace evidence. The candidate can contain zero or more skill outcomes; no new learnings can produce an empty skill_results array without publishing versions. Optional evaluation reuses a non-generated baseline candidate.
type
enum
required
Skill optimization discriminator.
context
OptimizationContext[]
required
At least one context item containing trace evidence, optional steering guidance, and optional exact baseline references. Supply agent_traces context; use separate steering_prompt and skill_references items for guidance and baselines. For skill optimization only, a steering prompt must be non-empty and at most 100 KiB (102,400 UTF-8 bytes), enforced by the service; oversized prompts are rejected rather than truncated.
training_split_ratio
number
Fraction of generated question groups assigned to learning, strictly greater than 0 and less than 1. Defaults to 0.7 when omitted. Normalized questions and shared source traces stay in the same group, and every generated row belongs to learning or validation. The service rejects splits that leave either side empty. Caller-provided validation data is not split.
evaluation_configuration
SkillOptimizationEvaluationConfiguration
Skill-only evaluation inputs. Training-trace grading can inform single-shot learning; supported before/after comparison reports impact without gating publication.
validation_set
AgentOptimizationTargetCompletionEvaluationSet
Evaluation set containing independent single-turn inputs.
type
enum
required
Target-completion set discriminator.
source
inline | dataset_reference
required
Base source for a target-completion optimization evaluation set.
inline
AgentOptimizationTargetCompletionInlineDataSource
Supplies single-turn rows directly in the optimization request.
type
enum
required
Inline source discriminator.
test_cases
AgentOptimizationTargetCompletionTestCase[]
required
Target-completion test cases.
dataset_reference
AgentOptimizationTargetCompletionDatasetReferenceDataSource
References an explicitly versioned registered Foundry dataset for target-completion evaluation.
type
enum
required
Registered dataset source discriminator.
name
string
required
Registered dataset name.
version
string
required
Registered dataset version.
evaluators
AgentOptimizationEvaluator[]
Existing evaluator reference. At submission, supply exactly one reference or evaluator_generation_configuration, not both; the service validates this combination. After preparation, contains the resolved exact evaluator version used for training grading and supported baseline and learned-candidate evaluation.
evaluation_model
EvaluationModelConfiguration
required
Configures the model that plays the simulated user. This model is separate from the evaluated target.
model
string
required
Model deployment that generates simulated user turns, in the format {connectionName}/modelDeploymentName.
sampling_params
ModelSamplingParams
Represents a set of parameters used to control the sampling behavior of a language model during text generation.
temperature
number
The temperature parameter for sampling. Defaults to 1.0.
top_p
number
The top-p parameter for nucleus sampling. Defaults to 1.0.
seed
integer
The random seed for reproducibility. Defaults to 42.
max_completion_tokens
integer
The maximum number of tokens allowed in the completion.
voice_model
azure-standard
Voice configuration used to convert text to speech for evaluation through the Voice Live endpoint.
azure-standard
EvaluationAzureStandardVoiceModelConfiguration
Configures an Azure standard neural voice used to convert text to speech for evaluation through the Voice Live endpoint.
type
enum
required
The voice kind. Always azure-standard.
name
string
required
The Azure neural voice name.
temperature
number
The synthesis temperature, from 0 to 1. When omitted, the service defaults to the underlying voice model's default temperature.
max_concurrent_agent_runs
integer
Maximum number of target-agent runs executed concurrently during each target-completion evaluation, from 1 to 10. If omitted, the service defaults to 1.
evaluator_generation_configuration
agent_traces
Base configuration for service-generated optimization evaluators. Currently supported for skill optimization only. Uses evaluation_configuration.evaluation_model; no separate generation model is accepted.
agent_traces
AgentOptimizationTraceEvaluatorGenerationConfiguration
Generates an evaluator from the job's trace evidence or a separate evaluator-only trace selection.
type
enum
required
Generate evaluators from the agent_traces context.
trace_window
fixed | trace_ids
Trace selection window for a one-time skill optimization job.
fixed
AgentOptimizationFixedTraceWindow
Selects the latest readable trace conversations in a half-open interval, independently of feedback availability.
type
enum
required
Fixed-window discriminator.
max_traces
integer
Maximum number of trace conversations to select, from 1 to 100 inclusive. If omitted, the service defaults to 100. Selects the latest matching readable traces before collecting their annotations or evaluation results; feedback availability does not affect selection priority.
trace_ids
AgentOptimizationTraceIdsTraceWindow
Selects explicit trace IDs within the configured telemetry source and a lookback interval ending at job creation.
type
enum
required
Explicit trace-ID selection discriminator.
trace_ids
string[]
required
At least one explicit trace identifier to look up within the configured telemetry source. Service support, maximum list size, duplicate handling, and missing-ID behavior are TBD.
lookback_hours
integer
required
Telemetry lookup horizon in hours, at least 1. The half-open lookup interval starts this many hours before job creation and ends at job creation; retries do not move the anchor.
run_duration_ms
integer
required
A duration encoded as an integer number of milliseconds.
warnings
string[]
Non-fatal warnings emitted during optimization. Omitted when no warnings were produced.
Request
POST /agent_optimization_jobs HTTP/1.1
Response
Status: 201
Content-Type: application/json
Status: 4XX
Content-Type: application/json
Status: 5XX
Content-Type: application/json