Skip to content

API Cleanup initial pass(merge sqush jugonzales/agents-optimization-v2preview) #43927

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
glecaros merged 5 commits into from
Jun 12, 2026
Merged

API Cleanup initial pass(merge sqush jugonzales/agents-optimization-v2preview) #43927

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0c7b766
rebase to /feature/foundry-release and merge sqush jugonzales/agents-…
YoYoJa Jun 11, 2026
652cae6
resolve missing file
YoYoJa Jun 11, 2026
ac5641e
address comment for minValue of max_candidates
YoYoJa Jun 12, 2026
15c9a73
address comments of OptimizationInlineDatasetInput.type
YoYoJa Jun 12, 2026
3179780
address coment of OptimizationJobListItem
YoYoJa Jun 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2,001 changes: 589 additions & 1,412 deletions specification/ai-foundry/data-plane/Foundry/openapi3/v1/microsoft-foundry-openapi3.json
View file
Open in desktop

Large diffs are not rendered by default.

1,002 changes: 212 additions & 790 deletions specification/ai-foundry/data-plane/Foundry/openapi3/v1/microsoft-foundry-openapi3.yaml
View file
Open in desktop

Large diffs are not rendered by default.

2,001 changes: 589 additions & 1,412 deletions ...oundry/data-plane/Foundry/openapi3/virtual-public-preview/microsoft-foundry-openapi3.json
View file
Open in desktop

Large diffs are not rendered by default.

1,002 changes: 212 additions & 790 deletions ...oundry/data-plane/Foundry/openapi3/virtual-public-preview/microsoft-foundry-openapi3.yaml
View file
Open in desktop

Large diffs are not rendered by default.

319 changes: 120 additions & 199 deletions specification/ai-foundry/data-plane/Foundry/src/agents-optimization/models.tsp
View file
Open in desktop

Large diffs are not rendered by default.

222 changes: 21 additions & 201 deletions specification/ai-foundry/data-plane/Foundry/src/agents-optimization/routes.tsp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ namespace Azure.AI.Projects;

const AgentOptimizationRequiredPreviews = #{
conditional_previews: #[
FoundryFeaturesOptInKeys.agents_optimization_v1_preview
FoundryFeaturesOptInKeys.agents_optimization_v2_preview
],
};

Expand All @@ -28,55 +28,31 @@ const AgentOptimizationRequiredPreviews = #{
#suppress "@azure-tools/typespec-azure-core/long-running-polling-operation-required" "LRO polling is handled by the client via Operation-Location"
@tag("AgentOptimizationJobs")
interface AgentOptimizationJobs {
/**
* Creates an agent optimization job and returns the queued job.
* Honors `Operation-Id` for idempotent retry.
*/
@summary("Create an agent optimization job")
@summary("Creates an agent optimization job.")
@doc("Create an optimization job. Returns 201 with the queued job. Honours `Operation-Id` for idempotent retry.")
@route("agent_optimization_jobs")
@extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
@post
create is FoundryDataPlanePreviewOperation<
FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
{
...WithOperationId;

@doc("The optimization job inputs.")
@body
inputs: OptimizationJobInputs;
},
JobCreatedResponse<OptimizationJob>
create is postJobPreview<
FoundryFeaturesOptInKeys.agents_optimization_v2_preview,
OptimizationJob
>;

/**
* Retrieves the specified agent optimization job.
* Returns 202 while the job is in progress and 200 after it reaches a terminal state.
*/
@summary("Get an agent optimization job")
@summary("Get info about an agent optimization job.")
@doc("Get an optimization job by id.")
@route("agent_optimization_jobs/{jobId}")
@extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
@get
get is FoundryDataPlanePreviewOperation<
FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
{
/** The ID of the job. */
@path jobId: string;
},
OptimizationJob & {
@statusCode _: 200 | 202;
@header("Retry-After") retryAfter?: int32;
}
get is queryJobStatusPreview<
FoundryFeaturesOptInKeys.agents_optimization_v2_preview,
OptimizationJob
>;

/**
* Returns agent optimization jobs with cursor pagination and optional lifecycle or agent filters.
*/
@summary("List agent optimization jobs")
@summary("Returns a list of agent optimization jobs.")
@doc("List optimization jobs. Supports cursor pagination and optional status / agent_name filters.")
@route("agent_optimization_jobs")
@extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
list is listJobsPreview<
FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
OptimizationJob,
FoundryFeaturesOptInKeys.agents_optimization_v2_preview,
OptimizationJobListItem,
{
@doc("Filter to jobs in this lifecycle state.")
@query
Expand All @@ -88,175 +64,19 @@ interface AgentOptimizationJobs {
}
>;

/**
* Requests cancellation of the specified agent optimization job.
* The operation remains idempotent after the job reaches a terminal state.
*/
@summary("Cancel an agent optimization job")
@summary("Cancels an agent optimization job.")
@doc("Request cancellation of a running or queued job. Returns an error if the job is already in a terminal state.")
@route("agent_optimization_jobs/{jobId}:cancel")
@extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
cancel is cancelJobPreview<
FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
FoundryFeaturesOptInKeys.agents_optimization_v2_preview,
OptimizationJob
>;

/**
* Deletes the specified agent optimization job and its candidate artifacts.
* Cancels the job first when it is still in a non-terminal state.
*/
@summary("Delete an agent optimization job")
@summary("Deletes an agent optimization job.")
@doc("Delete the job and its candidate artifacts. Cancels first if non-terminal.")
@route("agent_optimization_jobs/{jobId}")
@extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
@delete
delete is FoundryDataPlanePreviewOperation<
FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
{
@doc("The ID of the job to delete.")
@path
jobId: string;

@doc("When true, force-delete even if the job is in a non-terminal state.")
@query
force?: boolean;
},
NoContentResponse
>;

// ---------------------------------------------------------------------------
// Candidate sub-resource operations
// ---------------------------------------------------------------------------

/**
* Returns the candidates produced by the specified optimization job.
*/
@summary("List optimization job candidates")
@route("agent_optimization_jobs/{jobId}/candidates")
@extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
@get
@list
listCandidates is FoundryDataPlanePreviewOperation<
FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
{
@doc("The optimization job id.")
@path
jobId: string;
delete is deleteJobPreview<FoundryFeaturesOptInKeys.agents_optimization_v2_preview>;

...CommonPageQueryParameters;
},
AgentsPagedResult<OptimizationCandidate>
>;

/**
* Retrieves metadata, manifest information, and promotion details for the specified candidate.
*/
@summary("Get an optimization candidate")
@route("agent_optimization_jobs/{jobId}/candidates/{candidateId}")
@extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
@get
getCandidate is FoundryDataPlanePreviewOperation<
FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
{
@doc("The optimization job id.")
@path
jobId: string;

@doc("The candidate id.")
@path
candidateId: string;
},
CandidateMetadata
>;

/**
* Retrieves the deploy configuration JSON for the specified candidate.
* Clients can use it to compose `agents.create_version(...)` requests.
*/
@summary("Get an optimization candidate config")
@route("agent_optimization_jobs/{jobId}/candidates/{candidateId}/config")
@extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
@get
getCandidateConfig is FoundryDataPlanePreviewOperation<
FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
{
@doc("The optimization job id.")
@path
jobId: string;

@doc("The candidate id.")
@path
candidateId: string;
},
CandidateDeployConfig
>;

/**
* Retrieves full per-task evaluation results for the specified candidate.
*/
@summary("Get optimization candidate results")
@route("agent_optimization_jobs/{jobId}/candidates/{candidateId}/results")
@extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
@get
getCandidateResults is FoundryDataPlanePreviewOperation<
FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
{
@doc("The optimization job id.")
@path
jobId: string;

@doc("The candidate id.")
@path
candidateId: string;
},
CandidateResults
>;

/**
* Streams the specified file from the candidate's blob directory.
*/
@summary("Get an optimization candidate file")
@route("agent_optimization_jobs/{jobId}/candidates/{candidateId}/files")
@extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
@get
getCandidateFile is FoundryDataPlanePreviewOperation<
FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
{
@doc("The optimization job id.")
@path
jobId: string;

@doc("The candidate id.")
@path
candidateId: string;

@doc("Relative path of the file to download (e.g. 'files/examples.jsonl').")
@query
path: string;
},
bytes
>;

/**
* Promotes the specified candidate and records the deployment timestamp and target agent version.
*/
@summary("Promote an optimization candidate")
@route("agent_optimization_jobs/{jobId}/candidates/{candidateId}:promote")
@extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
@post
promoteCandidate is FoundryDataPlanePreviewOperation<
FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
{
@doc("The optimization job id.")
@path
jobId: string;

@doc("The candidate id to promote.")
@path
candidateId: string;

@doc("Promotion details.")
@body
candidate_request: PromoteCandidateRequest;
},
PromoteCandidateResponse
>;
}
21 changes: 0 additions & 21 deletions specification/ai-foundry/data-plane/Foundry/src/sdk-common/beta-ops-relocation-agents.tsp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,24 +68,3 @@ interface Agents {}
@@clientLocation(Azure.AI.Projects.AgentOptimizationJobs.list, Agents);
@@clientLocation(Azure.AI.Projects.AgentOptimizationJobs.cancel, Agents);
@@clientLocation(Azure.AI.Projects.AgentOptimizationJobs.delete, Agents);
@@clientLocation(
Azure.AI.Projects.AgentOptimizationJobs.listCandidates,
Agents
);
@@clientLocation(Azure.AI.Projects.AgentOptimizationJobs.getCandidate, Agents);
@@clientLocation(
Azure.AI.Projects.AgentOptimizationJobs.getCandidateConfig,
Agents
);
@@clientLocation(
Azure.AI.Projects.AgentOptimizationJobs.getCandidateResults,
Agents
);
@@clientLocation(
Azure.AI.Projects.AgentOptimizationJobs.getCandidateFile,
Agents
);
@@clientLocation(
Azure.AI.Projects.AgentOptimizationJobs.promoteCandidate,
Agents
);
13 changes: 0 additions & 13 deletions specification/ai-foundry/data-plane/Foundry/src/sdk-python-js-azure-ai-projects/client.tsp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,19 +191,6 @@ using Azure.AI.Projects;
@@clientName(AgentOptimizationJobs.list, "listOptimizationJobs");
@@clientName(AgentOptimizationJobs.cancel, "cancelOptimizationJob");
@@clientName(AgentOptimizationJobs.delete, "deleteOptimizationJob");
@@clientName(
AgentOptimizationJobs.listCandidates,
"listOptimizationCandidates"
);
@@clientName(AgentOptimizationJobs.getCandidate, "getOptimizationCandidate");
@@clientName(
AgentOptimizationJobs.getCandidateConfig,
"getOptimizationCandidateConfig"
);
@@clientName(
AgentOptimizationJobs.getCandidateResults,
"getOptimizationCandidateResults"
);

// DatasetItem model has a property `response_items?: OpenAI.OutputItem[]`. It is used
// to define Agent optimization request. If emitted as-is, it pulls in a lot of
Expand Down
2 changes: 1 addition & 1 deletion specification/ai-foundry/data-plane/Foundry/src/servicepatterns.tsp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ union FoundryFeaturesOptInKeys {
skills_v1_preview: "Skills=V1Preview",
data_generation_jobs_v1_preview: "DataGenerationJobs=V1Preview",
models_v1_preview: "Models=V1Preview",
agents_optimization_v1_preview: "AgentsOptimization=V1Preview",
agents_optimization_v2_preview: "AgentsOptimization=V2Preview",

@glecaros glecaros Jun 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

asked in the other PR, is there a strong reason not to use the opt-in key we were using before?

@YoYoJa YoYoJa Jun 12, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As V2 removed lots of useless properties from V1 to align with the job guidelines more correctly, but V1 is already released in previous sdk version per Justin, so bumped to V2 here to make it less confusion.
And service side is still supporting V1 as a backward now for smooth inergration from UI and kinds of tests platform while rollout the change.

@glecaros glecaros Jun 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the whole point of the endpoints being in preview, is to signal users that breaking changes are to be expected, not sure the value we are adding by replacing the string for the opt-in key.

@YoYoJa YoYoJa Jun 12, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We still need do backward from service side, since UI and kinds of our tests also need time to rollout to different region to switch from V1 to V2.

}

alias WithRequiredFoundryPreviewHeader<RequiredPreviewOptInHeader extends
Expand Down
Loading