AgentOptimizationJobs
Promote a candidate for an agent optimization job
Promotes a candidate to the Foundry agent stored in the parent job's target configuration. Promotion is unavailable when the job omitted target_configuration. Prompt-agent promotion creates a new agent version. Hosted-agent promotion currently records promotion metadata without deploying a new hosted-agent version.
Path parameters
jobId
string
required
The ID of the parent optimization job.
candidateId
string
required
The candidate identifier.
Query parameters
api-version
string
required
The API version to use for this operation.
Responses
The request has succeeded.
Body
candidate_id
string
required
Server-assigned candidate identifier.
job_id
string
required
Identifier of the parent optimization job.
name
string
required
Display name of the candidate (e.g., 'baseline', 'instruction-v2').
status
string | enum
required
The candidate's lifecycle state.
enum
output
agent_optimization | prompt_optimization
Base candidate output. Job types define derived output models with their own fields.
agent_optimization
AgentOptimizationAgentCandidateOutput
Candidate output produced by an agent-optimization job.
type
enum
required
mutations
AgentOptimizationMutation[]
Typed configuration mutations applied to the baseline. Omitted for the baseline candidate. LIST without expand=mutations returns mutation items with only type; expanded LIST and candidate GET populate each mutation's value.
prompt_optimization
AgentOptimizationPromptCandidateOutput
Candidate output produced by a prompt-optimization job.
type
enum
required
mutations
AgentOptimizationMutation[]
Typed configuration mutations applied to the baseline. Omitted for the baseline candidate. LIST without expand=mutations returns mutation items with only type; expanded LIST and candidate GET populate each mutation's value.
rationale
string
Human-readable explanation of why the optimizer produced this candidate. Populated on candidate GET when available and omitted from LIST.
agent_version
string
Foundry agent version associated with this candidate. Omitted when no temporary or evaluated agent version was created.
evaluation
AgentOptimizationCandidateEvaluation
Comparative evaluation summary for a candidate.
score
number
Average composite score across evaluated tasks. Omitted until scoring produces an aggregate score.
avg_tokens
number
Average total tokens consumed per task. Omitted when token usage was not measured.
avg_latency_ms
integer
A duration encoded as an integer number of milliseconds.
eval_id
string
Foundry evaluation identifier used to score this candidate. Omitted when unavailable.
eval_run_id
string
Foundry evaluation run identifier used to score this candidate. Omitted when unavailable.
promotion
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.
Request
POST /agent_optimization_jobs/{jobId}/candidates/{candidateId}:promote HTTP/1.1Response
Status: 200
Content-Type: application/jsonStatus: 4XX
Content-Type: application/jsonStatus: 5XX
Content-Type: application/json