AgentsClient Class
- java.
lang. Object - com.
azure. ai. agents. AgentsClient
- com.
public final class AgentsClient
Initializes a new instance of the synchronous AgentsClient type.
Method Summary
| Modifier and Type | Method and Description |
|---|---|
|
Sync |
beginCreateOptimizationJob(AgentOptimizationJob job)
Create an agent optimization job Creates an optimization job and returns the queued job. |
|
Sync |
beginCreateOptimizationJob(AgentOptimizationJob job, String operationId)
Create an agent optimization job Creates an optimization job and returns the queued job. |
|
Sync |
beginCreateOptimizationJob(BinaryData job, RequestOptions requestOptions)
Create an agent optimization job Creates an optimization job and returns the queued job. |
|
Agent |
cancelOptimizationJob(String jobId)
Cancel an agent optimization job Requests cancellation of a running or queued job. |
|
Response<Binary |
cancelOptimizationJobWithResponse(String jobId, RequestOptions requestOptions)
Cancel an agent optimization job Requests cancellation of a running or queued job. |
|
Agent |
createAgentVersion(String agentName, AgentDefinition definition)
Create an agent version Creates a new version for the specified agent and returns the created version resource. |
|
Agent |
createAgentVersion(String agentName, AgentDefinition definition, Map<String,String> metadata, String description)
Create a new agent version. |
|
Agent |
createAgentVersion(String agentName, CreateAgentVersionInput createAgentVersionInput)
Create a new agent version. |
|
Agent |
createAgentVersionFromCode(String agentName, HostedAgentDefinition definition, CodeFileDetails code, String description, Map<String,String> metadata)
Create a new code-based hosted agent version. |
|
Agent |
createAgentVersionFromCode(String agentName, String codeZipSha256, CreateAgentVersionFromCodeContent content)
Create an agent version from code Creates a new agent version from code. |
|
Agent |
createAgentVersionFromManifest(String agentName, String manifestId, Map<String,BinaryData> parameterValues)
Create an agent version from manifest Imports the provided manifest to create a new version for the specified agent. |
|
Agent |
createAgentVersionFromManifest(String agentName, String manifestId, Map<String,BinaryData> parameterValues, Map<String,String> metadata, String description)
Create an agent version from manifest Imports the provided manifest to create a new version for the specified agent. |
|
Response<Binary |
createAgentVersionFromManifestWithResponse(String agentName, BinaryData createAgentVersionFromManifestRequest, RequestOptions requestOptions)
Create an agent version from manifest Imports the provided manifest to create a new version for the specified agent. |
|
Response<Binary |
createAgentVersionWithResponse(String agentName, BinaryData createAgentVersionRequest, RequestOptions requestOptions)
Create an agent version Creates a new version for the specified agent and returns the created version resource. |
|
Agent |
createSession(String agentName, VersionIndicator versionIndicator)
Create a session Creates a new session for an agent endpoint. |
|
Agent |
createSession(String agentName, VersionIndicator versionIndicator, String agentSessionId)
Create a session Creates a new session for an agent endpoint. |
|
Response<Binary |
createSessionWithResponse(String agentName, BinaryData createSessionRequest, RequestOptions requestOptions)
Create a session Creates a new session for an agent endpoint. |
| void |
deleteAgent(String agentName)
Deletes an agent. |
| void |
deleteAgentVersion(String agentName, String agentVersion)
Deletes a specific version of an agent. |
| Response<Void> |
deleteAgentVersionWithResponse(String agentName, String agentVersion, RequestOptions requestOptions)
Deletes a specific version of an agent. |
| Response<Void> |
deleteAgentWithResponse(String agentName, RequestOptions requestOptions)
Deletes an agent. |
| void |
deleteOptimizationJob(String jobId)
Delete an agent optimization job Cancels active work, then deletes the job and its candidate artifacts. |
| Response<Void> |
deleteOptimizationJobWithResponse(String jobId, RequestOptions requestOptions)
Delete an agent optimization job Cancels active work, then deletes the job and its candidate artifacts. |
| void |
deleteSession(String agentName, String sessionId)
Delete a session Deletes a session synchronously. |
| void |
deleteSessionFile(String agentName, String sessionId, String path)
Delete a session file Deletes the specified file or directory from the session sandbox. |
| void |
deleteSessionFile(String agentName, String sessionId, String path, Boolean recursive)
Delete a session file Deletes the specified file or directory from the session sandbox. |
| Response<Void> |
deleteSessionFileWithResponse(String agentName, String sessionId, String path, RequestOptions requestOptions)
Delete a session file Deletes the specified file or directory from the session sandbox. |
| Response<Void> |
deleteSessionWithResponse(String agentName, String sessionId, RequestOptions requestOptions)
Delete a session Deletes a session synchronously. |
| void |
disableAgent(String agentName)
Disable an agent Disables the specified agent, preventing it from accepting new sessions or processing requests. |
| Response<Void> |
disableAgentWithResponse(String agentName, RequestOptions requestOptions)
Disable an agent Disables the specified agent, preventing it from accepting new sessions or processing requests. |
|
Binary |
downloadAgentCode(String agentName)
Download agent code Downloads the code zip for a code-based hosted agent. |
|
Binary |
downloadAgentCode(String agentName, String agentVersion)
Download agent code Downloads the code zip for a code-based hosted agent. |
| void |
downloadAgentCode(String agentName, String agentVersion, String filePath)
Download agent code Downloads the code zip for a code-based hosted agent. |
| void |
downloadAgentCode(String agentName, String agentVersion, String filePath, boolean overwrite)
Download agent code Downloads the code zip for a code-based hosted agent and writes it to |
|
Response<Binary |
downloadAgentCodeWithResponse(String agentName, RequestOptions requestOptions)
Download agent code Downloads the code zip for a code-based hosted agent. |
| Response<Void> |
downloadAgentCodeWithResponse(String agentName, String filePath, boolean overwrite, RequestOptions requestOptions)
Download agent code Downloads the code zip for a code-based hosted agent and writes it to |
| Response<Void> |
downloadAgentCodeWithResponse(String agentName, String filePath, RequestOptions requestOptions)
Download agent code Downloads the code zip for a code-based hosted agent. |
|
Binary |
downloadSessionFile(String agentName, String sessionId, String path)
Download a session file Downloads the file at the specified sandbox path as a binary stream. |
| Response<Void> |
downloadSessionFileWithResponse(String agentName, String agentSessionId, String path, String filePath, boolean overwrite, RequestOptions requestOptions)
Download a session file Downloads the file at the specified sandbox path and writes it to |
| Response<Void> |
downloadSessionFileWithResponse(String agentName, String agentSessionId, String path, String filePath, RequestOptions requestOptions)
Download a session file Downloads the file at the specified sandbox path as a binary stream. |
|
Response<Binary |
downloadSessionFileWithResponse(String agentName, String sessionId, String path, RequestOptions requestOptions)
Download a session file Downloads the file at the specified sandbox path as a binary stream. |
| void |
enableAgent(String agentName)
Enable an agent Enables the specified agent, allowing it to accept new sessions and process requests. |
| Response<Void> |
enableAgentWithResponse(String agentName, RequestOptions requestOptions)
Enable an agent Enables the specified agent, allowing it to accept new sessions and process requests. |
|
Agent |
estimateOptimizationJob(AgentOptimizationEstimateInputs inputs)
Estimate an agent optimization job Estimates validation-set rows, per-stage model call volumes, and cost bands without submitting the job. |
|
Response<Binary |
estimateOptimizationJobWithResponse(BinaryData inputs, RequestOptions requestOptions)
Estimate an agent optimization job Estimates validation-set rows, per-stage model call volumes, and cost bands without submitting the job. |
|
Agent |
getAgent(String agentName)
Get an agent Retrieves an agent definition by its unique name. |
|
Agent |
getAgentVersionDetails(String agentName, String agentVersion)
Get an agent version Retrieves the specified version of an agent by its agent name and version identifier. |
|
Response<Binary |
getAgentVersionDetailsWithResponse(String agentName, String agentVersion, RequestOptions requestOptions)
Get an agent version Retrieves the specified version of an agent by its agent name and version identifier. |
|
Response<Binary |
getAgentWithResponse(String agentName, RequestOptions requestOptions)
Get an agent Retrieves an agent definition by its unique name. |
|
Binary |
getMicrosoft365AppPackage(GetMicrosoft365AppPackageOptions options)
Generate a Microsoft 365 app package Generates the Microsoft Teams app package (zip) for a Foundry agent from the supplied publish request, without publishing it. |
|
Response<Binary |
getMicrosoft365AppPackageWithResponse(String agentName, BinaryData getMicrosoft365AppPackageRequest, RequestOptions requestOptions)
Generate a Microsoft 365 app package Generates the Microsoft Teams app package (zip) for a Foundry agent from the supplied publish request, without publishing it. |
|
Microsoft365Publish |
getMicrosoft365PublishDefaults(String agentName)
Get Microsoft 365 publish defaults Returns default and previously-published values used to pre-populate a Microsoft 365 publish request for a Foundry agent. |
|
Microsoft365Publish |
getMicrosoft365PublishDefaults(String agentName, Boolean publishAsDigitalWorker)
Get Microsoft 365 publish defaults Returns default and previously-published values used to pre-populate a Microsoft 365 publish request for a Foundry agent. |
|
Response<Binary |
getMicrosoft365PublishDefaultsWithResponse(String agentName, RequestOptions requestOptions)
Get Microsoft 365 publish defaults Returns default and previously-published values used to pre-populate a Microsoft 365 publish request for a Foundry agent. |
|
Agent |
getOptimizationCandidate(String jobId, String candidateId)
Get a candidate for an agent optimization job Retrieves a single candidate. |
|
Response<Binary |
getOptimizationCandidateWithResponse(String jobId, String candidateId, RequestOptions requestOptions)
Get a candidate for an agent optimization job Retrieves a single candidate. |
|
Agent |
getOptimizationJob(String jobId)
Get an agent optimization job Retrieves an optimization job by its identifier. |
|
Response<Binary |
getOptimizationJobWithResponse(String jobId, RequestOptions requestOptions)
Get an agent optimization job Retrieves an optimization job by its identifier. |
|
Agent |
getSession(String agentName, String sessionId)
Get a session Retrieves the details of a hosted agent session by agent name and session identifier. |
|
Iterable |
getSessionLogStream(String agentName, String agentVersion, String sessionId)
Streams console logs (stdout / stderr) for a specific hosted agent session as typed SessionLogEvent values. |
|
Iterable |
getSessionLogStream(String agentName, String agentVersion, String sessionId, RequestOptions requestOptions)
Streams console logs (stdout / stderr) for a specific hosted agent session as typed SessionLogEvent values. |
|
Response<Binary |
getSessionLogStreamWithResponse(String agentName, String agentVersion, String sessionId, RequestOptions requestOptions)
Stream console logs for a hosted agent session Streams console logs (stdout / stderr) for a specific hosted agent session as a Server-Sent Events (SSE) stream. |
|
Response<Binary |
getSessionWithResponse(String agentName, String sessionId, RequestOptions requestOptions)
Get a session Retrieves the details of a hosted agent session by agent name and session identifier. |
|
Paged |
listAgentConversations()
List conversations Returns the conversations available in the current project. |
|
Paged |
listAgentConversations(Integer limit, PageOrder order, String after, String before, String agentName, String agentId)
Returns the list of all conversations. |
|
Paged |
listAgentConversations(Integer limit, PageOrder order, String after, String before, String agentName, String agentId, String userIdentity)
List conversations Returns the conversations available in the current project. |
|
Paged |
listAgentConversations(RequestOptions requestOptions)
List conversations Returns the conversations available in the current project. |
|
Paged |
listAgents()
List agents Returns a paged collection of agent resources. |
|
Paged |
listAgents(AgentKind kind, Integer limit, PageOrder order, String after, String before)
List agents Returns a paged collection of agent resources. |
|
Paged |
listAgents(RequestOptions requestOptions)
List agents Returns a paged collection of agent resources. |
|
Paged |
listAgentVersions(String agentName)
List agent versions Returns a paged collection of versions for the specified agent. |
|
Paged |
listAgentVersions(String agentName, Integer limit, PageOrder order, String after, String before, Boolean includeDrafts)
List agent versions Returns a paged collection of versions for the specified agent. |
|
Paged |
listAgentVersions(String agentName, RequestOptions requestOptions)
List agent versions Returns a paged collection of versions for the specified agent. |
|
Paged |
listOptimizationCandidates(String jobId)
List candidates for an agent optimization job Lists candidates for the given optimization job with cursor pagination, including the original baseline and generated candidates. |
|
Paged |
listOptimizationCandidates(String jobId, List<AgentOptimizationCandidateExpand> expand, Integer limit, PageOrder order, String after, String before)
List candidates for an agent optimization job Lists candidates for the given optimization job with cursor pagination, including the original baseline and generated candidates. |
|
Paged |
listOptimizationCandidates(String jobId, RequestOptions requestOptions)
List candidates for an agent optimization job Lists candidates for the given optimization job with cursor pagination, including the original baseline and generated candidates. |
|
Paged |
listOptimizationJobs()
List agent optimization jobs Lists optimization jobs with cursor pagination and optional status or agent name filters. |
|
Paged |
listOptimizationJobs(Integer limit, PageOrder order, String after, String before, JobStatus status, String agentName)
List agent optimization jobs Lists optimization jobs with cursor pagination and optional status or agent name filters. |
|
Paged |
listOptimizationJobs(RequestOptions requestOptions)
List agent optimization jobs Lists optimization jobs with cursor pagination and optional status or agent name filters. |
|
Paged |
listSessionFiles(String agentName, String sessionId)
List session files Returns files and directories at the specified path in the session sandbox. |
|
Paged |
listSessionFiles(String agentName, String sessionId, RequestOptions requestOptions)
List session files Returns files and directories at the specified path in the session sandbox. |
|
Paged |
listSessionFiles(String agentName, String sessionId, String path, Integer limit, PageOrder order, String after, String before)
List session files Returns files and directories at the specified path in the session sandbox. |
|
Paged |
listSessions(String agentName)
List sessions for an agent Returns a paged collection of sessions associated with the specified agent endpoint. |
|
Paged |
listSessions(String agentName, Integer limit, PageOrder order, String after, String before)
List sessions for an agent Returns a paged collection of sessions associated with the specified agent endpoint. |
|
Paged |
listSessions(String agentName, RequestOptions requestOptions)
List sessions for an agent Returns a paged collection of sessions associated with the specified agent endpoint. |
|
Agent |
promoteOptimizationCandidate(String jobId, String candidateId)
Promote a candidate for an agent optimization job Promotes a candidate to the Foundry agent stored in the parent job's target configuration. |
|
Response<Binary |
promoteOptimizationCandidateWithResponse(String jobId, String candidateId, RequestOptions requestOptions)
Promote a candidate for an agent optimization job Promotes a candidate to the Foundry agent stored in the parent job's target configuration. |
|
Microsoft365Publish |
publishAgentToMicrosoft365(PublishAgentToMicrosoft365Options options)
Publish an agent to Microsoft 365 Publishes a Foundry agent to Microsoft 365 / Microsoft Teams and returns the published title and Teams app ids. |
|
Response<Binary |
publishAgentToMicrosoft365WithResponse(String agentName, BinaryData publishAgentToMicrosoft365Request, RequestOptions requestOptions)
Publish an agent to Microsoft 365 Publishes a Foundry agent to Microsoft 365 / Microsoft Teams and returns the published title and Teams app ids. |
| void |
stopSession(String agentName, String sessionId)
Stop a session Terminates the specified hosted agent session and returns 204 No Content when the request succeeds. |
| Response<Void> |
stopSessionWithResponse(String agentName, String sessionId, RequestOptions requestOptions)
Stop a session Terminates the specified hosted agent session and returns 204 No Content when the request succeeds. |
|
Agent |
updateAgentDetails(String agentName, UpdateAgentDetailsOptions patchAgentObjectRequest)
Update an agent endpoint Applies a merge-patch update to the specified agent endpoint configuration. |
|
Response<Binary |
updateAgentDetailsWithResponse(String agentName, BinaryData patchAgentObjectRequest, RequestOptions requestOptions)
Update an agent endpoint Applies a merge-patch update to the specified agent endpoint configuration. |
|
Agent |
updateAgentFromCode(String agentName, String codeZipSha256, CreateAgentVersionFromCodeContent content)
Update a code-based agent Updates a code-based agent by uploading new code and creating a new version. |
|
Session |
uploadSessionFile(String agentName, String sessionId, String path, BinaryData content)
Upload a session file Uploads binary file content to the specified path in the session sandbox. |
|
Response<Binary |
uploadSessionFileWithResponse(String agentName, String agentSessionId, String path, String filePath, RequestOptions requestOptions)
Upload a session file Uploads binary file content to the specified path in the session sandbox. |
|
Response<Binary |
uploadSessionFileWithResponse(String agentName, String sessionId, String path, BinaryData content, RequestOptions requestOptions)
Upload a session file Uploads binary file content to the specified path in the session sandbox. |
Methods inherited from java.lang.Object
Method Details
beginCreateOptimizationJob
public SyncPoller<AgentOptimizationJob,AgentOptimizationJobResult> beginCreateOptimizationJob(AgentOptimizationJob job)
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.
Parameters:
Returns:
beginCreateOptimizationJob
public SyncPoller<AgentOptimizationJob,AgentOptimizationJobResult> beginCreateOptimizationJob(AgentOptimizationJob job, String operationId)
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.
Parameters:
Returns:
beginCreateOptimizationJob
public SyncPoller<BinaryData,BinaryData> beginCreateOptimizationJob(BinaryData job, RequestOptions requestOptions)
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
| ------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| Name | Type | Required | Description |
| Operation-Id | String | No | Client-generated unique ID for idempotent retries. When absent, the server creates the job unconditionally. |
You can add these to a request with RequestOptions#addHeader
Request Body Schema
{
id: String (Required)
result (Optional): {
candidate_summary (Optional): {
completed_candidate_count: int (Required)
baseline_id: String (Optional)
best_id: String (Optional)
baseline_score: Double (Optional)
best_score: Double (Optional)
latest_promoted_candidate (Optional): {
promoted_at: long (Required)
promoted_agent (Required): {
type: String (Required)
name: String (Required)
version: String (Optional)
}
}
}
token_usage (Required): [
(Required){
stage: String(agent/evaluation/optimization) (Required)
model: String (Optional)
input_tokens: Long (Optional)
output_tokens: Long (Optional)
total_tokens: Long (Optional)
cached_tokens: Long (Optional)
reasoning_tokens: Long (Optional)
}
]
latency_metrics (Required): [
(Required){
stage: String(agent/evaluation/optimization) (Required)
model: String (Optional)
avg_latency_ms: long (Required)
call_count: long (Required)
}
]
termination_reason: String(completed/budget_exhausted/candidate_screening_stalled) (Optional)
}
status: String(queued/in_progress/succeeded/failed/cancelled) (Required)
error (Optional): {
code: String (Required)
message: String (Required)
param: String (Optional)
type: String (Optional)
misalignment (Optional): {
error_type: String(potentially_unintended_data_transfer/potentially_unintended_data_access/potentially_unintended_destructive_activity/other) (Optional)
detailed_explanation: String (Optional)
steer (Optional): {
message: String (Required)
}
}
details (Optional): [
(recursive schema, see above)
]
additionalInfo (Optional): {
String: BinaryData (Required)
}
debugInfo (Optional): {
String: BinaryData (Required)
}
}
display_name: String (Optional)
target_configuration (Optional): {
type: String(foundry_agent) (Required)
}
optimization_model_configuration (Required): {
model: String (Required)
}
optimization_configuration (Required): {
type: String(agent_optimization/prompt_optimization) (Required)
}
run_duration_ms: long (Required)
created_at: long (Required)
updated_at: long (Required)
warnings (Optional): [
String (Optional)
]
}
Response Body Schema
{
id: String (Required)
result (Optional): {
candidate_summary (Optional): {
completed_candidate_count: int (Required)
baseline_id: String (Optional)
best_id: String (Optional)
baseline_score: Double (Optional)
best_score: Double (Optional)
latest_promoted_candidate (Optional): {
promoted_at: long (Required)
promoted_agent (Required): {
type: String (Required)
name: String (Required)
version: String (Optional)
}
}
}
token_usage (Required): [
(Required){
stage: String(agent/evaluation/optimization) (Required)
model: String (Optional)
input_tokens: Long (Optional)
output_tokens: Long (Optional)
total_tokens: Long (Optional)
cached_tokens: Long (Optional)
reasoning_tokens: Long (Optional)
}
]
latency_metrics (Required): [
(Required){
stage: String(agent/evaluation/optimization) (Required)
model: String (Optional)
avg_latency_ms: long (Required)
call_count: long (Required)
}
]
termination_reason: String(completed/budget_exhausted/candidate_screening_stalled) (Optional)
}
status: String(queued/in_progress/succeeded/failed/cancelled) (Required)
error (Optional): {
code: String (Required)
message: String (Required)
param: String (Optional)
type: String (Optional)
misalignment (Optional): {
error_type: String(potentially_unintended_data_transfer/potentially_unintended_data_access/potentially_unintended_destructive_activity/other) (Optional)
detailed_explanation: String (Optional)
steer (Optional): {
message: String (Required)
}
}
details (Optional): [
(recursive schema, see above)
]
additionalInfo (Optional): {
String: BinaryData (Required)
}
debugInfo (Optional): {
String: BinaryData (Required)
}
}
display_name: String (Optional)
target_configuration (Optional): {
type: String(foundry_agent) (Required)
}
optimization_model_configuration (Required): {
model: String (Required)
}
optimization_configuration (Required): {
type: String(agent_optimization/prompt_optimization) (Required)
}
run_duration_ms: long (Required)
created_at: long (Required)
updated_at: long (Required)
warnings (Optional): [
String (Optional)
]
}
Parameters:
Returns:
cancelOptimizationJob
public AgentOptimizationJob cancelOptimizationJob(String jobId)
Cancel an agent optimization job Requests cancellation of a running or queued job. Returns 409 Conflict if the job is already in a terminal state.
Parameters:
Returns:
cancelOptimizationJobWithResponse
public Response<BinaryData> cancelOptimizationJobWithResponse(String jobId, RequestOptions requestOptions)
Cancel an agent optimization job Requests cancellation of a running or queued job. Returns 409 Conflict if the job is already in a terminal state.
Response Body Schema
{
id: String (Required)
result (Optional): {
candidate_summary (Optional): {
completed_candidate_count: int (Required)
baseline_id: String (Optional)
best_id: String (Optional)
baseline_score: Double (Optional)
best_score: Double (Optional)
latest_promoted_candidate (Optional): {
promoted_at: long (Required)
promoted_agent (Required): {
type: String (Required)
name: String (Required)
version: String (Optional)
}
}
}
token_usage (Required): [
(Required){
stage: String(agent/evaluation/optimization) (Required)
model: String (Optional)
input_tokens: Long (Optional)
output_tokens: Long (Optional)
total_tokens: Long (Optional)
cached_tokens: Long (Optional)
reasoning_tokens: Long (Optional)
}
]
latency_metrics (Required): [
(Required){
stage: String(agent/evaluation/optimization) (Required)
model: String (Optional)
avg_latency_ms: long (Required)
call_count: long (Required)
}
]
termination_reason: String(completed/budget_exhausted/candidate_screening_stalled) (Optional)
}
status: String(queued/in_progress/succeeded/failed/cancelled) (Required)
error (Optional): {
code: String (Required)
message: String (Required)
param: String (Optional)
type: String (Optional)
misalignment (Optional): {
error_type: String(potentially_unintended_data_transfer/potentially_unintended_data_access/potentially_unintended_destructive_activity/other) (Optional)
detailed_explanation: String (Optional)
steer (Optional): {
message: String (Required)
}
}
details (Optional): [
(recursive schema, see above)
]
additionalInfo (Optional): {
String: BinaryData (Required)
}
debugInfo (Optional): {
String: BinaryData (Required)
}
}
display_name: String (Optional)
target_configuration (Optional): {
type: String(foundry_agent) (Required)
}
optimization_model_configuration (Required): {
model: String (Required)
}
optimization_configuration (Required): {
type: String(agent_optimization/prompt_optimization) (Required)
}
run_duration_ms: long (Required)
created_at: long (Required)
updated_at: long (Required)
warnings (Optional): [
String (Optional)
]
}
Parameters:
Returns:
createAgentVersion
public AgentVersionDetails createAgentVersion(String agentName, AgentDefinition definition)
Create an agent version Creates a new version for the specified agent and returns the created version resource.
Parameters:
- Must start and end with alphanumeric characters,
- Can contain hyphens in the middle
- Must not exceed 63 characters.
Returns:
createAgentVersion
public AgentVersionDetails createAgentVersion(String agentName, AgentDefinition definition, Map<String,String> metadata, String description)
Create a new agent version.
Parameters:
- Must start and end with alphanumeric characters,
- Can contain hyphens in the middle
- Must not exceed 63 characters.
Returns:
createAgentVersion
public AgentVersionDetails createAgentVersion(String agentName, CreateAgentVersionInput createAgentVersionInput)
Create a new agent version.
Parameters:
- Must start and end with alphanumeric characters,
- Can contain hyphens in the middle
- Must not exceed 63 characters.
Returns:
createAgentVersionFromCode
public AgentVersionDetails createAgentVersionFromCode(String agentName, HostedAgentDefinition definition, CodeFileDetails code, String description, Map<String,String> metadata)
Create a new code-based hosted agent version.
This convenience overload flattens the request: instead of assembling a CreateAgentVersionFromCodeContent that wraps a CreateAgentVersionFromCodeMetadata, the caller passes the HostedAgentDefinition and code zip directly. The required x-ms-code-zip-sha256 value is computed from code automatically.
Parameters:
- Must start and end with alphanumeric characters,
- Can contain hyphens in the middle
- Must not exceed 63 characters.
code_configuration, cpu,
memory, and protocol_versions.
null.
null. Keys
are strings with a maximum length of 64 characters and values are strings with a maximum length of 512
characters.
Returns:
createAgentVersionFromCode
public AgentVersionDetails createAgentVersionFromCode(String agentName, String codeZipSha256, CreateAgentVersionFromCodeContent content)
Create an agent version from code Creates a new agent version from code. Uploads the code zip and creates a new version for an existing agent. The SHA-256 hex digest of the zip is provided in the `x-ms-code-zip-sha256` header for integrity and dedup. The request body is multipart/form-data with a JSON metadata part and a binary code part (part order is irrelevant). Maximum upload size is 250 MB.
Parameters:
- Must start and end with alphanumeric characters,
- Can contain hyphens in the middle
- Must not exceed 63 characters.
Returns:
createAgentVersionFromManifest
public AgentVersionDetails createAgentVersionFromManifest(String agentName, String manifestId, Map<String,BinaryData> parameterValues)
Create an agent version from manifest Imports the provided manifest to create a new version for the specified agent.
Parameters:
- Must start and end with alphanumeric characters,
- Can contain hyphens in the middle
- Must not exceed 63 characters.
Returns:
createAgentVersionFromManifest
public AgentVersionDetails createAgentVersionFromManifest(String agentName, String manifestId, Map<String,BinaryData> parameterValues, Map<String,String> metadata, String description)
Create an agent version from manifest Imports the provided manifest to create a new version for the specified agent.
Parameters:
- Must start and end with alphanumeric characters,
- Can contain hyphens in the middle
- Must not exceed 63 characters.
Returns:
createAgentVersionFromManifestWithResponse
public Response<BinaryData> createAgentVersionFromManifestWithResponse(String agentName, BinaryData createAgentVersionFromManifestRequest, RequestOptions requestOptions)
Create an agent version from manifest Imports the provided manifest to create a new version for the specified agent.
Request Body Schema
{
metadata (Optional): {
String: String (Required)
}
description: String (Optional)
manifest_id: String (Required)
parameter_values (Required): {
String: BinaryData (Required)
}
}
Response Body Schema
{
metadata (Required): {
String: String (Required)
}
object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
id: String (Required)
name: String (Required)
version: String (Required)
description: String (Optional)
created_at: long (Required)
definition (Required): {
kind: String(prompt/hosted/workflow/external/voice) (Required)
rai_config (Optional): {
rai_policy_name: String (Required)
invocations_moderation (Optional): {
input_content_type: String(json/text) (Optional)
output_content_type: String(json/text) (Optional)
response_mode: String(non_streaming/streaming/both) (Required)
input_paths (Optional): [
String (Optional)
]
output_paths (Optional): [
String (Optional)
]
stream_selectors (Optional): [
(Optional){
event_type: String (Required)
text_field: String (Optional)
}
]
}
}
}
draft: Boolean (Optional)
status: String(creating/active/failed/deleting/deleted) (Optional)
instance_identity (Optional): {
principal_id: String (Required)
client_id: String (Required)
status: String(active/disabled) (Optional)
}
blueprint (Optional): (recursive schema, see blueprint above)
blueprint_reference (Optional): {
type: String(ManagedAgentIdentityBlueprint) (Required)
}
agent_guid: String (Optional)
}
Parameters:
- Must start and end with alphanumeric characters,
- Can contain hyphens in the middle
- Must not exceed 63 characters.
Returns:
createAgentVersionWithResponse
public Response<BinaryData> createAgentVersionWithResponse(String agentName, BinaryData createAgentVersionRequest, RequestOptions requestOptions)
Create an agent version Creates a new version for the specified agent and returns the created version resource.
Request Body Schema
{
metadata (Optional): {
String: String (Required)
}
description: String (Optional)
definition (Required): {
kind: String(prompt/hosted/workflow/external/voice) (Required)
rai_config (Optional): {
rai_policy_name: String (Required)
invocations_moderation (Optional): {
input_content_type: String(json/text) (Optional)
output_content_type: String(json/text) (Optional)
response_mode: String(non_streaming/streaming/both) (Required)
input_paths (Optional): [
String (Optional)
]
output_paths (Optional): [
String (Optional)
]
stream_selectors (Optional): [
(Optional){
event_type: String (Required)
text_field: String (Optional)
}
]
}
}
}
blueprint_reference (Optional): {
type: String(ManagedAgentIdentityBlueprint) (Required)
}
digital_worker_type: String(m365) (Optional)
draft: Boolean (Optional)
}
Response Body Schema
{
metadata (Required): {
String: String (Required)
}
object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
id: String (Required)
name: String (Required)
version: String (Required)
description: String (Optional)
created_at: long (Required)
definition (Required): {
kind: String(prompt/hosted/workflow/external/voice) (Required)
rai_config (Optional): {
rai_policy_name: String (Required)
invocations_moderation (Optional): {
input_content_type: String(json/text) (Optional)
output_content_type: String(json/text) (Optional)
response_mode: String(non_streaming/streaming/both) (Required)
input_paths (Optional): [
String (Optional)
]
output_paths (Optional): [
String (Optional)
]
stream_selectors (Optional): [
(Optional){
event_type: String (Required)
text_field: String (Optional)
}
]
}
}
}
draft: Boolean (Optional)
status: String(creating/active/failed/deleting/deleted) (Optional)
instance_identity (Optional): {
principal_id: String (Required)
client_id: String (Required)
status: String(active/disabled) (Optional)
}
blueprint (Optional): (recursive schema, see blueprint above)
blueprint_reference (Optional): {
type: String(ManagedAgentIdentityBlueprint) (Required)
}
agent_guid: String (Optional)
}
Parameters:
- Must start and end with alphanumeric characters,
- Can contain hyphens in the middle
- Must not exceed 63 characters.
Returns:
createSession
public AgentSessionResource createSession(String agentName, VersionIndicator versionIndicator)
Create a session Creates a new session for an agent endpoint. The endpoint resolves the backing agent version from `version_indicator` and enforces session ownership using the provided user identity for session-mutating operations.
Parameters:
Returns:
createSession
public AgentSessionResource createSession(String agentName, VersionIndicator versionIndicator, String agentSessionId)
Create a session Creates a new session for an agent endpoint. The endpoint resolves the backing agent version from `version_indicator` and enforces session ownership using the provided user identity for session-mutating operations.
Parameters:
Returns:
createSessionWithResponse
public Response<BinaryData> createSessionWithResponse(String agentName, BinaryData createSessionRequest, RequestOptions requestOptions)
Create a session Creates a new session for an agent endpoint. The endpoint resolves the backing agent version from `version_indicator` and enforces session ownership using the provided user identity for session-mutating operations.
Request Body Schema
{
agent_session_id: String (Optional)
version_indicator (Required): {
type: String(version_ref) (Required)
}
}
Response Body Schema
{
agent_session_id: String (Required)
version_indicator (Required): {
type: String(version_ref) (Required)
}
status: String(creating/active/idle/updating/failed/deleting/deleted/expired) (Required)
created_at: long (Required)
last_accessed_at: long (Required)
expires_at: long (Required)
stopped_at: Long (Optional)
}
Parameters:
Returns:
deleteAgent
public void deleteAgent(String agentName)
Deletes an agent.
Parameters:
deleteAgentVersion
public void deleteAgentVersion(String agentName, String agentVersion)
Deletes a specific version of an agent.
Parameters:
deleteAgentVersionWithResponse
public Response<Void> deleteAgentVersionWithResponse(String agentName, String agentVersion, RequestOptions requestOptions)
Deletes a specific version of an agent.
Response Body Schema
{
object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
name: String (Required)
version: String (Required)
deleted: boolean (Required)
}
Parameters:
Returns:
deleteAgentWithResponse
public Response<Void> deleteAgentWithResponse(String agentName, RequestOptions requestOptions)
Deletes an agent.
Response Body Schema
{
object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
name: String (Required)
deleted: boolean (Required)
}
Parameters:
Returns:
deleteOptimizationJob
public void deleteOptimizationJob(String jobId)
Delete an agent optimization job Cancels active work, then deletes the job and its candidate artifacts.
Parameters:
deleteOptimizationJobWithResponse
public Response<Void> deleteOptimizationJobWithResponse(String jobId, RequestOptions requestOptions)
Delete an agent optimization job Cancels active work, then deletes the job and its candidate artifacts.
Parameters:
Returns:
deleteSession
public void deleteSession(String agentName, String sessionId)
Delete a session Deletes a session synchronously. Returns 204 No Content when the session is deleted or does not exist.
Parameters:
deleteSessionFile
public void deleteSessionFile(String agentName, String sessionId, String path)
Delete a session file Deletes the specified file or directory from the session sandbox. When `recursive` is false, deleting a non-empty directory returns 409 Conflict.
Parameters:
deleteSessionFile
public void deleteSessionFile(String agentName, String sessionId, String path, Boolean recursive)
Delete a session file Deletes the specified file or directory from the session sandbox. When `recursive` is false, deleting a non-empty directory returns 409 Conflict.
Parameters:
false if a value is
not specified by the caller.
deleteSessionFileWithResponse
public Response<Void> deleteSessionFileWithResponse(String agentName, String sessionId, String path, RequestOptions requestOptions)
Delete a session file Deletes the specified file or directory from the session sandbox. When `recursive` is false, deleting a non-empty directory returns 409 Conflict.
Query Parameters
| --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Name | Type | Required | Description |
| recursive | Boolean | No | Whether to recursively delete directory contents. The service defaults to \`false\` if a value is not specified by the caller. |
You can add these to a request with RequestOptions#addQueryParam
Parameters:
Returns:
deleteSessionWithResponse
public Response<Void> deleteSessionWithResponse(String agentName, String sessionId, RequestOptions requestOptions)
Delete a session Deletes a session synchronously. Returns 204 No Content when the session is deleted or does not exist.
Parameters:
Returns:
disableAgent
public void disableAgent(String agentName)
Disable an agent Disables the specified agent, preventing it from accepting new sessions or processing requests. Existing active sessions are allowed to drain gracefully but no new sessions can be created. This operation is idempotent — disabling an already-disabled agent returns success with no side effects.
Parameters:
disableAgentWithResponse
public Response<Void> disableAgentWithResponse(String agentName, RequestOptions requestOptions)
Disable an agent Disables the specified agent, preventing it from accepting new sessions or processing requests. Existing active sessions are allowed to drain gracefully but no new sessions can be created. This operation is idempotent — disabling an already-disabled agent returns success with no side effects.
Parameters:
Returns:
downloadAgentCode
public BinaryData downloadAgentCode(String agentName)
Download agent code Downloads the code zip for a code-based hosted agent. Returns the previously-uploaded zip (`application/zip`). If `agent_version` is supplied, returns that version's code zip; otherwise returns the latest version's code zip. The SHA-256 digest of the returned bytes matches the `content_hash` on the resolved version's `code_configuration`.
Parameters:
Returns:
downloadAgentCode
public BinaryData downloadAgentCode(String agentName, String agentVersion)
Download agent code Downloads the code zip for a code-based hosted agent. Returns the previously-uploaded zip (`application/zip`). If `agent_version` is supplied, returns that version's code zip; otherwise returns the latest version's code zip. The SHA-256 digest of the returned bytes matches the `content_hash` on the resolved version's `code_configuration`.
Parameters:
Returns:
downloadAgentCode
public void downloadAgentCode(String agentName, String agentVersion, String filePath)
Download agent code Downloads the code zip for a code-based hosted agent. Returns the previously-uploaded zip (`application/zip`). If `agent_version` is supplied, returns that version's code zip; otherwise returns the latest version's code zip. The SHA-256 digest of the returned bytes matches the `content_hash` on the resolved version's `code_configuration`.
Parameters:
Throws:
downloadAgentCode
public void downloadAgentCode(String agentName, String agentVersion, String filePath, boolean overwrite)
Download agent code Downloads the code zip for a code-based hosted agent and writes it to filePath.
Parameters:
filePath. When false, the operation
fails if a file already exists at the destination.
Throws:
downloadAgentCodeWithResponse
public Response<BinaryData> downloadAgentCodeWithResponse(String agentName, RequestOptions requestOptions)
Download agent code Downloads the code zip for a code-based hosted agent. Returns the previously-uploaded zip (`application/zip`). If `agent_version` is supplied, returns that version's code zip; otherwise returns the latest version's code zip. The SHA-256 digest of the returned bytes matches the `content_hash` on the resolved version's `code_configuration`.
Query Parameters
| -------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| Name | Type | Required | Description |
| agent\_version | String | No | The version of the agent whose code zip should be downloaded. If omitted, the latest version's code zip is returned. |
You can add these to a request with RequestOptions#addQueryParam
Response Body Schema
BinaryData
Response Headers
| ------------------ | ------ | ------------------------------------------------------------------------- |
| Name | Type | Description |
| x-ms-agent-version | String | The version of the agent whose code zip is returned in the response body. |
Parameters:
Returns:
downloadAgentCodeWithResponse
public Response<Void> downloadAgentCodeWithResponse(String agentName, String filePath, boolean overwrite, RequestOptions requestOptions)
Download agent code Downloads the code zip for a code-based hosted agent and writes it to filePath.
Parameters:
filePath. When false, the operation
fails if a file already exists at the destination.
Returns:
Throws:
downloadAgentCodeWithResponse
public Response<Void> downloadAgentCodeWithResponse(String agentName, String filePath, RequestOptions requestOptions)
Download agent code Downloads the code zip for a code-based hosted agent. Returns the previously-uploaded zip (`application/zip`). If `agent_version` is supplied, returns that version's code zip; otherwise returns the latest version's code zip. The SHA-256 digest of the returned bytes matches the `content_hash` on the resolved version's `code_configuration`.
Query Parameters
| -------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| Name | Type | Required | Description |
| agent\_version | String | No | The version of the agent whose code zip should be downloaded. If omitted, the latest version's code zip is returned. |
You can add these to a request with RequestOptions#addQueryParam
Response Body Schema
BinaryData
Parameters:
Returns:
Throws:
downloadSessionFile
public BinaryData downloadSessionFile(String agentName, String sessionId, String path)
Download a session file Downloads the file at the specified sandbox path as a binary stream. The path is resolved relative to the session home directory.
Parameters:
Returns:
downloadSessionFileWithResponse
public Response<Void> downloadSessionFileWithResponse(String agentName, String agentSessionId, String path, String filePath, boolean overwrite, RequestOptions requestOptions)
Download a session file Downloads the file at the specified sandbox path and writes it to filePath. The path is resolved relative to the session home directory.
Parameters:
filePath. When false, the operation
fails if a file already exists at the destination.
Returns:
Throws:
downloadSessionFileWithResponse
public Response<Void> downloadSessionFileWithResponse(String agentName, String agentSessionId, String path, String filePath, RequestOptions requestOptions)
Download a session file Downloads the file at the specified sandbox path as a binary stream. The path is resolved relative to the session home directory.
Header Parameters
| ----------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Name | Type | Required | Description |
| x-ms-user-isolation-key | String | No | Opaque per-user isolation key used to scope endpoint-scoped data (responses, conversations, sessions) to a specific end user. |
You can add these to a request with RequestOptions#addHeader
Response Body Schema
BinaryData
Parameters:
Returns:
Throws:
downloadSessionFileWithResponse
public Response<BinaryData> downloadSessionFileWithResponse(String agentName, String sessionId, String path, RequestOptions requestOptions)
Download a session file Downloads the file at the specified sandbox path as a binary stream. The path is resolved relative to the session home directory.
Response Body Schema
BinaryData
Parameters:
Returns:
enableAgent
public void enableAgent(String agentName)
Enable an agent Enables the specified agent, allowing it to accept new sessions and process requests. This operation is idempotent — enabling an already-enabled agent returns success with no side effects.
Parameters:
enableAgentWithResponse
public Response<Void> enableAgentWithResponse(String agentName, RequestOptions requestOptions)
Enable an agent Enables the specified agent, allowing it to accept new sessions and process requests. This operation is idempotent — enabling an already-enabled agent returns success with no side effects.
Parameters:
Returns:
estimateOptimizationJob
public AgentOptimizationEstimateResult estimateOptimizationJob(AgentOptimizationEstimateInputs inputs)
Estimate an agent optimization job Estimates validation-set rows, per-stage model call volumes, and cost bands without submitting the job.
Parameters:
Returns:
estimateOptimizationJobWithResponse
public Response<BinaryData> estimateOptimizationJobWithResponse(BinaryData inputs, RequestOptions requestOptions)
Estimate an agent optimization job Estimates validation-set rows, per-stage model call volumes, and cost bands without submitting the job.
Request Body Schema
{
target_configuration (Optional): {
type: String(foundry_agent) (Required)
}
optimization_model_configuration (Required): {
model: String (Required)
}
optimization_configuration (Required): {
type: String(agent_optimization/prompt_optimization) (Required)
goal: String(improve_quality) (Optional)
evaluation_configuration (Required): {
training_set (Required): {
type: String(target_completion/user_conversation_simulation) (Required)
}
validation_set (Optional): (recursive schema, see validation_set above)
evaluators (Required): [
(Required){
name: String (Required)
version: String (Optional)
initialization_parameters (Optional): {
String: BinaryData (Required)
}
}
]
evaluation_model (Required): {
model: String (Required)
sampling_params (Optional): {
temperature: Double (Optional)
top_p: Double (Optional)
seed: Integer (Optional)
max_completion_tokens: Long (Optional)
}
voice_model (Optional): {
type: String (Required)
}
}
max_concurrent_agent_runs: Integer (Optional)
}
candidate_search_configuration (Required): {
max_candidates: Integer (Optional)
}
baseline_agent_configuration (Optional): {
system_prompt: String (Optional)
current_model: String (Optional)
skills (Optional): [
(Optional){
name: String (Required)
description: String (Required)
body: String (Optional)
}
]
tools (Optional): [
(Optional){
type: String (Required)
function (Required): {
description: String (Optional)
name: String (Required)
parameters (Optional): {
(Optional): {
String: BinaryData (Required)
}
}
strict: Boolean (Optional)
}
}
]
}
agent_optimization_space (Required): {
target_attributes (Optional): [
String(instructions/model/skills/tools) (Optional)
]
model_search_space (Optional): [
String (Optional)
]
}
}
}
Response Body Schema
{
call_counts (Optional): {
agent (Optional): {
low: double (Required)
typical: double (Required)
ceiling: double (Required)
}
evaluation (Optional): (recursive schema, see evaluation above)
optimization (Optional): (recursive schema, see optimization above)
}
cost (Optional): {
currency: String (Required)
total (Optional): (recursive schema, see total above)
by_stage (Optional): (recursive schema, see by_stage above)
unpriced_stages (Optional): [
String(agent/evaluation/optimization) (Optional)
]
}
prices_as_of: Long (Optional)
}
Parameters:
Returns:
getAgent
public AgentDetails getAgent(String agentName)
Get an agent Retrieves an agent definition by its unique name.
Parameters:
Returns:
getAgentVersionDetails
public AgentVersionDetails getAgentVersionDetails(String agentName, String agentVersion)
Get an agent version Retrieves the specified version of an agent by its agent name and version identifier.
Parameters:
Returns:
getAgentVersionDetailsWithResponse
public Response<BinaryData> getAgentVersionDetailsWithResponse(String agentName, String agentVersion, RequestOptions requestOptions)
Get an agent version Retrieves the specified version of an agent by its agent name and version identifier.
Response Body Schema
{
metadata (Required): {
String: String (Required)
}
object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
id: String (Required)
name: String (Required)
version: String (Required)
description: String (Optional)
created_at: long (Required)
definition (Required): {
kind: String(prompt/hosted/workflow/external/voice) (Required)
rai_config (Optional): {
rai_policy_name: String (Required)
invocations_moderation (Optional): {
input_content_type: String(json/text) (Optional)
output_content_type: String(json/text) (Optional)
response_mode: String(non_streaming/streaming/both) (Required)
input_paths (Optional): [
String (Optional)
]
output_paths (Optional): [
String (Optional)
]
stream_selectors (Optional): [
(Optional){
event_type: String (Required)
text_field: String (Optional)
}
]
}
}
}
draft: Boolean (Optional)
status: String(creating/active/failed/deleting/deleted) (Optional)
instance_identity (Optional): {
principal_id: String (Required)
client_id: String (Required)
status: String(active/disabled) (Optional)
}
blueprint (Optional): (recursive schema, see blueprint above)
blueprint_reference (Optional): {
type: String(ManagedAgentIdentityBlueprint) (Required)
}
agent_guid: String (Optional)
}
Parameters:
Returns:
getAgentWithResponse
public Response<BinaryData> getAgentWithResponse(String agentName, RequestOptions requestOptions)
Get an agent Retrieves an agent definition by its unique name.
Response Body Schema
{
object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
id: String (Required)
name: String (Required)
state: String(enabled/disabled) (Required)
configuration_state: String(enabled/disabled) (Required)
state_source: String(agent_instance_identity/agent_blueprint) (Optional)
versions (Required): {
latest (Required): {
metadata (Required): {
String: String (Required)
}
object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
id: String (Required)
name: String (Required)
version: String (Required)
description: String (Optional)
created_at: long (Required)
definition (Required): {
kind: String(prompt/hosted/workflow/external/voice) (Required)
rai_config (Optional): {
rai_policy_name: String (Required)
invocations_moderation (Optional): {
input_content_type: String(json/text) (Optional)
output_content_type: String(json/text) (Optional)
response_mode: String(non_streaming/streaming/both) (Required)
input_paths (Optional): [
String (Optional)
]
output_paths (Optional): [
String (Optional)
]
stream_selectors (Optional): [
(Optional){
event_type: String (Required)
text_field: String (Optional)
}
]
}
}
}
draft: Boolean (Optional)
status: String(creating/active/failed/deleting/deleted) (Optional)
instance_identity (Optional): {
principal_id: String (Required)
client_id: String (Required)
status: String(active/disabled) (Optional)
}
blueprint (Optional): (recursive schema, see blueprint above)
blueprint_reference (Optional): {
type: String(ManagedAgentIdentityBlueprint) (Required)
}
agent_guid: String (Optional)
}
}
agent_endpoint (Optional): {
version_selector (Optional): {
version_selection_rules (Optional, Required on create): [
(Optional, Required on create){
type: String(FixedRatio) (Required)
agent_version: String (Optional, Required on create)
}
]
}
protocol_configuration (Optional): {
activity (Optional): {
enable_m365_public_endpoint: Boolean (Optional)
access_boundaries (Optional): [
String(read.1on1.developers/read.1on1.manager/read.1on1.allowlisted/read.1on1.tenant/write.1on1.developers/write.1on1.manager/write.1on1.allowlisted/write.1on1.tenant/read.group.developers/read.group.allowlisted/read.group.manager-invited/read.group.manager-present/read.group.tenant/write.group.developers/write.group.allowlisted/write.group.manager-invited/write.group.manager-present/write.group.tenant) (Optional)
]
}
responses (Optional): {
}
a2a (Optional): {
}
mcp (Optional): {
}
invocations (Optional): {
}
invocations_ws (Optional): {
}
}
authorization_schemes (Optional): [
(Optional){
type: String(Entra/BotService/BotServiceRbac/BotServiceTenant) (Required)
}
]
publish_approval_status: String(not_published/pending/approved/rejected/no_approval_needed) (Optional)
}
digital_worker_type: String(m365) (Optional)
instance_identity (Optional): (recursive schema, see instance_identity above)
blueprint (Optional): (recursive schema, see blueprint above)
blueprint_reference (Optional): (recursive schema, see blueprint_reference above)
agent_card (Optional): {
version: String (Optional, Required on create)
description: String (Optional)
skills (Optional, Required on create): [
(Optional, Required on create){
id: String (Optional, Required on create)
name: String (Optional, Required on create)
description: String (Optional)
tags (Optional): [
String (Optional)
]
examples (Optional): [
String (Optional)
]
}
]
}
}
Parameters:
Returns:
getMicrosoft365AppPackage
public BinaryData getMicrosoft365AppPackage(GetMicrosoft365AppPackageOptions options)
Generate a Microsoft 365 app package Generates the Microsoft Teams app package (zip) for a Foundry agent from the supplied publish request, without publishing it. Returns the app package as `application/zip`.
Parameters:
Returns:
getMicrosoft365AppPackageWithResponse
public Response<BinaryData> getMicrosoft365AppPackageWithResponse(String agentName, BinaryData getMicrosoft365AppPackageRequest, RequestOptions requestOptions)
Generate a Microsoft 365 app package Generates the Microsoft Teams app package (zip) for a Foundry agent from the supplied publish request, without publishing it. Returns the app package as `application/zip`.
Request Body Schema
{
agentDisplayName: String (Optional)
botServiceArmId: String (Optional)
publishAsAutopilot: Boolean (Optional)
accessBoundaries (Optional): [
String(read.1on1.developers/read.1on1.manager/read.1on1.allowlisted/read.1on1.tenant/write.1on1.developers/write.1on1.manager/write.1on1.allowlisted/write.1on1.tenant/read.group.developers/read.group.allowlisted/read.group.manager-invited/read.group.manager-present/read.group.tenant/write.group.developers/write.group.allowlisted/write.group.manager-invited/write.group.manager-present/write.group.tenant) (Optional)
]
optionalPermissionScopes (Optional): [
(Optional){
resourceAppId: String (Required)
scopes (Required): [
String (Required)
]
}
]
publishScope: String(Personal/Shared/Tenant) (Required)
canRespondWithoutMention: Boolean (Optional)
appVersion: String (Optional)
shortDescription: String (Optional)
fullDescription: String (Optional)
developerName: String (Optional)
developerWebsiteUrl: String (Optional)
privacyUrl: String (Optional)
termsOfUseUrl: String (Optional)
colorIconBase64: String (Optional)
outlineIconBase64: String (Optional)
}
Response Body Schema
BinaryData
Parameters:
Returns:
getMicrosoft365PublishDefaults
public Microsoft365PublishDefaults getMicrosoft365PublishDefaults(String agentName)
Get Microsoft 365 publish defaults Returns default and previously-published values used to pre-populate a Microsoft 365 publish request for a Foundry agent.
Parameters:
Returns:
getMicrosoft365PublishDefaults
public Microsoft365PublishDefaults getMicrosoft365PublishDefaults(String agentName, Boolean publishAsDigitalWorker)
Get Microsoft 365 publish defaults Returns default and previously-published values used to pre-populate a Microsoft 365 publish request for a Foundry agent.
Parameters:
Returns:
getMicrosoft365PublishDefaultsWithResponse
public Response<BinaryData> getMicrosoft365PublishDefaultsWithResponse(String agentName, RequestOptions requestOptions)
Get Microsoft 365 publish defaults Returns default and previously-published values used to pre-populate a Microsoft 365 publish request for a Foundry agent.
Query Parameters
| ---------------------- | ------- | -------- | -------------------------------------------------------------------------------------------- |
| Name | Type | Required | Description |
| publishAsDigitalWorker | Boolean | No | When true, returns defaults for publishing the agent as an autopilot (digital worker) agent. |
You can add these to a request with RequestOptions#addQueryParam
Response Body Schema
{
appPublishScope: String(Personal/Shared/Tenant) (Optional)
agentName: String (Optional)
agentDisplayName: String (Optional)
appRegistrationClientId: String (Optional)
botServiceArmId: String (Optional)
appVersion: String (Optional)
recommendedNextAppVersion: String (Optional)
titleId: String (Optional)
teamsAppId: String (Optional)
shortDescription: String (Optional)
fullDescription: String (Optional)
developerName: String (Optional)
developerWebsiteUrl: String (Optional)
privacyUrl: String (Optional)
termsOfUseUrl: String (Optional)
}
Parameters:
Returns:
getOptimizationCandidate
public AgentOptimizationCandidate getOptimizationCandidate(String jobId, String candidateId)
Get a candidate for an agent optimization job Retrieves a single candidate. Mutation values are always included.
Parameters:
Returns:
getOptimizationCandidateWithResponse
public Response<BinaryData> getOptimizationCandidateWithResponse(String jobId, String candidateId, RequestOptions requestOptions)
Get a candidate for an agent optimization job Retrieves a single candidate. Mutation values are always included.
Response Body Schema
{
candidate_id: String (Required)
job_id: String (Required)
name: String (Required)
status: String(generating/evaluating/completed/failed) (Required)
started_at: long (Required)
output (Optional): {
type: String(agent_optimization/prompt_optimization) (Required)
}
rationale: String (Optional)
agent_version: String (Optional)
evaluation (Optional): {
score: Double (Optional)
avg_tokens: Double (Optional)
avg_latency_ms: Long (Optional)
eval_id: String (Optional)
eval_run_id: String (Optional)
completed_at: Long (Optional)
}
promotion (Optional): {
promoted_at: long (Required)
promoted_agent (Required): {
type: String (Required)
name: String (Required)
version: String (Optional)
}
}
}
Parameters:
Returns:
getOptimizationJob
public AgentOptimizationJob getOptimizationJob(String jobId)
Get an agent optimization job Retrieves an optimization job by its identifier.
Parameters:
Returns:
getOptimizationJobWithResponse
public Response<BinaryData> getOptimizationJobWithResponse(String jobId, RequestOptions requestOptions)
Get an agent optimization job Retrieves an optimization job by its identifier.
Response Body Schema
{
id: String (Required)
result (Optional): {
candidate_summary (Optional): {
completed_candidate_count: int (Required)
baseline_id: String (Optional)
best_id: String (Optional)
baseline_score: Double (Optional)
best_score: Double (Optional)
latest_promoted_candidate (Optional): {
promoted_at: long (Required)
promoted_agent (Required): {
type: String (Required)
name: String (Required)
version: String (Optional)
}
}
}
token_usage (Required): [
(Required){
stage: String(agent/evaluation/optimization) (Required)
model: String (Optional)
input_tokens: Long (Optional)
output_tokens: Long (Optional)
total_tokens: Long (Optional)
cached_tokens: Long (Optional)
reasoning_tokens: Long (Optional)
}
]
latency_metrics (Required): [
(Required){
stage: String(agent/evaluation/optimization) (Required)
model: String (Optional)
avg_latency_ms: long (Required)
call_count: long (Required)
}
]
termination_reason: String(completed/budget_exhausted/candidate_screening_stalled) (Optional)
}
status: String(queued/in_progress/succeeded/failed/cancelled) (Required)
error (Optional): {
code: String (Required)
message: String (Required)
param: String (Optional)
type: String (Optional)
misalignment (Optional): {
error_type: String(potentially_unintended_data_transfer/potentially_unintended_data_access/potentially_unintended_destructive_activity/other) (Optional)
detailed_explanation: String (Optional)
steer (Optional): {
message: String (Required)
}
}
details (Optional): [
(recursive schema, see above)
]
additionalInfo (Optional): {
String: BinaryData (Required)
}
debugInfo (Optional): {
String: BinaryData (Required)
}
}
display_name: String (Optional)
target_configuration (Optional): {
type: String(foundry_agent) (Required)
}
optimization_model_configuration (Required): {
model: String (Required)
}
optimization_configuration (Required): {
type: String(agent_optimization/prompt_optimization) (Required)
}
run_duration_ms: long (Required)
created_at: long (Required)
updated_at: long (Required)
warnings (Optional): [
String (Optional)
]
}
Response Headers
| ----------- | ---- | ----------------------------------------------------------- |
| Name | Type | Description |
| Retry-After | int | Recommended number of seconds to wait before polling again. |
Parameters:
Returns:
getSession
public AgentSessionResource getSession(String agentName, String sessionId)
Get a session Retrieves the details of a hosted agent session by agent name and session identifier.
Parameters:
Returns:
getSessionLogStream
public IterableStream<SessionLogEvent> getSessionLogStream(String agentName, String agentVersion, String sessionId)
Streams console logs (stdout / stderr) for a specific hosted agent session as typed SessionLogEvent values.
Parameters:
Returns:
getSessionLogStream
public IterableStream<SessionLogEvent> getSessionLogStream(String agentName, String agentVersion, String sessionId, RequestOptions requestOptions)
Streams console logs (stdout / stderr) for a specific hosted agent session as typed SessionLogEvent values.
Parameters:
Returns:
getSessionLogStreamWithResponse
public Response<BinaryData> getSessionLogStreamWithResponse(String agentName, String agentVersion, String sessionId, RequestOptions requestOptions)
Stream console logs for a hosted agent session Streams console logs (stdout / stderr) for a specific hosted agent session as a Server-Sent Events (SSE) stream. Each SSE frame contains: - `event`: always `"log"` - `data`: a plain-text log line (currently JSON-formatted, but the schema is not contractual and may include additional keys or change format over time — clients should treat it as an opaque string) Example SSE frames: ``` event: log data: {"timestamp":"2026-03-10T09:33:17.121Z","stream":"stdout","message":"Starting FoundryCBAgent server on port 8088"} event: log data: {"timestamp":"2026-03-10T09:33:17.130Z","stream":"stderr","message":"INFO: Application startup complete."} event: log data: {"timestamp":"2026-03-10T09:34:52.714Z","stream":"status","message":"Successfully connected to container"} event: log data: {"timestamp":"2026-03-10T09:35:52.714Z","stream":"status","message":"No logs since last 60 seconds"} ``` The stream remains open until the client disconnects or the server terminates the connection. Clients should handle reconnection as needed.
Response Body Schema
{
event: String(log) (Required)
data: String (Required)
}
Parameters:
Returns:
event field identifying the event type and a data
field carrying the payload as plain text along with Response<T>.getSessionWithResponse
public Response<BinaryData> getSessionWithResponse(String agentName, String sessionId, RequestOptions requestOptions)
Get a session Retrieves the details of a hosted agent session by agent name and session identifier.
Response Body Schema
{
agent_session_id: String (Required)
version_indicator (Required): {
type: String(version_ref) (Required)
}
status: String(creating/active/idle/updating/failed/deleting/deleted/expired) (Required)
created_at: long (Required)
last_accessed_at: long (Required)
expires_at: long (Required)
stopped_at: Long (Optional)
}
Parameters:
Returns:
listAgentConversations
public PagedIterable<Conversation> listAgentConversations()
List conversations Returns the conversations available in the current project.
Returns:
listAgentConversations
public PagedIterable<Conversation> listAgentConversations(Integer limit, PageOrder order, String after, String before, String agentName, String agentId)
Returns the list of all conversations.
Parameters:
created_at timestamp of the objects. asc for ascending order anddesc
for descending order.
after is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include after=obj_foo in order to fetch the next page of the list.
before is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include before=obj_foo in order to fetch the previous page of the list.
name:version. If provided, only items associated with the
specified agent ID will be returned.
Returns:
listAgentConversations
public PagedIterable<Conversation> listAgentConversations(Integer limit, PageOrder order, String after, String before, String agentName, String agentId, String userIdentity)
List conversations Returns the conversations available in the current project.
Parameters:
created_at timestamp of the objects. asc for ascending order anddesc
for descending order.
after is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include after=obj_foo in order to fetch the next page of the list.
before is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include before=obj_foo in order to fetch the previous page of the list.
name:version. If provided, only items associated with the
specified agent ID will be returned.
agents/endpoints/UserIdentityImpersonation/action RBAC permission.
Returns:
listAgentConversations
public PagedIterable<BinaryData> listAgentConversations(RequestOptions requestOptions)
List conversations Returns the conversations available in the current project.
Query Parameters
| ----------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | Type | Required | Description |
| limit | Integer | No | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. |
| order | String | No | Sort order by the \`created\_at\` timestamp of the objects. \`asc\` for ascending order and\`desc\` for descending order. Allowed values: "asc", "desc". |
| after | String | No | A cursor for use in pagination. \`after\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include after=obj\_foo in order to fetch the next page of the list. |
| before | String | No | A cursor for use in pagination. \`before\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include before=obj\_foo in order to fetch the previous page of the list. |
| agent\_name | String | No | Filter by agent name. If provided, only items associated with the specified agent will be returned. |
| agent\_id | String | No | Filter by agent ID in the format \`name:version\`. If provided, only items associated with the specified agent ID will be returned. |
You can add these to a request with RequestOptions#addQueryParam
Header Parameters
| ------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Name | Type | Required | Description |
| x-ms-user-identity | String | No | Opaque per-user identity string used to scope endpoint-scoped data to a specific end user. The caller must have the \`agents/endpoints/UserIdentityImpersonation/action\` RBAC permission. |
You can add these to a request with RequestOptions#addHeader
Response Body Schema
{
id: String (Required)
object: String (Required)
metadata (Required): {
String: String (Required)
}
created_at: long (Required)
}
Parameters:
Returns:
listAgents
public PagedIterable<AgentDetails> listAgents()
List agents Returns a paged collection of agent resources.
Returns:
listAgents
public PagedIterable<AgentDetails> listAgents(AgentKind kind, Integer limit, PageOrder order, String after, String before)
List agents Returns a paged collection of agent resources.
Parameters:
created_at timestamp of the objects. asc for ascending order anddesc
for descending order.
after is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include after=obj_foo in order to fetch the next page of the list.
before is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include before=obj_foo in order to fetch the previous page of the list.
Returns:
listAgents
public PagedIterable<BinaryData> listAgents(RequestOptions requestOptions)
List agents Returns a paged collection of agent resources.
Query Parameters
| ------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | Type | Required | Description |
| kind | String | No | Filter agents by kind. If not provided, all agents are returned. Allowed values: "prompt", "hosted", "workflow", "external", "voice". |
| limit | Integer | No | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. |
| order | String | No | Sort order by the \`created\_at\` timestamp of the objects. \`asc\` for ascending order and\`desc\` for descending order. Allowed values: "asc", "desc". |
| after | String | No | A cursor for use in pagination. \`after\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include after=obj\_foo in order to fetch the next page of the list. |
| before | String | No | A cursor for use in pagination. \`before\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include before=obj\_foo in order to fetch the previous page of the list. |
You can add these to a request with RequestOptions#addQueryParam
Response Body Schema
{
object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
id: String (Required)
name: String (Required)
state: String(enabled/disabled) (Required)
configuration_state: String(enabled/disabled) (Required)
state_source: String(agent_instance_identity/agent_blueprint) (Optional)
versions (Required): {
latest (Required): {
metadata (Required): {
String: String (Required)
}
object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
id: String (Required)
name: String (Required)
version: String (Required)
description: String (Optional)
created_at: long (Required)
definition (Required): {
kind: String(prompt/hosted/workflow/external/voice) (Required)
rai_config (Optional): {
rai_policy_name: String (Required)
invocations_moderation (Optional): {
input_content_type: String(json/text) (Optional)
output_content_type: String(json/text) (Optional)
response_mode: String(non_streaming/streaming/both) (Required)
input_paths (Optional): [
String (Optional)
]
output_paths (Optional): [
String (Optional)
]
stream_selectors (Optional): [
(Optional){
event_type: String (Required)
text_field: String (Optional)
}
]
}
}
}
draft: Boolean (Optional)
status: String(creating/active/failed/deleting/deleted) (Optional)
instance_identity (Optional): {
principal_id: String (Required)
client_id: String (Required)
status: String(active/disabled) (Optional)
}
blueprint (Optional): (recursive schema, see blueprint above)
blueprint_reference (Optional): {
type: String(ManagedAgentIdentityBlueprint) (Required)
}
agent_guid: String (Optional)
}
}
agent_endpoint (Optional): {
version_selector (Optional): {
version_selection_rules (Optional, Required on create): [
(Optional, Required on create){
type: String(FixedRatio) (Required)
agent_version: String (Optional, Required on create)
}
]
}
protocol_configuration (Optional): {
activity (Optional): {
enable_m365_public_endpoint: Boolean (Optional)
access_boundaries (Optional): [
String(read.1on1.developers/read.1on1.manager/read.1on1.allowlisted/read.1on1.tenant/write.1on1.developers/write.1on1.manager/write.1on1.allowlisted/write.1on1.tenant/read.group.developers/read.group.allowlisted/read.group.manager-invited/read.group.manager-present/read.group.tenant/write.group.developers/write.group.allowlisted/write.group.manager-invited/write.group.manager-present/write.group.tenant) (Optional)
]
}
responses (Optional): {
}
a2a (Optional): {
}
mcp (Optional): {
}
invocations (Optional): {
}
invocations_ws (Optional): {
}
}
authorization_schemes (Optional): [
(Optional){
type: String(Entra/BotService/BotServiceRbac/BotServiceTenant) (Required)
}
]
publish_approval_status: String(not_published/pending/approved/rejected/no_approval_needed) (Optional)
}
digital_worker_type: String(m365) (Optional)
instance_identity (Optional): (recursive schema, see instance_identity above)
blueprint (Optional): (recursive schema, see blueprint above)
blueprint_reference (Optional): (recursive schema, see blueprint_reference above)
agent_card (Optional): {
version: String (Optional, Required on create)
description: String (Optional)
skills (Optional, Required on create): [
(Optional, Required on create){
id: String (Optional, Required on create)
name: String (Optional, Required on create)
description: String (Optional)
tags (Optional): [
String (Optional)
]
examples (Optional): [
String (Optional)
]
}
]
}
}
Parameters:
Returns:
listAgentVersions
public PagedIterable<AgentVersionDetails> listAgentVersions(String agentName)
List agent versions Returns a paged collection of versions for the specified agent.
Parameters:
Returns:
listAgentVersions
public PagedIterable<AgentVersionDetails> listAgentVersions(String agentName, Integer limit, PageOrder order, String after, String before, Boolean includeDrafts)
List agent versions Returns a paged collection of versions for the specified agent.
Parameters:
created_at timestamp of the objects. asc for ascending order anddesc
for descending order.
after is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include after=obj_foo in order to fetch the next page of the list.
before is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include before=obj_foo in order to fetch the previous page of the list.
false
if a value is not specified by the caller (only non-draft versions are returned).
Returns:
listAgentVersions
public PagedIterable<BinaryData> listAgentVersions(String agentName, RequestOptions requestOptions)
List agent versions Returns a paged collection of versions for the specified agent.
Query Parameters
| --------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | Type | Required | Description |
| limit | Integer | No | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. |
| order | String | No | Sort order by the \`created\_at\` timestamp of the objects. \`asc\` for ascending order and\`desc\` for descending order. Allowed values: "asc", "desc". |
| after | String | No | A cursor for use in pagination. \`after\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include after=obj\_foo in order to fetch the next page of the list. |
| before | String | No | A cursor for use in pagination. \`before\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include before=obj\_foo in order to fetch the previous page of the list. |
| include\_drafts | Boolean | No | (Preview) Whether to include draft versions in the listing. The service defaults to \`false\` if a value is not specified by the caller (only non-draft versions are returned). |
You can add these to a request with RequestOptions#addQueryParam
Response Body Schema
{
metadata (Required): {
String: String (Required)
}
object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
id: String (Required)
name: String (Required)
version: String (Required)
description: String (Optional)
created_at: long (Required)
definition (Required): {
kind: String(prompt/hosted/workflow/external/voice) (Required)
rai_config (Optional): {
rai_policy_name: String (Required)
invocations_moderation (Optional): {
input_content_type: String(json/text) (Optional)
output_content_type: String(json/text) (Optional)
response_mode: String(non_streaming/streaming/both) (Required)
input_paths (Optional): [
String (Optional)
]
output_paths (Optional): [
String (Optional)
]
stream_selectors (Optional): [
(Optional){
event_type: String (Required)
text_field: String (Optional)
}
]
}
}
}
draft: Boolean (Optional)
status: String(creating/active/failed/deleting/deleted) (Optional)
instance_identity (Optional): {
principal_id: String (Required)
client_id: String (Required)
status: String(active/disabled) (Optional)
}
blueprint (Optional): (recursive schema, see blueprint above)
blueprint_reference (Optional): {
type: String(ManagedAgentIdentityBlueprint) (Required)
}
agent_guid: String (Optional)
}
Parameters:
Returns:
listOptimizationCandidates
public PagedIterable<AgentOptimizationCandidate> listOptimizationCandidates(String jobId)
List candidates for an agent optimization job Lists candidates for the given optimization job with cursor pagination, including the original baseline and generated candidates. Each `output.mutations` item identifies a changed attribute by `type`; mutation `value` fields are omitted unless the client passes `expand=mutations`.
Parameters:
Returns:
listOptimizationCandidates
public PagedIterable<AgentOptimizationCandidate> listOptimizationCandidates(String jobId, List<AgentOptimizationCandidateExpand> expand, Integer limit, PageOrder order, String after, String before)
List candidates for an agent optimization job Lists candidates for the given optimization job with cursor pagination, including the original baseline and generated candidates. Each `output.mutations` item identifies a changed attribute by `type`; mutation `value` fields are omitted unless the client passes `expand=mutations`.
Parameters:
mutations to populate mutation value fields; omit to
receive mutation items containing only type. Additional expand keys may be added in future previews.
started_at timestamp.
Returns:
listOptimizationCandidates
public PagedIterable<BinaryData> listOptimizationCandidates(String jobId, RequestOptions requestOptions)
List candidates for an agent optimization job Lists candidates for the given optimization job with cursor pagination, including the original baseline and generated candidates. Each `output.mutations` item identifies a changed attribute by `type`; mutation `value` fields are omitted unless the client passes `expand=mutations`.
Query Parameters
| ------ | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | Type | Required | Description |
| expand | List<String> | No | Comma-separated list of expand keys. Pass \`mutations\` to populate mutation \`value\` fields; omit to receive mutation items containing only \`type\`. Additional expand keys may be added in future previews. In the form of "," separated string. |
| limit | Integer | No | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. |
| order | String | No | Sort order by the candidate \`started\_at\` timestamp. Allowed values: "asc", "desc". |
| after | String | No | Candidate-ID cursor identifying the last item from the previous page. |
| before | String | No | Candidate-ID cursor identifying the first item from the following page. |
You can add these to a request with RequestOptions#addQueryParam
Response Body Schema
{
candidate_id: String (Required)
job_id: String (Required)
name: String (Required)
status: String(generating/evaluating/completed/failed) (Required)
started_at: long (Required)
output (Optional): {
type: String(agent_optimization/prompt_optimization) (Required)
}
rationale: String (Optional)
agent_version: String (Optional)
evaluation (Optional): {
score: Double (Optional)
avg_tokens: Double (Optional)
avg_latency_ms: Long (Optional)
eval_id: String (Optional)
eval_run_id: String (Optional)
completed_at: Long (Optional)
}
promotion (Optional): {
promoted_at: long (Required)
promoted_agent (Required): {
type: String (Required)
name: String (Required)
version: String (Optional)
}
}
}
Parameters:
Returns:
listOptimizationJobs
public PagedIterable<AgentOptimizationJob> listOptimizationJobs()
List agent optimization jobs Lists optimization jobs with cursor pagination and optional status or agent name filters.
Returns:
listOptimizationJobs
public PagedIterable<AgentOptimizationJob> listOptimizationJobs(Integer limit, PageOrder order, String after, String before, JobStatus status, String agentName)
List agent optimization jobs Lists optimization jobs with cursor pagination and optional status or agent name filters.
Parameters:
created_at timestamp of the objects. asc for ascending order anddesc
for descending order.
after is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include after=obj_foo in order to fetch the next page of the list.
before is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include before=obj_foo in order to fetch the previous page of the list.
Returns:
listOptimizationJobs
public PagedIterable<BinaryData> listOptimizationJobs(RequestOptions requestOptions)
List agent optimization jobs Lists optimization jobs with cursor pagination and optional status or agent name filters.
Query Parameters
| ----------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | Type | Required | Description |
| limit | Integer | No | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. |
| order | String | No | Sort order by the \`created\_at\` timestamp of the objects. \`asc\` for ascending order and\`desc\` for descending order. Allowed values: "asc", "desc". |
| after | String | No | A cursor for use in pagination. \`after\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include after=obj\_foo in order to fetch the next page of the list. |
| before | String | No | A cursor for use in pagination. \`before\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include before=obj\_foo in order to fetch the previous page of the list. |
| status | String | No | Filter to jobs in this lifecycle state. Allowed values: "queued", "in\_progress", "succeeded", "failed", "cancelled". |
| agent\_name | String | No | Filter to jobs targeting this agent name. |
You can add these to a request with RequestOptions#addQueryParam
Response Body Schema
{
id: String (Required)
result (Optional): {
candidate_summary (Optional): {
completed_candidate_count: int (Required)
baseline_id: String (Optional)
best_id: String (Optional)
baseline_score: Double (Optional)
best_score: Double (Optional)
latest_promoted_candidate (Optional): {
promoted_at: long (Required)
promoted_agent (Required): {
type: String (Required)
name: String (Required)
version: String (Optional)
}
}
}
token_usage (Required): [
(Required){
stage: String(agent/evaluation/optimization) (Required)
model: String (Optional)
input_tokens: Long (Optional)
output_tokens: Long (Optional)
total_tokens: Long (Optional)
cached_tokens: Long (Optional)
reasoning_tokens: Long (Optional)
}
]
latency_metrics (Required): [
(Required){
stage: String(agent/evaluation/optimization) (Required)
model: String (Optional)
avg_latency_ms: long (Required)
call_count: long (Required)
}
]
termination_reason: String(completed/budget_exhausted/candidate_screening_stalled) (Optional)
}
status: String(queued/in_progress/succeeded/failed/cancelled) (Required)
error (Optional): {
code: String (Required)
message: String (Required)
param: String (Optional)
type: String (Optional)
misalignment (Optional): {
error_type: String(potentially_unintended_data_transfer/potentially_unintended_data_access/potentially_unintended_destructive_activity/other) (Optional)
detailed_explanation: String (Optional)
steer (Optional): {
message: String (Required)
}
}
details (Optional): [
(recursive schema, see above)
]
additionalInfo (Optional): {
String: BinaryData (Required)
}
debugInfo (Optional): {
String: BinaryData (Required)
}
}
display_name: String (Optional)
target_configuration (Optional): {
type: String(foundry_agent) (Required)
}
optimization_model_configuration (Required): {
model: String (Required)
}
optimization_configuration (Required): {
type: String(agent_optimization/prompt_optimization) (Required)
}
run_duration_ms: long (Required)
created_at: long (Required)
updated_at: long (Required)
warnings (Optional): [
String (Optional)
]
}
Parameters:
Returns:
listSessionFiles
public PagedIterable<SessionDirectoryEntry> listSessionFiles(String agentName, String sessionId)
List session files Returns files and directories at the specified path in the session sandbox. The response includes only the immediate children of the target directory and defaults to the session home directory when no path is supplied.
Parameters:
Returns:
listSessionFiles
public PagedIterable<BinaryData> listSessionFiles(String agentName, String sessionId, RequestOptions requestOptions)
List session files Returns files and directories at the specified path in the session sandbox. The response includes only the immediate children of the target directory and defaults to the session home directory when no path is supplied.
Query Parameters
| ------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | Type | Required | Description |
| path | String | No | The directory path to list, relative to the session home directory. Defaults to the home directory if not provided. |
| limit | Integer | No | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. |
| order | String | No | Sort order by the \`created\_at\` timestamp of the objects. \`asc\` for ascending order and\`desc\` for descending order. Allowed values: "asc", "desc". |
| after | String | No | A cursor for use in pagination. \`after\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include after=obj\_foo in order to fetch the next page of the list. |
| before | String | No | A cursor for use in pagination. \`before\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include before=obj\_foo in order to fetch the previous page of the list. |
You can add these to a request with RequestOptions#addQueryParam
Response Body Schema
{
name: String (Required)
size: long (Required)
is_directory: boolean (Required)
modified_time: long (Required)
}
Parameters:
Returns:
listSessionFiles
public PagedIterable<SessionDirectoryEntry> listSessionFiles(String agentName, String sessionId, String path, Integer limit, PageOrder order, String after, String before)
List session files Returns files and directories at the specified path in the session sandbox. The response includes only the immediate children of the target directory and defaults to the session home directory when no path is supplied.
Parameters:
created_at timestamp of the objects. asc for ascending order anddesc
for descending order.
after is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include after=obj_foo in order to fetch the next page of the list.
before is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include before=obj_foo in order to fetch the previous page of the list.
Returns:
listSessions
public PagedIterable<AgentSessionResource> listSessions(String agentName)
List sessions for an agent Returns a paged collection of sessions associated with the specified agent endpoint.
Parameters:
Returns:
listSessions
public PagedIterable<AgentSessionResource> listSessions(String agentName, Integer limit, PageOrder order, String after, String before)
List sessions for an agent Returns a paged collection of sessions associated with the specified agent endpoint.
Parameters:
created_at timestamp of the objects. asc for ascending order anddesc
for descending order.
after is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include after=obj_foo in order to fetch the next page of the list.
before is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include before=obj_foo in order to fetch the previous page of the list.
Returns:
listSessions
public PagedIterable<BinaryData> listSessions(String agentName, RequestOptions requestOptions)
List sessions for an agent Returns a paged collection of sessions associated with the specified agent endpoint.
Query Parameters
| ------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | Type | Required | Description |
| limit | Integer | No | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. |
| order | String | No | Sort order by the \`created\_at\` timestamp of the objects. \`asc\` for ascending order and\`desc\` for descending order. Allowed values: "asc", "desc". |
| after | String | No | A cursor for use in pagination. \`after\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include after=obj\_foo in order to fetch the next page of the list. |
| before | String | No | A cursor for use in pagination. \`before\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include before=obj\_foo in order to fetch the previous page of the list. |
You can add these to a request with RequestOptions#addQueryParam
Response Body Schema
{
agent_session_id: String (Required)
version_indicator (Required): {
type: String(version_ref) (Required)
}
status: String(creating/active/idle/updating/failed/deleting/deleted/expired) (Required)
created_at: long (Required)
last_accessed_at: long (Required)
expires_at: long (Required)
stopped_at: Long (Optional)
}
Parameters:
Returns:
promoteOptimizationCandidate
public AgentOptimizationCandidate promoteOptimizationCandidate(String jobId, String candidateId)
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.
Parameters:
Returns:
promoteOptimizationCandidateWithResponse
public Response<BinaryData> promoteOptimizationCandidateWithResponse(String jobId, String candidateId, RequestOptions requestOptions)
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.
Response Body Schema
{
candidate_id: String (Required)
job_id: String (Required)
name: String (Required)
status: String(generating/evaluating/completed/failed) (Required)
started_at: long (Required)
output (Optional): {
type: String(agent_optimization/prompt_optimization) (Required)
}
rationale: String (Optional)
agent_version: String (Optional)
evaluation (Optional): {
score: Double (Optional)
avg_tokens: Double (Optional)
avg_latency_ms: Long (Optional)
eval_id: String (Optional)
eval_run_id: String (Optional)
completed_at: Long (Optional)
}
promotion (Optional): {
promoted_at: long (Required)
promoted_agent (Required): {
type: String (Required)
name: String (Required)
version: String (Optional)
}
}
}
Parameters:
Returns:
publishAgentToMicrosoft365
public Microsoft365PublishResult publishAgentToMicrosoft365(PublishAgentToMicrosoft365Options options)
Publish an agent to Microsoft 365 Publishes a Foundry agent to Microsoft 365 / Microsoft Teams and returns the published title and Teams app ids.
Parameters:
Returns:
publishAgentToMicrosoft365WithResponse
public Response<BinaryData> publishAgentToMicrosoft365WithResponse(String agentName, BinaryData publishAgentToMicrosoft365Request, RequestOptions requestOptions)
Publish an agent to Microsoft 365 Publishes a Foundry agent to Microsoft 365 / Microsoft Teams and returns the published title and Teams app ids.
Request Body Schema
{
agentDisplayName: String (Optional)
botServiceArmId: String (Optional)
publishAsAutopilot: Boolean (Optional)
accessBoundaries (Optional): [
String(read.1on1.developers/read.1on1.manager/read.1on1.allowlisted/read.1on1.tenant/write.1on1.developers/write.1on1.manager/write.1on1.allowlisted/write.1on1.tenant/read.group.developers/read.group.allowlisted/read.group.manager-invited/read.group.manager-present/read.group.tenant/write.group.developers/write.group.allowlisted/write.group.manager-invited/write.group.manager-present/write.group.tenant) (Optional)
]
optionalPermissionScopes (Optional): [
(Optional){
resourceAppId: String (Required)
scopes (Required): [
String (Required)
]
}
]
publishScope: String(Personal/Shared/Tenant) (Required)
canRespondWithoutMention: Boolean (Optional)
appVersion: String (Optional)
shortDescription: String (Optional)
fullDescription: String (Optional)
developerName: String (Optional)
developerWebsiteUrl: String (Optional)
privacyUrl: String (Optional)
termsOfUseUrl: String (Optional)
colorIconBase64: String (Optional)
outlineIconBase64: String (Optional)
}
Response Body Schema
{
titleId: String (Optional)
teamsAppId: String (Optional)
}
Parameters:
Returns:
stopSession
public void stopSession(String agentName, String sessionId)
Stop a session Terminates the specified hosted agent session and returns 204 No Content when the request succeeds.
Parameters:
stopSessionWithResponse
public Response<Void> stopSessionWithResponse(String agentName, String sessionId, RequestOptions requestOptions)
Stop a session Terminates the specified hosted agent session and returns 204 No Content when the request succeeds.
Parameters:
Returns:
updateAgentDetails
public AgentDetails updateAgentDetails(String agentName, UpdateAgentDetailsOptions patchAgentObjectRequest)
Update an agent endpoint Applies a merge-patch update to the specified agent endpoint configuration.
Parameters:
Returns:
updateAgentDetailsWithResponse
public Response<BinaryData> updateAgentDetailsWithResponse(String agentName, BinaryData patchAgentObjectRequest, RequestOptions requestOptions)
Update an agent endpoint Applies a merge-patch update to the specified agent endpoint configuration.
Request Body Schema
{
agent_endpoint (Optional): {
version_selector (Optional): {
version_selection_rules (Optional, Required on create): [
(Optional, Required on create){
type: String(FixedRatio) (Required)
agent_version: String (Optional, Required on create)
}
]
}
protocol_configuration (Optional): {
activity (Optional): {
enable_m365_public_endpoint: Boolean (Optional)
access_boundaries (Optional): [
String(read.1on1.developers/read.1on1.manager/read.1on1.allowlisted/read.1on1.tenant/write.1on1.developers/write.1on1.manager/write.1on1.allowlisted/write.1on1.tenant/read.group.developers/read.group.allowlisted/read.group.manager-invited/read.group.manager-present/read.group.tenant/write.group.developers/write.group.allowlisted/write.group.manager-invited/write.group.manager-present/write.group.tenant) (Optional)
]
}
responses (Optional): {
}
a2a (Optional): {
}
mcp (Optional): {
}
invocations (Optional): {
}
invocations_ws (Optional): {
}
}
authorization_schemes (Optional): [
(Optional){
type: String(Entra/BotService/BotServiceRbac/BotServiceTenant) (Required)
}
]
publish_approval_status: String(not_published/pending/approved/rejected/no_approval_needed) (Optional)
}
agent_card (Optional): {
version: String (Optional, Required on create)
description: String (Optional)
skills (Optional, Required on create): [
(Optional, Required on create){
id: String (Optional, Required on create)
name: String (Optional, Required on create)
description: String (Optional)
tags (Optional): [
String (Optional)
]
examples (Optional): [
String (Optional)
]
}
]
}
}
Response Body Schema
{
object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
id: String (Required)
name: String (Required)
state: String(enabled/disabled) (Required)
configuration_state: String(enabled/disabled) (Required)
state_source: String(agent_instance_identity/agent_blueprint) (Optional)
versions (Required): {
latest (Required): {
metadata (Required): {
String: String (Required)
}
object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
id: String (Required)
name: String (Required)
version: String (Required)
description: String (Optional)
created_at: long (Required)
definition (Required): {
kind: String(prompt/hosted/workflow/external/voice) (Required)
rai_config (Optional): {
rai_policy_name: String (Required)
invocations_moderation (Optional): {
input_content_type: String(json/text) (Optional)
output_content_type: String(json/text) (Optional)
response_mode: String(non_streaming/streaming/both) (Required)
input_paths (Optional): [
String (Optional)
]
output_paths (Optional): [
String (Optional)
]
stream_selectors (Optional): [
(Optional){
event_type: String (Required)
text_field: String (Optional)
}
]
}
}
}
draft: Boolean (Optional)
status: String(creating/active/failed/deleting/deleted) (Optional)
instance_identity (Optional): {
principal_id: String (Required)
client_id: String (Required)
status: String(active/disabled) (Optional)
}
blueprint (Optional): (recursive schema, see blueprint above)
blueprint_reference (Optional): {
type: String(ManagedAgentIdentityBlueprint) (Required)
}
agent_guid: String (Optional)
}
}
agent_endpoint (Optional): {
version_selector (Optional): {
version_selection_rules (Optional, Required on create): [
(Optional, Required on create){
type: String(FixedRatio) (Required)
agent_version: String (Optional, Required on create)
}
]
}
protocol_configuration (Optional): {
activity (Optional): {
enable_m365_public_endpoint: Boolean (Optional)
access_boundaries (Optional): [
String(read.1on1.developers/read.1on1.manager/read.1on1.allowlisted/read.1on1.tenant/write.1on1.developers/write.1on1.manager/write.1on1.allowlisted/write.1on1.tenant/read.group.developers/read.group.allowlisted/read.group.manager-invited/read.group.manager-present/read.group.tenant/write.group.developers/write.group.allowlisted/write.group.manager-invited/write.group.manager-present/write.group.tenant) (Optional)
]
}
responses (Optional): {
}
a2a (Optional): {
}
mcp (Optional): {
}
invocations (Optional): {
}
invocations_ws (Optional): {
}
}
authorization_schemes (Optional): [
(Optional){
type: String(Entra/BotService/BotServiceRbac/BotServiceTenant) (Required)
}
]
publish_approval_status: String(not_published/pending/approved/rejected/no_approval_needed) (Optional)
}
digital_worker_type: String(m365) (Optional)
instance_identity (Optional): (recursive schema, see instance_identity above)
blueprint (Optional): (recursive schema, see blueprint above)
blueprint_reference (Optional): (recursive schema, see blueprint_reference above)
agent_card (Optional): {
version: String (Optional, Required on create)
description: String (Optional)
skills (Optional, Required on create): [
(Optional, Required on create){
id: String (Optional, Required on create)
name: String (Optional, Required on create)
description: String (Optional)
tags (Optional): [
String (Optional)
]
examples (Optional): [
String (Optional)
]
}
]
}
}
Parameters:
Returns:
updateAgentFromCode
public AgentDetails updateAgentFromCode(String agentName, String codeZipSha256, CreateAgentVersionFromCodeContent content)
Update a code-based agent Updates a code-based agent by uploading new code and creating a new version. If the code and definition are unchanged (matched by x-ms-code-zip-sha256 header), returns the existing version. The request body is multipart/form-data with a JSON metadata part and a binary code part (part order is irrelevant). Maximum upload size is 250 MB.
Parameters:
- Must start and end with alphanumeric characters,
- Can contain hyphens in the middle
- Must not exceed 63 characters.
Returns:
uploadSessionFile
public SessionFileWriteResult uploadSessionFile(String agentName, String sessionId, String path, BinaryData content)
Upload a session file Uploads binary file content to the specified path in the session sandbox. The service stores the file relative to the session home directory and rejects payloads larger than 50 MB.
Parameters:
Returns:
uploadSessionFileWithResponse
public Response<BinaryData> uploadSessionFileWithResponse(String agentName, String agentSessionId, String path, String filePath, RequestOptions requestOptions)
Upload a session file Uploads binary file content to the specified path in the session sandbox. The service stores the file relative to the session home directory and rejects payloads larger than 50 MB.
Header Parameters
| ----------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Name | Type | Required | Description |
| x-ms-user-isolation-key | String | No | Opaque per-user isolation key used to scope endpoint-scoped data (responses, conversations, sessions) to a specific end user. |
You can add these to a request with RequestOptions#addHeader
Request Body Schema
BinaryData
Response Body Schema
{
path: String (Required)
bytes_written: long (Required)
}
Parameters:
Returns:
uploadSessionFileWithResponse
public Response<BinaryData> uploadSessionFileWithResponse(String agentName, String sessionId, String path, BinaryData content, RequestOptions requestOptions)
Upload a session file Uploads binary file content to the specified path in the session sandbox. The service stores the file relative to the session home directory and rejects payloads larger than 50 MB.
Request Body Schema
BinaryData
Response Body Schema
{
path: String (Required)
bytes_written: long (Required)
}
Parameters:
Returns: